forked from NuQloud/nc-talk-ai
120 lines
6.3 KiB
Markdown
120 lines
6.3 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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.
|