diff --git a/README.md b/README.md index da2366e..1c166d5 100644 --- a/README.md +++ b/README.md @@ -81,7 +81,7 @@ Open it, review the proposed action, choose **Approve**, and confirm. ![Pending approval for Delete the staging cluster, marked high risk, with the exact action under review](docs/images/approval.png) **What you should see:** the approval becomes `approved`, the exact content you reviewed is sent to the agent once, and the task moves to -completed. The approval page shows "Delivered to the agent; task is now" followed by the task state, and **Audit** lists every step. +completed. The approval page shows "Delivered to the agent; task is now" followed by the task state, and **Administration → Audit trail** lists every step. ![The same approval after it was delivered once, with the task completed](docs/images/approval-delivered.png) diff --git a/docs/guides/configuration-recipes.md b/docs/guides/configuration-recipes.md index c4ea0e8..ac55562 100644 --- a/docs/guides/configuration-recipes.md +++ b/docs/guides/configuration-recipes.md @@ -124,7 +124,7 @@ curl -i http://localhost:3002/api/auth/session A `200` with `"mode":"development"` means you are signed in as the local administrator. Open `http://localhost:3002/agents`; the sample agent is listed. -Only one process may open the PGlite directory. Stop `npm run dev` before running a script against it with `--offline-pglite`. +Only one process may open the PGlite directory, and Taskbay refuses a second one with "already open in another process". Stop `npm run dev` before running a script against it with `--offline-pglite`. ## 3. Single server on PostgreSQL with OIDC diff --git a/docs/guides/find-and-steer-tasks-started-elsewhere.md b/docs/guides/find-and-steer-tasks-started-elsewhere.md index d3062f9..025f2fa 100644 --- a/docs/guides/find-and-steer-tasks-started-elsewhere.md +++ b/docs/guides/find-and-steer-tasks-started-elsewhere.md @@ -14,7 +14,7 @@ What Taskbay does, in one paragraph: it uses **the agent's own credential** to a ## Find a task and track it -1. Open **Agents**, then the agent. In the **Task discovery** card choose **Browse tasks**. +1. Choose **Find tasks** in the sidebar and pick the agent. (From the agent page, **Browse tasks** in the **Task discovery** card opens the same page.) 2. Narrow the list with **State** (for example *Needs input*) or **Context ID**. Each row shows the title or ID, the state, how long ago it changed and, in quotes, the first line of what the agent last said. 3. Choose **Track** on the task you want. The row now says **Tracked**; **Open** takes you to the task. If you know the ID, paste it under **Track by task ID** instead. diff --git a/docs/guides/teams-and-grants.md b/docs/guides/teams-and-grants.md index 8c0458b..bc63780 100644 --- a/docs/guides/teams-and-grants.md +++ b/docs/guides/teams-and-grants.md @@ -89,7 +89,7 @@ Use `"skillId": null` for the whole agent. For everyone, use `"subjectType": "or 2. Ask a team member to sign in and open **Agents**. They see `Billing agent` with the description `Restricted skill access` and only the `Refunds` skill. The other skills, and the agent's own description, are hidden. 3. When they start a task with that agent, the chat shows a **Skill** picker with only the granted skills. Taskbay sends the skill id to the agent in the skill-routing metadata. 4. Their task lists show only tasks recorded for that skill. -5. The **Audit** page records each change: `team.created`, `team.addTeamMember`, `access.granted`. +5. **Administration → Audit trail** records each change: `team.created`, `team.addTeamMember`, `access.granted`. Browsing an agent's tasks and tracking them need an `operate` grant on the **whole** agent (or the administrator role). A skill grant never allows it, and a person with only skill grants never sees tracked or discovered tasks ([Task discovery](connect-an-agent.md#task-discovery)). diff --git a/docs/guides/use-the-console.md b/docs/guides/use-the-console.md index aa4abca..ba002b3 100644 --- a/docs/guides/use-the-console.md +++ b/docs/guides/use-the-console.md @@ -16,7 +16,7 @@ The console is the web app you open in the browser. The sidebar lists its screen | Read agents, tasks, conversations and notifications | All agents | Granted agents | Granted agents | | Send messages, answer forms, cancel tasks | Yes | With an "operate" grant | No | | Add or remove agents | Yes | No | No | -| Organization-wide **Audit**, CSV export | Yes | No | No | +| Organization-wide **Audit trail**, CSV export | Yes | No | No | | Read one task's audit trail | Yes | With read access | With read access | | **Administration** (people, teams, agent access, policies) | Yes | Not shown | Not shown | diff --git a/docs/images/agents.png b/docs/images/agents.png index c16de69..b6935bf 100644 Binary files a/docs/images/agents.png and b/docs/images/agents.png differ diff --git a/docs/images/approval-delivered.png b/docs/images/approval-delivered.png index 019dd29..b610c58 100644 Binary files a/docs/images/approval-delivered.png and b/docs/images/approval-delivered.png differ diff --git a/docs/images/approval.png b/docs/images/approval.png index 65eb251..309bbc0 100644 Binary files a/docs/images/approval.png and b/docs/images/approval.png differ diff --git a/docs/images/audit.png b/docs/images/audit.png index 7e89118..df92fa9 100644 Binary files a/docs/images/audit.png and b/docs/images/audit.png differ diff --git a/docs/images/chat.png b/docs/images/chat.png index ace4845..1ba68ca 100644 Binary files a/docs/images/chat.png and b/docs/images/chat.png differ diff --git a/docs/images/flows.png b/docs/images/flows.png index e6bcefd..cd07854 100644 Binary files a/docs/images/flows.png and b/docs/images/flows.png differ diff --git a/docs/images/home.png b/docs/images/home.png index 1f5157a..3178828 100644 Binary files a/docs/images/home.png and b/docs/images/home.png differ diff --git a/docs/images/tasks.png b/docs/images/tasks.png index fcd5bf8..fbe92dc 100644 Binary files a/docs/images/tasks.png and b/docs/images/tasks.png differ diff --git a/docs/quickstart.md b/docs/quickstart.md index 6ac5e3f..eef6d1a 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -127,7 +127,7 @@ The full set of reviewer actions is in [Approvals and ownership](guides/approval - **Tasks** lists the task with its status timeline, history and identifiers. - The approval page lists the decision record and every revision. -- **Audit** (administrators only) lists each step. The approval page links to the trail for its task. +- **Administration → Audit trail** (administrators only) lists each step. The approval page links to the trail for its task. Everything above is stored in the database, not in the browser. With `npx` the state lives in the launcher's data directory (`~/.agent-taskbay` by default). From source it lives in `./.data/pglite` (database) and `./.data/artifacts` (binary content). The state survives a restart: `npm run verify:package` installs the packaged launcher, registers an agent, sends it a command, restarts, and checks that the agent and task are still there. @@ -136,7 +136,7 @@ Everything above is stored in the database, not in the browser. With `npx` the s Real agents are often driven by more than one system. The `automation` sample agent plays that: it already has a task, "Rotate staging credentials", waiting for an answer, as if a pipeline had started it. 1. In **Agents**, choose **Add agent**, paste `http://127.0.0.1:4010/automation/card.json`, then **Fetch Agent Card**, **Continue** and **Connect**. -2. Open the agent and choose **Browse tasks**. You see two tasks, with the agent's question in quotes: "Which environment should I rotate?". Nothing has been stored yet. +2. Choose **Find tasks** in the sidebar and pick the **Automation fixture** agent (or open the agent and choose **Browse tasks**). You see two tasks, with the agent's question in quotes: "Which environment should I rotate?". Nothing has been stored yet. 3. Choose **Track** on "Rotate staging credentials". The row says **Tracked**; choose **Open**. 4. Open the task in chat and reply `staging`. The task completes ("Done. Rotated staging."). @@ -152,7 +152,7 @@ How it works, who may do this and how to switch it off: [Find and steer tasks st | The error says the target is not in the allowlist, or blocked | Production builds only reach exact origins in `A2A_ALLOWED_AGENT_ORIGINS`, and block private addresses unless `A2A_ALLOW_PRIVATE_NETWORKS=true`. The launcher sets the private-network option for you in local mode. | See [Connect an agent](guides/connect-an-agent.md#when-it-fails). | | `Agent Taskbay is already running for (pid ...)` | A second launcher on the same data directory. The embedded database allows one owner. | Stop the first process or pass `--data-dir`. | | "There is no production build." | The launcher was run from a checkout without a build. | Run `npm run build` first, or use `npx agent-taskbay`. | -| Database error when starting a second `npm run dev` or script against the same `.data` | PGlite has a single owner process. | Stop the other process. CLIs that touch the database need `--offline-pglite` while it is stopped. | +| `The embedded database in is already open in another process` when starting a second `npm run dev` or running a script against the same `.data` | PGlite has a single owner process, and Taskbay refuses a second one instead of sharing the folder. | Stop the other process. CLIs that touch the database need `--offline-pglite` while it is stopped. See [Development setup](contributing/development.md#where-the-database-is). | | **Browse tasks** is missing, or says task discovery is off | Your role cannot browse (viewers and skill-only grants cannot), or `A2A_TASK_DISCOVERY=off` | Local mode signs you in as an administrator, so check that variable. | | The approval never appears | The message did not contain "approve", so the showcase agent sent a form instead. | Use the exact message above, or open the task and choose **Request approval** to record one yourself. | | Approve is disabled or refused: "The requester cannot decide their own request." | Separation of duties is on by default. | Agent-opened requests have no requester, so this only hits approvals you created yourself. Ask another reviewer. | diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 7e54736..e4e16ca 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -151,7 +151,7 @@ npm run db:projections:rebuild -- --offline-pglite | Flag | Meaning | | --- | --- | -| `--offline-pglite` | Required when the profile is PGlite, because only one process may open the database. Stop the web server first. Not needed with PostgreSQL. | +| `--offline-pglite` | Required when the profile is PGlite, because only one process may open the database. Stop the web server first, or the command stops with "already open in another process". Not needed with PostgreSQL. | | `--organization ` | Organization to rebuild. Default: the organization with slug `local`. | | `--task ` | Rebuild only this local task ID. | diff --git a/docs/reference/compatibility.md b/docs/reference/compatibility.md index 96c32f0..a8017d0 100644 --- a/docs/reference/compatibility.md +++ b/docs/reference/compatibility.md @@ -25,7 +25,7 @@ the repository's own CI runs; nothing here is a claim about other versions or en | A2A SDK | `@a2a-js/sdk` `^1.3.0` (locked at `1.3.0`) | `package.json`, `package-lock.json` | | Web framework | Next.js `16.3.6`, React `19.3.0` | `package.json` | | ORM | MikroORM `7.2.3` | `package.json` | -| Operating systems | CI runs `ubuntu-latest` only. The launcher has code to open a browser on macOS, Windows and Linux; Windows is not tested. | `ci.yml`, `bin/agent-taskbay.mjs` | +| Operating systems | The full suite runs on `ubuntu-latest`. An informational `platforms` job also runs lint, unit tests, the embedded-database lock and people tests and the build on macOS and Windows; it may fail without blocking a merge, so treat those systems as unverified until it has been green. The launcher has code to open a browser on macOS, Windows and Linux. | `ci.yml`, `bin/agent-taskbay.mjs` | | Browsers | Not verified. The repository declares no browser support list and has no cross-browser test suite. | `package.json` | `npm run check` is what CI runs: lint, unit tests, database tests (PGlite, plus PostgreSQL when `A2A_TEST_POSTGRES_URL` is set), migrations, schema-drift check, production build, and the HTTP diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md index feebefc..65054bc 100644 --- a/docs/reference/glossary.md +++ b/docs/reference/glossary.md @@ -83,6 +83,9 @@ A rule that gives a subject `read` or `operate` permission on one agent (agent g ## I to P +**Identifier (ID)**\ +A value that names one thing. The console labels each one (Task ID, Context ID, Message ID, Artifact ID, Referenced task, Call ID, Taskbay ID, Approval ID, Command ID, Digest), says whether the A2A protocol defines it or only Taskbay keeps it, and offers a copy icon. See [Identifiers](../guides/use-the-console.md#identifiers). + **Inbox**\ One list of the tasks and approvals you may read, across agents. Its views are **Needs you** (the default), **Mine**, **Overdue**, **Active**, **Done** and **All**, with **Show** and **Risk** filters. See [Approvals and ownership](../guides/approvals-and-ownership.md#find-work-the-inbox). diff --git a/docs/security/threat-model.md b/docs/security/threat-model.md index 46ed6d3..1ee1056 100644 --- a/docs/security/threat-model.md +++ b/docs/security/threat-model.md @@ -34,6 +34,8 @@ Each row names the control and where it is exercised. "Evidence" points at tests | Restarting an instruction exposes private artifact URLs or loses file inputs | Before cancellation, the browser restores bytes using the existing authenticated artifact download route and its current task grants. External URLs remain references; restored input is bounded by the command body limit. Missing or unauthorized files stop the restart before cancellation. | `restart-task.test.ts`, `verify-steering-http.mjs`, and existing artifact-access HTTP tests. No new artifact endpoint or credentials are exposed. | | Cross-tenant data bleed | The organization comes from the local membership, carried per request in async-local storage, not from request input. | `scoped-security.db.test.ts`: foreign tasks, commands, content and artifacts are denied. | | Cross-site command submission | Exact `Origin` match and `Sec-Fetch-Site` rejection on state-changing requests. Reads do not submit commands. | Wrong or missing `Origin` is rejected in the production HTTP run. In development, loopback aliases on the same port are accepted. | +| An administrator account is misused to add people, raise roles or lock the organization out | Adding, changing and deactivating people are administrator-only API actions (`provisionMember`, `changeRole`, `deactivateMember`, `reactivateMember`). Adding uses the configured OIDC issuer and an exact subject, never a browser-supplied issuer. An administrator cannot change or deactivate their own membership, so one always remains. Deactivation deletes the person's sessions at once. Every change is audited with the actor (`member.*`). | `people.db.test.ts` covers the self-change guard, session removal, cross-organization refusal and audit. Local development mode refuses `provisionMember`. An administrator can still promote another person to administrator by design. | +| Two processes open the same embedded database and corrupt it | PGlite has no lock of its own. Taskbay takes a `.lock` file for as long as a database is open and refuses a second live process; a lock from a dead process is taken over. A damaged folder fails the open with an actionable error and is never deleted or moved automatically. | `pglite-guard.db.test.ts`. A reused process number can show a false refusal; the message says to delete the lock file. PostgreSQL is not affected. | | Access without a grant; role escalation | Explicit grants to a member, team or the organization, for a whole agent or one skill. Viewers cannot operate even with an "operate" grant. Task queries are filtered in SQL before pagination. | Grant, disabled-team and revoke tests in `scoped-security.db.test.ts`. A provider "admin" claim cannot raise a viewer. Administrators have full organization access by design. | | A skill grant used to do unrestricted work | Skill-only sends need the agent to advertise and enforce the [skill routing extension](../reference/extensions/skill-routing.md). The server picks the skill, starts a new context and checks follow-ups. | Generic, private-context and hidden-reference sends are denied in tests. A grant does not constrain an agent that ignores the extension. Enable it only for agents you have reviewed. | | Credential theft from the database; substitution; use after revoke | Credentials are encrypted (JWE) with the organization and agent bound into the payload and are valid only for their configured origins. Key rotation is supported. Missing keys, tampering and revoked bindings fail closed. | `scoped-security.db.test.ts` on both database profiles: tampering, cross-organization resolve, rotation, revoke. Protecting the key ring on the host is an operator duty. |