nuqloud-ai/docs/NUQLOUD_TOOLS_PLAN.md

NuQloud-AI tools plan

Objective

NuQloud-AI ships first-party tools for managed NuQloud Nextcloud instances. They let a bot guide users and perform authorised work in Files, Calendar, Deck, Collectives, and installed NuQloud bridge apps. The model never receives passwords, app passwords, API tokens, or a caller ID it can choose.

Execution modes

User mode (default)

Tools act as the authenticated user who invoked the bot and can only access objects that user can already access. No user credential is stored by the app.

Agent workspace mode (opt-in)

Tools act as an administrator-configured nuqloud-ai account. Normal Nextcloud folder, calendar, board, collective, group, and sharing permissions limit that account. Credentials are encrypted at rest and excluded from API output, logs, and traces. This is not an administrator mode.

Agent-mode implementation design

Agent profiles will be stored separately from bot tool assignments. An administrator creates a profile with a fixed Nextcloud user ID, a labelled scope, and an encrypted app password. A bot assignment can reference only an administrator-created profile ID; it must never accept an arbitrary agent_user_id, password, or endpoint from a bot owner or model.

ExecutionContextResolver will resolve user mode by default and agent mode only for an enabled profile assigned to that bot. The resolved account then uses normal Nextcloud permissions. Files can use server APIs scoped to that account; Calendar mutation must use the account's CalDAV endpoint because the public Calendar API currently exposes creation/search but not update/delete. Credential decryption happens only immediately before the outbound CalDAV/OCS request and is never added to tool results, traces, or logs.

Agent-mode migrations will add: an encrypted agent-profile table, a profile-to-bot assignment reference, admin-only controller methods, and audit fields for execution mode/profile ID. The first rollout will expose one unprivileged nuqloud-ai profile per instance, with Files and Calendar scopes granted through ordinary Nextcloud shares/groups rather than administrator privileges.

Tool families and safeguards

Family	Scope	Safeguards
Files	CRUD, restore, sharing	revision checks; confirm deletes, public links, and permission escalation
Calendar	availability and event CRUD	timezone required; confirm attendee invitations and deletes
Deck	boards, stacks, cards, labels, comments	confirm deletions and cross-board moves
Collectives	pages, hierarchy, content	revision checks and destructive-action confirmation
NuQloud bridges	resources, publishing, mappings, messages	confirm publish, send, and removal actions

The target design has the server define execution mode, allowed resources, and confirmations per bot/tool assignment. Model arguments must not override those policies.

Initial implementation status

The first user-mode slice adds a bundled NuQloudToolProvider, trusted invoking-user context, Files CRUD plus direct local-user sharing, and Calendar list/search/availability/create tools. File and share deletion require explicit user confirmation recorded server-side and are marked destructive in the agent policy. Overwriting a file and elevating a share to edit access use the same workflow. The bot asks the same user to reply with a short affirmative such as yes in a later Talk message in the same bot and room within ten minutes. The confirmation is bound to a hash of the requested action and consumed once. Calendar event creation is available only on Nextcloud 31+ because it uses the public calendar event builder API. File restore, Calendar update/delete, agent credentials, Deck, Collectives, and bridge tools remain planned work.

All bundled schemas normalize empty properties maps as JSON objects ({}), not arrays ([]), for compatibility with strict OpenAI-compatible tool parsers. Talk's users/<uid> actor identifier is normalized to <uid> before Files, Calendar, Share, or confirmation APIs are called.

Continuation order

1. Add Files restore plus confirmed public-link and group-share support.
2. Add Calendar update/delete.
3. Add per-bot mode and resource-scope configuration, then agent credentials.
4. Add Deck, Collectives, and NuQloud bridge tool families behind capability checks, so standalone installs remain functional.

Deployment and testing handoff

1. Deploy the NuQloud-AI branch to the app directory named educai, then run the normal integration recreate/install workflow. The app ID stays educai; its displayed name is NuQloud-AI.
2. Enable the app and select the desired NuQloud tools in the bot's tool assignment screen. Bundled tools are intentionally not enabled for every bot automatically.
3. Test in user mode with a non-administrator account. Ask the bot to list a folder, read a small UTF-8 file, create, copy, move, and delete a test file; create, update, and remove a direct user share; then list calendars and create an event with explicit timezone offsets.
4. Confirm that the bot cannot read or modify another user's private files, cannot overwrite a file unless overwrite is explicitly requested, and does not advertise Calendar event creation on Nextcloud 30.
5. Do not configure an app password for user mode. Agent workspace mode is a later opt-in migration; create a dedicated unprivileged nuqloud-ai account only when that implementation lands.

From the Qortal-Nextcloud-Integration checkout on the target instance, use the no-TLS compose configuration, for example:

docker compose -f docker-compose.devprod.nossl.yml --env-file .env.devprod exec -T --user www-data app php occ app:enable educai
docker compose -f docker-compose.devprod.nossl.yml --env-file .env.devprod exec -T --user www-data app php occ upgrade
docker compose -f docker-compose.devprod.nossl.yml --env-file .env.devprod exec -T --user www-data app php occ app:list --enabled | rg educai
docker compose -f docker-compose.devprod.nossl.yml --env-file .env.devprod exec -T --user www-data app php occ maintenance:repair

Then sign in as the test user, open NuQloud-AI's bot/tool configuration, and enable only the tools being tested. If the new tools are absent, confirm the deployed app revision first rather than reinstalling a different app source.