Multiplayer agent harness for work.
Allow live admin reads in Open conversations (#1358)
Joshua France4450bd7f1827
diff --git a/skills-seed/admin/SKILL.md b/skills-seed/admin/SKILL.mdindex 317c2f9d6..9b6fc536f 100644--- a/skills-seed/admin/SKILL.md+++ b/skills-seed/admin/SKILL.md@@ -12,12 +12,17 @@ store on every call, and every call is audited under their name. Two standing ru**confirm before any mutation** (state exactly what you'll change and where), and reportafterwards exactly what changed. Reads are fine to just do.-Three limits the API enforces (don't offer what it will refuse):+Limits the API enforces (don't offer what it will refuse):- Your token elevates only on turns the admin **started themselves** — on autonomousruns (crons, webhooks) the admin plane refuses it, whoever owns the run.- Reads that return private content — transcripts, files, notebooks, logs, another- scope's config — only work from a **DM** with the admin. Two exceptions: org-targeted+ scope's config — work from a **DM** with the admin, or from an **Open** conversation+ on a live admin turn. Organization, personal, and conversation sharing restrictions+ all apply; any Isolated setting keeps the DM requirement. The request uses the+ authenticated speaker's live admin grant, not another participant's authority.+ Open reads can expose private data to everyone in the conversation: retrieve and+ report only what the request needs. Two other exceptions: org-targetedmemory/config reads work anywhere (org content is ambient to every conversation), anda cron can carry **unattended read grants** (`unattendedGrants` on the cron:`admin.sessions.read`, `admin.audit.read`, `admin.metrics.read`, `admin.egress.read`,@@ -26,7 +31,8 @@ Three limits the API enforces (don't offer what it will refuse):exactly its own GET routes to that cron's autonomous fires, audited as the owner(re-checked live — revoking their admin grant closes it). Other mutations workanywhere; the room sees what changed, by design.-- **Grant changes (promote/revoke) are portal-only** through you — see below.+- **Grant changes (promote/revoke) and impersonation are portal-only** through you.+- Bulk configuration import is not supported. Use the individual configuration resources instead.All calls share one shape — only method/path/body vary:@@ -174,7 +180,7 @@ where the admin acts directly. If asked, point them there — don't try the APIrevoked). Say so; don't retry or work around it.- `403 … require a turn the admin started themselves` — this is an autonomous run(cron/webhook); admin actions only ride turns the admin personally initiated. Say so.-- `403 … returns private content — ask the agent in a DM` — you're in a shared room;+- `403 … returns private content — ask the agent in a DM` — the shared room does not have effective Open access for this live admin turn;tell the admin to ask again in a DM with you (or, for reads they want recurringon a schedule, to put an unattended read grant on a personal-scope cron — fromtheir DM, never from here).diff --git a/src/api/agent-api-catalog.ts b/src/api/agent-api-catalog.tsindex 17a1ec900..2f80cf6d7 100644--- a/src/api/agent-api-catalog.ts+++ b/src/api/agent-api-catalog.ts@@ -759,7 +759,7 @@ const FAMILIES: AgentApiFamily[] = [match: (_m, p) => p.startsWith("/v1/admin/"),when: (v) => v.isAdmin && livePersonCapability(v.claims),guidance:- "Admin plane: you act AS this org admin — live-authorized per call, audited under their name; confirm before any mutation (bodies/params in the admin skill). Enforced limits: content reads work only from a DM with the admin; bulk config imports also require a DM; other mutations work anywhere; admin grant changes are portal-only and refuse agent tokens.",+ "Admin plane: you act AS this org admin — live-authorized per call, audited under their name; confirm before any mutation (bodies/params in the admin skill). Enforced limits: content reads require a DM or effective Open sharing for the live admin (organization, personal, and conversation restrictions all apply); configuration mutations work anywhere; admin grant changes and impersonation are portal-only. Open admin reads can expose private data to the conversation; retrieve and report only what the request needs.",routes: [{ method: "GET", path: "/v1/admin/whoami", summary: "this user's admin status" },{@@ -771,7 +771,7 @@ const FAMILIES: AgentApiFamily[] = [method: "GET",path: "/v1/admin/scopes/:scopeId",summary:- "a scope's resolved config: command policy, SOUL, egress, flags, connectors, service credentials (non-org scopes: DM only)",+ "a scope's resolved config: command policy, SOUL, egress, flags, connectors, service credentials (non-org scopes: DM or effective Open sharing)",},{method: "PUT",@@ -782,41 +782,48 @@ const FAMILIES: AgentApiFamily[] = [{method: "GET|PUT",path: "/v1/admin/memory?scope=",- summary: "read or rewrite any scope's memory notebook (e.g. fix poisoned memory; non-org reads: DM only)",+ summary:+ "read or rewrite any scope's memory notebook (e.g. fix poisoned memory; non-org reads: DM or effective Open sharing)",},{method: "GET",path: "/v1/admin/sessions?scope=",summary:- "conversation metadata; /v1/admin/sessions/:id for a transcript and /:id/llm for captured prompts (DM only)",+ "conversation metadata; /v1/admin/sessions/:id for a transcript and /:id/llm for captured prompts (DM or effective Open sharing)",+ },+ {+ method: "GET",+ path: "/v1/admin/runs?scope=",+ summary: "queued / in-flight / recent runs (DM or effective Open sharing)",},- { method: "GET", path: "/v1/admin/runs?scope=", summary: "queued / in-flight / recent runs (DM only)" },{method: "GET",path: "/v1/admin/files?scope=",- summary: "document store listing; files/read?id= and files/download?id= for content (DM only)",+ summary:+ "document store listing; files/read?id= and files/download?id= for content (DM or effective Open sharing)",},{method: "GET",path: "/v1/admin/volumes?scope=",- summary: "a scope's computer/backup contents (paths and sizes; DM only)",+ summary: "a scope's computer/backup contents (paths and sizes; DM or effective Open sharing)",},{method: "GET",path: "/v1/admin/crons|deployments|skills?scope=",- summary: "artifacts by owning scope (DM only)",+ summary: "artifacts by owning scope (DM or effective Open sharing)",},{method: "GET",path: "/v1/admin/audit|errors|metrics|egress?scope=",- summary: "observability: audit log, error telemetry, turn metrics, outbound-destination log (logs: DM only)",+ summary:+ "observability: audit log, error telemetry, turn metrics, outbound-destination log (logs: DM or effective Open sharing)",},{ method: "GET", path: "/v1/admin/retention", summary: "org-wide usage and retention report" },{method: "GET",path: "/v1/admin/users",summary:- "org roster with admin status plus externalUsers (invited outside collaborators with role, expiry, status); /v1/admin/users/:id for one user's activity, conversations, and personal-scope artifacts (DM only)",+ "org roster with admin status plus externalUsers (invited outside collaborators with role, expiry, status); /v1/admin/users/:id for one user's activity, conversations, and personal-scope artifacts (DM or effective Open sharing)",},{method: "POST",@@ -838,7 +845,7 @@ const FAMILIES: AgentApiFamily[] = [{method: "GET",path: "/v1/admin/keychain",- summary: "person-owned keychain metadata, grants, and asks (DM only)",+ summary: "person-owned keychain metadata, grants, and asks (DM or effective Open sharing)",},],},diff --git a/src/api/routes/admin/scope-config.ts b/src/api/routes/admin/scope-config.tsindex d31e8abcf..7affaaa9b 100644--- a/src/api/routes/admin/scope-config.ts+++ b/src/api/routes/admin/scope-config.ts@@ -46,7 +46,7 @@ export async function putScopeConfig(ctx: ApiCtx): Promise<void> {const actor = await authorizeAdmin(ctx, targetScope);if (!actor) return;- if (["base-model", "runtime", "webui-models", "browse-model", "auto-flagger", "import"].includes(resource))+ if (["base-model", "runtime", "webui-models", "browse-model", "auto-flagger"].includes(resource))await deps.refreshModels?.();const withScopeMutationLock = async <T>(fn: () => Promise<T>): Promise<T> =>deps.advisoryLock ? deps.advisoryLock.withLock(`admin-governance:${targetScope}`, fn) : fn();diff --git a/src/api/server.ts b/src/api/server.tsindex 03bd27d32..a845566ce 100644--- a/src/api/server.ts+++ b/src/api/server.ts@@ -21,7 +21,7 @@ import { verifyCapabilityToken, CONTROL_PLANE_AUD, type CapabilityClaims } fromimport { verifyPortalIdentity, PORTAL_IDENTITY_HEADER, type PortalIdentity } from "../auth/portal-identity.ts";import { isUserScoped, userScopedField, assertedActor, isUnclassifiedWrite } from "./user-scoped-routes.ts";import { errMessage } from "../util/errors.ts";-import { parseScopeId } from "../types.ts";+import { parseScopeId, scopeId } from "../types.ts";import {armBodyDeadline,canonicalPayload,@@ -44,7 +44,13 @@ const safeDecode = (s: string): string => {}};-function capabilityAdminDenied(method: string, pathname: string, url: URL, claims: CapabilityClaims): string | null {+async function capabilityAdminDenied(+ method: string,+ pathname: string,+ url: URL,+ claims: CapabilityClaims,+ config: ServerDeps["config"],+): Promise<string | null> {if (method === "GET" && pathname === "/v1/admin/whoami") return null;if (claims.aud !== CONTROL_PLANE_AUD) return "admin routes require the per-turn agent token";if (!livePersonCapability(claims) && !unattendedAdminReadAllowed(method, pathname, claims)) {@@ -56,19 +62,16 @@ function capabilityAdminDenied(method: string, pathname: string, url: URL, claimif (pathname.startsWith("/v1/admin/impersonate")) {return "impersonating a user is portal-only — the agent cannot act as another person";}- if (- method === "PUT" &&- /^\/v1\/admin\/scopes\/[^/]+\/import$/.test(pathname) &&- parseScopeId(claims.scopeId).kind !== "personal"- ) {- return "bulk configuration imports may contain credentials — run them from a DM or the portal";- }if (method === "GET" && isAdminContentRead(pathname) && parseScopeId(claims.scopeId).kind !== "personal") {let target = "";if (pathname.startsWith("/v1/admin/scopes/"))target = safeDecode(pathname.slice("/v1/admin/scopes/".length).split("/")[0] ?? "");else if (pathname === "/v1/admin/memory") target = url.searchParams.get("scope") ?? "";- if (parseScopeId(target).kind !== "org") {+ if (+ parseScopeId(target).kind !== "org" &&+ (!livePersonCapability(claims) ||+ (await config?.resolveSharingPostureDurable(scopeId("personal", claims.actorId), claims.scopeId)) !== "open")+ ) {return "this admin read returns private content — ask the agent in a DM";}}@@ -239,7 +242,7 @@ async function gate(return null;}if (pathname.startsWith("/v1/admin/")) {- const denied = capabilityAdminDenied(method, pathname, url, capability);+ const denied = await capabilityAdminDenied(method, pathname, url, capability, deps.config);if (denied) {sendJson(res, 403, { error: "forbidden", message: denied });return null;diff --git a/src/core/orchestrator.ts b/src/core/orchestrator.tsindex e487f7fc1..5f65d2f2b 100644--- a/src/core/orchestrator.ts+++ b/src/core/orchestrator.ts@@ -1943,7 +1943,7 @@ export function createOrchestrator(deps: OrchestratorDeps): Orchestrator {(orgMemoryWrite? ', and for plain "remember this org-wide" requests the lighter path is `"scope":"org"` on the memory self-API (memory skill)': "") +- ". You're acting as them: confirm before any mutation, and say exactly what you changed. Hard limits the API enforces: private-content reads work only from a DM; admin grant changes are portal-only.";+ ". You're acting as them: confirm before any mutation, and say exactly what you changed. Hard limits the API enforces: private-content reads require a DM or an Open conversation on a live admin turn (organization, personal, and conversation sharing restrictions all apply); admin grant changes and impersonation are portal-only. Open admin reads can expose private data to everyone in the conversation: retrieve and report only what the request needs.";}if (deps.signingSecret && deps.apiBaseUrl && (deps.crons || deps.webhooks || deps.monitors)) {const nowMs = Date.now();diff --git a/test/admin-agent-capability.test.ts b/test/admin-agent-capability.test.tsindex 59497f924..5e5280175 100644--- a/test/admin-agent-capability.test.ts+++ b/test/admin-agent-capability.test.ts@@ -23,7 +23,7 @@ import { testConfig } from "./support/test-config.ts";const SECRET = "agent-admin-test-secret".repeat(3);const ORG = scopeId("org", "default-org");-function start() {+function start(withConfig = true) {const built = buildApp(testConfig({dataDir: mkdtempSync(join(tmpdir(), "admin-agent-cap-")),@@ -34,7 +34,10 @@ function start() {);void built.directory.replaceChannels([{ channelId: "C1", name: "agent-admin", isPrivate: false }],- [{ channelId: "C1", principalId: "admin-alice" }],+ [+ { channelId: "C1", principalId: "admin-alice" },+ { channelId: "C1", principalId: "U1" },+ ],);const keychain = createKeychain({creds: createMemoryMap(),@@ -45,7 +48,7 @@ function start() {const server = createServer(built.app, {admin: built.admin,memory: built.memory,- config: built.config,+ ...(withConfig ? { config: built.config } : {}),auditLog: built.auditLog,sessions: built.sessions,runs: built.runs,@@ -412,8 +415,8 @@ test("content reads need a DM-scoped token", async () => {headers: { "x-agent-capability": fromChannel, "content-type": "application/json" },body: JSON.stringify({}),});- assert.equal(importFromChannel.status, 403);- assert.match(((await importFromChannel.json()) as any).message, /credentials/);+ assert.equal(importFromChannel.status, 404);+ assert.match(((await importFromChannel.json()) as { message: string }).message, /unknown admin resource/);const ackPicksFromChannel = await fetch(`${s.base}/v1/admin/ack-emoji-picks`, {headers: { "x-agent-capability": fromChannel },});@@ -563,3 +566,145 @@ for (const [name, input, expected] of [}});}++for (const room of [scopeId("channel", "C1"), scopeId("group", "G1")]) {+ test(`Open admin reads and writes from ${room} preserve live authorization and posture vetoes`, async () => {+ const s = start();+ try {+ await s.built.directory.replaceGroups([+ { groupId: "G1", principalId: "admin-alice" },+ { groupId: "G1", principalId: "U1" },+ ]);+ await s.built.config.setSharingPosture(ORG, "open");+ const cap = await capFor("admin-alice", { scope: room });+ const headers = { "x-agent-capability": cap, "content-type": "application/json" };+ const personal = scopeId("personal", "admin-alice");+ const target = scopeId("personal", "U1");+ await s.built.memory.replace(target, "# Memory\n\n- private test sentinel");+ const path = `/v1/admin/memory?scope=${encodeURIComponent(target)}`;+ const read = () => fetch(`${s.base}${path}`, { headers });+ const response = await read();+ assert.equal(response.status, 200);+ assert.match(((await response.json()) as { content: string }).content, /private test sentinel/);+ const reads = (await s.built.auditLog.events()).filter((e) => e.action === "memory.read");+ assert.equal(reads.length, 1);+ assert.equal(reads[0]!.principalId, "admin-alice");+ assert.equal(reads[0]!.scopeLabel, target);+ for (const route of [`/v1/admin/sessions?scope=${target}`, "/v1/admin/keychain", `/v1/admin/scopes/${target}`]) {+ assert.equal((await fetch(`${s.base}${route}`, { headers })).status, 200, route);+ }+ const write = (token = cap) =>+ fetch(`${s.base}/v1/admin/scopes/${target}/soul`, {+ method: "PUT",+ headers: { ...headers, "x-agent-capability": token },+ body: JSON.stringify({ content: "Open admin configuration sentinel" }),+ });+ assert.equal((await write()).status, 200);+ assert.equal(await s.built.config.getSoul(target), "Open admin configuration sentinel");+ const writes = (await s.built.auditLog.events()).filter((e) => e.action === "soul.update");+ assert.equal(writes.length, 1);+ assert.equal(writes[0]!.principalId, "admin-alice");+ assert.equal(writes[0]!.scopeLabel, target);+ for (const veto of [ORG, personal, room]) {+ await s.built.config.setSharingPosture(veto, "isolated");+ assert.equal((await read()).status, 403, `${veto} vetoes Open on an existing token`);+ await s.built.config.setSharingPosture(veto, "open");+ assert.equal((await read()).status, 200);+ }+ for (const liveAuthor of [false, true]) {+ const token = await capFor("admin-alice", { scope: room, live: false, liveAuthor });+ assert.equal(+ (await fetch(`${s.base}${path}`, { headers: { "x-agent-capability": token } })).status,+ liveAuthor ? 200 : 403,+ "only a live human's authority may use Open",+ );+ assert.equal((await write(token)).status, liveAuthor ? 200 : 403);+ }+ const unattended = await capFor("admin-alice", {+ scope: room,+ live: false,+ grants: ["admin.sessions.read"],+ });+ assert.equal(+ (+ await fetch(`${s.base}/v1/admin/sessions`, {+ headers: { "x-agent-capability": unattended },+ })+ ).status,+ 403,+ "Open does not widen unattended grants",+ );+ for (const [method, route] of [+ ["POST", "/v1/admin/grants"],+ ["DELETE", `/v1/admin/grants/admin-bob?scope=${ORG}&role=org_admin`],+ ["POST", "/v1/admin/impersonate"],+ ]) {+ assert.equal(+ (+ await fetch(`${s.base}${route}`, {+ method,+ headers,+ body: "{}",+ })+ ).status,+ 403,+ `${route} retains its existing restriction`,+ );+ }+ const nonAdmin = await capFor("U1", { scope: room });+ assert.equal(+ (+ await fetch(`${s.base}${path}`, {+ headers: { "x-agent-capability": nonAdmin, "x-admin-actor": "admin-alice@default-org" },+ })+ ).status,+ 403,+ "Open and a spoofed header cannot grant admin authority",+ );+ assert.equal((await write(nonAdmin)).status, 403, "Open does not give members admin write access");+ await s.built.admin.revokeGrant({ id: "admin-bob", type: "internal" }, "admin-alice", ORG, "org_admin");+ assert.equal((await read()).status, 403, "revocation applies to an existing Open token");+ assert.equal((await write()).status, 403, "revocation also stops writes on an existing Open token");+ } finally {+ await s.close();+ }+ });+}++test("shared admin reads fail closed without a sharing config resolver", async () => {+ const s = start(false);+ try {+ await s.built.config.setSharingPosture(ORG, "open");+ const cap = await capFor("admin-alice", { scope: scopeId("channel", "C1") });+ const response = await fetch(`${s.base}/v1/admin/sessions`, { headers: { "x-agent-capability": cap } });+ assert.equal(response.status, 403);+ } finally {+ await s.close();+ }+});++for (const room of [scopeId("personal", "admin-alice"), scopeId("channel", "C1"), scopeId("group", "G1")]) {+ test(`retired bulk import is equally unsupported from ${room}`, async () => {+ const s = start();+ try {+ await s.built.directory.replaceGroups([+ { groupId: "G1", principalId: "admin-alice" },+ { groupId: "G1", principalId: "U1" },+ ]);+ const cap = await capFor("admin-alice", { scope: room });+ for (const posture of ["isolated", "open"] as const) {+ await s.built.config.setSharingPosture(ORG, posture);+ const response = await fetch(`${s.base}/v1/admin/scopes/${ORG}/import`, {+ method: "PUT",+ headers: { "x-agent-capability": cap, "content-type": "application/json" },+ body: JSON.stringify({ soul: "must not be imported" }),+ });+ assert.equal(response.status, 404, posture);+ assert.deepEqual(await response.json(), { error: "not_found", message: "unknown admin resource: import" });+ assert.notEqual(await s.built.config.getSoul(ORG), "must not be imported");+ }+ } finally {+ await s.close();+ }+ });+}diff --git a/test/agent-api-discovery.test.ts b/test/agent-api-discovery.test.tsindex 9ce3b7f9a..73a31dadb 100644--- a/test/agent-api-discovery.test.ts+++ b/test/agent-api-discovery.test.ts@@ -124,6 +124,8 @@ test("discovery for an org admin's LIVE turn includes the admin plane (live granassert.ok(p.includes("/v1/admin/users"));assert.ok(!p.includes("/v1/admin/grants"), "grant management is portal-only and must not be advertised");assert.ok(body.guidance.some((g: string) => g.includes("confirm before any mutation")));+ assert.match(JSON.stringify(body), /content reads require a DM or effective Open sharing for the live admin/);+ assert.doesNotMatch(JSON.stringify(body), /DM only|only from a DM|bulk config imports require/);assert.equal(p.filter((x: string) => x === "/v1/admin/whoami").length, 1, "whoami listed once, not duplicated");} finally {await s.close();@@ -236,6 +238,8 @@ test("discovery includes admin routes for a verified human thread reply", asyncassert.equal(p.filter((path) => path === "/v1/admin/whoami").length, 1);assert.equal(p.filter((path) => path === "/v1/admin/scopes").length, 1);assert.ok(body.guidance.some((g: string) => g.includes("confirm before any mutation")));+ assert.match(JSON.stringify(body), /content reads require a DM or effective Open sharing for the live admin/);+ assert.doesNotMatch(JSON.stringify(body), /DM only|only from a DM|bulk config imports require/);assert.ok(!body.guidance.some((g: string) => g.includes("This cron")));const member = await listApis(s.base, await capFor("U1", { liveAuthor: true }));assert.ok(!paths(member.body).includes("/v1/admin/scopes"));diff --git a/test/orchestrator.test.ts b/test/orchestrator.test.tsindex b01495e9a..1eedd1ccb 100644--- a/test/orchestrator.test.ts+++ b/test/orchestrator.test.ts@@ -1122,6 +1122,14 @@ test("an org admin's turn carries org-notebook write (token claim + prompt hint)adminTurn({ text: "!sysprompt", conversation: { kind: "dm", threadRef: "dm:admin-alice:t2" } }),);assert.match(adminPrompt.reply ?? "", /## Acting for an org admin/);+ assert.match(+ adminPrompt.reply ?? "",+ /private-content reads require a DM or an Open conversation on a live admin turn/,+ );+ assert.doesNotMatch(+ adminPrompt.reply ?? "",+ /private-content reads work only from a DM|bulk configuration imports require/,+ );assert.match(adminPrompt.reply ?? "", /"scope":"org"/, "the org-notebook option rides in the admin hint");captured = undefined;