Skip to content

armgit / qm

Public Imported from GitHub
0

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.md
index 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 report
afterwards 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 autonomous
runs (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-targeted
memory/config reads work anywhere (org content is ambient to every conversation), and
a 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 work
anywhere; 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 API
revoked). 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 recurring
on a schedule, to put an unattended read grant on a personal-scope cron — from
their DM, never from here).
diff --git a/src/api/agent-api-catalog.ts b/src/api/agent-api-catalog.ts
index 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.ts
index 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.ts
index 03bd27d32..a845566ce 100644
--- a/src/api/server.ts
+++ b/src/api/server.ts
@@ -21,7 +21,7 @@ import { verifyCapabilityToken, CONTROL_PLANE_AUD, type CapabilityClaims } from
import { 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, claim
if (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.ts
index 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.ts
index 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.ts
index 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 gran
assert.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", async
assert.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.ts
index 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;