Multiplayer agent harness for work.
Preserve concurrent guidance updates
Joshua France321b13dc7053
diff --git a/src/api/app-sessions.ts b/src/api/app-sessions.tsindex c36d870e6..95a3bab40 100644--- a/src/api/app-sessions.ts+++ b/src/api/app-sessions.ts@@ -1130,7 +1130,11 @@ export function createSessionMethods(try {await deps.config.refreshScope(scopeIdValue);snapshot = await deps.config.captureSoulSnapshot(scopeIdValue);- const version = await deps.config.setSoulLatest(scopeIdValue, content, actorId);+ const version =+ opts?.expectedVersion === undefined+ ? await deps.config.setSoulLatest(scopeIdValue, content, actorId)+ : await deps.config.setSoulIfVersion(scopeIdValue, opts.expectedVersion, content, actorId);+ if (version === null) throw new Error("Guidance changed; read it and retry the edit.");deps.auditLog.record({at: Date.now(),principalId: actorId,@@ -1141,6 +1145,7 @@ export function createSessionMethods(return version;} catch (error) {if (snapshot !== undefined) deps.config.restoreSoulCacheSnapshot(scopeIdValue, snapshot);+ if (opts?.expectedVersion !== undefined) await deps.config.refreshScope(scopeIdValue);throw error;}};diff --git a/src/api/app-types.ts b/src/api/app-types.tsindex deea51b4e..2db10afdc 100644--- a/src/api/app-types.ts+++ b/src/api/app-types.ts@@ -430,7 +430,7 @@ export interface App {scopeId: ScopeId,content: string,actorId: string,- opts?: { allowSharedScope?: boolean },+ opts?: { allowSharedScope?: boolean; expectedVersion?: number },): Promise<number>;createCron(input: CreateCronInput): Promise<Cron>;getCron(id: string): Promise<Cron | null>;diff --git a/src/api/control-service.ts b/src/api/control-service.tsindex be4505db9..d5d89fb45 100644--- a/src/api/control-service.ts+++ b/src/api/control-service.ts@@ -172,6 +172,7 @@ export interface ControlService {writeSoul(content: string,claims: CapabilityClaims,+ expectedVersion?: number,): Promise<ControlOk<{ version: number }> | ControlErr<"soul_update_denied">>;shareArtifact(req: ShareArtifactRequest, claims: CapabilityClaims): Promise<ShareArtifactResult>;}@@ -862,10 +863,11 @@ export function createControlService(app: App, scheduler?: Scheduler, admin?: Adreturn { effectiveSoul, soul, soulVersion };},- async writeSoul(content, capability) {+ async writeSoul(content, capability, expectedVersion) {try {const version = await app.updateSoul(capability.scopeId, content, capability.actorId, {allowSharedScope: true,+ expectedVersion,});return { ok: true, version };} catch (e) {diff --git a/src/core/orchestrator/surface-tools.ts b/src/core/orchestrator/surface-tools.tsindex 9182efc35..74537458c 100644--- a/src/core/orchestrator/surface-tools.ts+++ b/src/core/orchestrator/surface-tools.ts@@ -28,7 +28,7 @@ import type {} from "../../tools/primitives.ts";import { collectBlob, MAX_BLOB_BYTES, type BlobTransferStore } from "../../persistence/blob-transfer.ts";import { collectNamedOutbound, type ArtifactRegistration } from "../attachments.ts";-import { parseBotLedger, type BotPolicy } from "../../surface-cache/channel-policy-store.ts";+import { parseBotLedger, type BotPolicy, type ChannelPolicy } from "../../surface-cache/channel-policy-store.ts";import { isoFromTs } from "../../util/message-tag.ts";import { errMessage } from "../../util/errors.ts";import { adminSessionUrl } from "../../util/admin-links.ts";@@ -493,7 +493,12 @@ export function createSurfaceToolDeps(ctx: SurfaceToolsContext): SurfaceToolDeps...(p?.ambientEnabled !== undefined ? { ambientEnabled: p.ambientEnabled } : {}),};},- setStandingOrder: async (orders: string, bots?: Record<string, BotPolicy>, ambientEnabled?: boolean | null) => {+ setStandingOrder: async (+ orders: string | undefined,+ bots?: Record<string, BotPolicy>,+ ambientEnabled?: boolean | null,+ expectedOrders?: string,+ ) => {if (!deps.channelPolicy) return { ok: false, message: "standing orders aren't available on this turn" };if (conversation.kind === "dm" || !conversation.channelRef)return { ok: false, message: "standing orders are per-channel — you can only set one from inside a channel." };@@ -503,12 +508,18 @@ export function createSurfaceToolDeps(ctx: SurfaceToolsContext): SurfaceToolDepsif ("error" in parsed) return { ok: false, message: parsed.error };parsedBots = parsed.bots;}- const p = await deps.channelPolicy.set(conversation.channelRef, orders, {- setBy: actor.id,- bots: parsedBots,- sessionId: session.id,- ambientEnabled,- });+ let p: ChannelPolicy;+ try {+ p = await deps.channelPolicy.set(conversation.channelRef, orders, {+ setBy: actor.id,+ bots: parsedBots,+ sessionId: session.id,+ ambientEnabled,+ expectedOrders,+ });+ } catch (error) {+ return { ok: false, message: errMessage(error) };+ }deps.auditLog.record({at: Date.now(),principalId: actor.id,@@ -518,7 +529,7 @@ export function createSurfaceToolDeps(ctx: SurfaceToolsContext): SurfaceToolDeps});return {ok: true,- orders,+ orders: p.orders,...(p.bots && Object.keys(p.bots).length ? { bots: p.bots } : {}),...(p.ambientEnabled !== undefined ? { ambientEnabled: p.ambientEnabled } : {}),};diff --git a/src/harness/agent-tools.ts b/src/harness/agent-tools.tsindex 67d531025..f6bfc8acc 100644--- a/src/harness/agent-tools.ts+++ b/src/harness/agent-tools.ts@@ -2943,14 +2943,12 @@ export function createAgentTools(ref: ToolContextRef, opts?: AgentToolsOptions):(channel!.orders.trim() ? channel!.orders : "[no channel guidance set]") + ambient + ledger + note;return recordResult(callId, { tool: "guidance", scope, ok: true }, text(body));}- let orders = channel!.orders;+ let orders = typeof params.content === "string" ? params.content : undefined;if (params.action === "edit") {- const edited = applyEdit(orders);+ const edited = applyEdit(channel!.orders);if (!edited.ok) return editError(edited.message);orders = edited.next;- } else if (typeof params.content === "string") {- orders = params.content;- } else if (params.bots === undefined && params.ambientEnabled === undefined) {+ } else if (typeof orders !== "string" && params.bots === undefined && params.ambientEnabled === undefined) {return recordResult(callId,{ tool: "guidance", scope, error: "content, bots, or ambientEnabled required" },@@ -2960,7 +2958,12 @@ export function createAgentTools(ref: ToolContextRef, opts?: AgentToolsOptions):true,);}- const r = await tc.setStandingOrder(orders, params.bots, params.ambientEnabled);+ const r = await tc.setStandingOrder(+ orders,+ params.bots,+ params.ambientEnabled,+ params.action === "edit" ? channel!.orders : undefined,+ );if (!r.ok)return recordResult(callId, { tool: "guidance", scope, ok: false }, text(`[error] ${r.message}`), true);return recordResult(callId, { tool: "guidance", scope, ok: true }, text("[channel guidance updated]"));@@ -2985,12 +2988,14 @@ export function createAgentTools(ref: ToolContextRef, opts?: AgentToolsOptions):);}let content = params.content;+ let expectedVersion: number | undefined;if (params.action === "edit") {const current = tc.soulRead();if (isUnavailable(current)) return unavailable(callId, "guidance");const edited = applyEdit(current.soul ?? "");if (!edited.ok) return editError(edited.message);content = edited.next;+ expectedVersion = current.soulVersion;} else if (typeof content !== "string") {return recordResult(callId,@@ -2999,7 +3004,7 @@ export function createAgentTools(ref: ToolContextRef, opts?: AgentToolsOptions):true,);}- const r = await tc.soulWrite(content);+ const r = await tc.soulWrite(content, expectedVersion);if (isUnavailable(r)) return unavailable(callId, "guidance");if (!r.ok)return recordResult(callId, { tool: "guidance", scope, error: r.code }, text(`[error] ${r.message}`), true);diff --git a/src/surface-cache/channel-policy-store.ts b/src/surface-cache/channel-policy-store.tsindex eb4a52d96..d561898dd 100644--- a/src/surface-cache/channel-policy-store.ts+++ b/src/surface-cache/channel-policy-store.ts@@ -60,8 +60,14 @@ export interface ChannelPolicyStore {get(container: string): Promise<ChannelPolicy | null>;set(container: string,- orders: string,- opts?: { setBy?: string; bots?: Record<string, BotPolicy>; sessionId?: string; ambientEnabled?: boolean | null },+ orders: string | undefined,+ opts?: {+ setBy?: string;+ bots?: Record<string, BotPolicy>;+ sessionId?: string;+ ambientEnabled?: boolean | null;+ expectedOrders?: string;+ },): Promise<ChannelPolicy>;history(container: string, limit?: number): Promise<ChannelPolicyRevision[]>;list(): Promise<ChannelPolicy[]>;@@ -120,30 +126,42 @@ export function createPostgresChannelPolicyStore(connectionString: string): Chanconst now = Date.now();const rows = await q(`WITH up AS (+ ${+ opts?.expectedOrders !== undefined+ ? `UPDATE channel_policy SET orders = COALESCE($3, channel_policy.orders),+ bots = COALESCE($4::jsonb, channel_policy.bots),+ ambient_enabled = CASE WHEN $9 THEN $8::boolean ELSE channel_policy.ambient_enabled END,+ set_by = $5, updated_at = $6+ WHERE org_id = $1 AND container = $2 AND orders = $10+ RETURNING *`+ : `INSERT INTO channel_policy(org_id, container, orders, bots, ambient_enabled, set_by, updated_at)- VALUES ($1,$2,$3,COALESCE($4::jsonb,'{}'::jsonb),CASE WHEN $9 THEN $8::boolean END,$5,$6)- ON CONFLICT (org_id, container) DO UPDATE SET orders = EXCLUDED.orders,+ VALUES ($1,$2,COALESCE($3,''),COALESCE($4::jsonb,'{}'::jsonb),CASE WHEN $9 THEN $8::boolean END,$5,$6)+ ON CONFLICT (org_id, container) DO UPDATE SET orders = COALESCE($3, channel_policy.orders),bots = COALESCE($4::jsonb, channel_policy.bots),ambient_enabled = CASE WHEN $9 THEN $8::boolean ELSE channel_policy.ambient_enabled END,set_by = EXCLUDED.set_by, updated_at = EXCLUDED.updated_at- RETURNING *+ RETURNING *`+ }), hist AS (INSERT INTO channel_policy_history(org_id, container, orders, bots, ambient_enabled, set_by, session_id, created_at)- SELECT $1, $2, $3, up.bots, up.ambient_enabled, $5, $7, $6 FROM up+ SELECT $1, $2, up.orders, up.bots, up.ambient_enabled, $5, $7, $6 FROM up)SELECT * FROM up`,[orgId,container,- orders,+ orders ?? null,opts?.bots ? JSON.stringify(opts.bots) : null,opts?.setBy ?? null,now,opts?.sessionId ?? null,opts?.ambientEnabled ?? null,opts?.ambientEnabled !== undefined,+ ...(opts?.expectedOrders !== undefined ? [opts.expectedOrders] : []),],);+ if (!rows.length) throw new Error("Channel guidance changed; read it and retry the edit.");return row(rows[0]!);},async history(container, limit = HISTORY_DEFAULT_LIMIT) {@@ -170,12 +188,14 @@ export function createMemoryChannelPolicyStore(): ChannelPolicyStore {},async set(container, orders, opts) {const existing = policies.get(container);+ if (opts?.expectedOrders !== undefined && existing?.orders !== opts.expectedOrders)+ throw new Error("Channel guidance changed; read it and retry the edit.");const now = Date.now();const ambientEnabled =opts?.ambientEnabled === undefined ? existing?.ambientEnabled : (opts.ambientEnabled ?? undefined);const p: ChannelPolicy = {container,- orders,+ orders: orders ?? existing?.orders ?? "",bots: opts?.bots ?? existing?.bots ?? {},...(ambientEnabled !== undefined ? { ambientEnabled } : {}),...(opts?.setBy ? { setBy: opts.setBy } : {}),@@ -184,7 +204,7 @@ export function createMemoryChannelPolicyStore(): ChannelPolicyStore {policies.set(container, p);history.push({container,- orders,+ orders: p.orders,bots: p.bots,...(p.ambientEnabled !== undefined ? { ambientEnabled: p.ambientEnabled } : {}),...(opts?.setBy ? { setBy: opts.setBy } : {}),diff --git a/src/tools/primitives.ts b/src/tools/primitives.tsindex bc38819ab..524f4469f 100644--- a/src/tools/primitives.ts+++ b/src/tools/primitives.ts@@ -306,6 +306,7 @@ export interface ToolContext extends SurfaceToolDeps {soulRead(): { effectiveSoul: string; soul: string | null; soulVersion: number } | ControlUnavailable;soulWrite(content: string,+ expectedVersion?: number,): Promise<ControlOk<{ version: number }> | ControlErr<"soul_update_denied"> | ControlUnavailable>;shareArtifact(req: ShareArtifactRequest): Promise<ShareArtifactResult | ControlUnavailable>;}@@ -422,9 +423,10 @@ export interface SurfaceToolDeps {readFile(ref: string): Promise<SurfaceFileResult>;getStandingOrder(): Promise<SurfaceStandingOrderResult>;setStandingOrder(- orders: string,+ orders: string | undefined,bots?: Record<string, BotPolicy>,ambientEnabled?: boolean | null,+ expectedOrders?: string,): Promise<SurfaceStandingOrderResult>;}@@ -1380,9 +1382,9 @@ export function createToolContext(deps: ToolContextDeps): ToolContext {if (!deps.control || !deps.controlClaims) return CONTROL_UNAVAILABLE;return deps.control.readSoul(deps.controlClaims);},- soulWrite: (content) =>+ soulWrite: (content, expectedVersion) =>controlOp(- async (c, cl) => c.writeSoul(content, cl),+ async (c, cl) => c.writeSoul(content, cl, expectedVersion),(r) => r.ok,),shareArtifact: (req) =>@@ -1422,8 +1424,8 @@ export function createToolContext(deps: ToolContextDeps): ToolContext {readMembers: () => surfaceOp((s) => s.readMembers()),readFile: (ref) => surfaceOp((s) => s.readFile(ref)),getStandingOrder: () => surfaceOp((s) => s.getStandingOrder()),- setStandingOrder: (orders, bots, ambientEnabled) =>- surfaceOp((s) => s.setStandingOrder(orders, bots, ambientEnabled)),+ setStandingOrder: (orders, bots, ambientEnabled, expectedOrders) =>+ surfaceOp((s) => s.setStandingOrder(orders, bots, ambientEnabled, expectedOrders)),attach: (files) =>deps.attach ? deps.attach(files) : Promise.resolve({ ok: false as const, message: ATTACH_UNAVAILABLE_MESSAGE }),};diff --git a/test/agent-tools.test.ts b/test/agent-tools.test.tsindex c4683daa5..2fbfa9c2e 100644--- a/test/agent-tools.test.ts+++ b/test/agent-tools.test.ts@@ -347,8 +347,8 @@ function fakeToolContext(sink?: { lastExecOpts?: Parameters<ToolContext["executeasync getStandingOrder() {return { ok: true, orders: "" };},- async setStandingOrder(orders: string) {- return { ok: true, orders };+ async setStandingOrder(orders) {+ return { ok: true, orders: orders ?? "" };},mcpToolDefs() {return [];@@ -2400,7 +2400,7 @@ test("guidance reads and writes channel ambient replies without changing omitted},async setStandingOrder(orders, _bots, nextAmbientEnabled) {if (nextAmbientEnabled !== undefined) ambientEnabled = nextAmbientEnabled ?? undefined;- return { ok: true, orders, ...(ambientEnabled === undefined ? {} : { ambientEnabled }) };+ return { ok: true, orders: orders ?? "keep watch", ...(ambientEnabled === undefined ? {} : { ambientEnabled }) };},};@@ -2424,7 +2424,7 @@ test("guidance edit swaps one exact passage in either scope and refuses ambiguoureturn { ok: true, orders };},async setStandingOrder(next, bots, ambientEnabled) {- orders = next;+ orders = next ?? orders;setCalls.push({ bots, ambientEnabled });return { ok: true, orders };},diff --git a/test/control-tool-context.test.ts b/test/control-tool-context.test.tsindex 5da6a41a1..322c311a6 100644--- a/test/control-tool-context.test.ts+++ b/test/control-tool-context.test.ts@@ -13,6 +13,9 @@ import { CAPABILITY_TTL_MS, type CapabilityClaims } from "../src/auth/capabilityimport type { ToolLedger } from "../src/runs/tool-ledger.ts";import type { Sandbox, SandboxHandle } from "../src/sandbox/sandbox.ts";import { testConfig } from "./support/test-config.ts";+import { createAgentTools } from "../src/harness/agent-tools.ts";+import { createMemoryChannelPolicyStore } from "../src/surface-cache/channel-policy-store.ts";+import { createSurfaceToolDeps, type SurfaceToolsContext } from "../src/core/orchestrator/surface-tools.ts";const SECRET = "control-tool-ctx";const handle: SandboxHandle = { id: "h", rootDir: "/workspace" };@@ -151,6 +154,93 @@ test("createToolContext.soulWrite then soulRead reflect the new SOUL", async ()assert.equal((r as { soul: string | null }).soul, "Be brief.");});+for (const scope of ["conversation", "channel"] as const) {+ test(`concurrent guidance edits at ${scope} scope reject a stale replacement without losing the winner`, async () => {+ const { control } = build();+ const channelPolicy = createMemoryChannelPolicyStore();+ const surface = createSurfaceToolDeps({+ deps: { deliveries: {}, channelPolicy, auditLog: { record() {} } },+ input: { surfaceTools: true },+ actor: { id: "U1" },+ conversation: { kind: "channel", channelRef: "C1" },+ session: { id: "S1" },+ scopeId: "channel:C1",+ defaultDestination: {},+ } as unknown as SurfaceToolsContext)!;+ const ctx = ctxFor({ control, controlClaims: claims("U1"), surface });+ await ctx.soulWrite("First rule. Second rule.");+ await ctx.setStandingOrder("First rule. Second rule.");+ const entries: string[] = [];+ const tool = createAgentTools(+ {+ current: ctx,+ scopeLabel: scopeId("personal", "U1"),+ emit: (entry) => {+ entries.push(entry.type);+ },+ },+ { controlTools: true },+ ).find((t) => t.name === "guidance")!;+ const edit = (old: string, next: string) =>+ tool+ .execute(old, { action: "edit", scope, old, new: next }, undefined, undefined, {} as never)+ .then((result) => JSON.stringify(result));+ const results = await Promise.all([edit("First rule.", "First updated."), edit("Second rule.", "Second updated.")]);+ assert.equal(results.filter((result) => !result.includes("[error]")).length, 1);+ assert.equal(entries.filter((type) => type === "tool_result").length, 2);+ assert.match(+ results.find((result) => result.includes("[error]"))!,+ /changed/,+ );+ const current =+ scope === "conversation" ? control.readSoul(claims("U1")).soul : (await channelPolicy.get("C1"))!.orders;+ assert.ok(current === "First updated. Second rule." || current === "First rule. Second updated.");+ const retry = current.includes("First updated.")+ ? await edit("Second rule.", "Second updated.")+ : await edit("First rule.", "First updated.");+ assert.doesNotMatch(retry, /\[error\]/);+ const final =+ scope === "conversation" ? control.readSoul(claims("U1")).soul : (await channelPolicy.get("C1"))!.orders;+ assert.equal(final, "First updated. Second updated.");+ });+}++test("channel guidance metadata updates preserve intervening edits and initialize missing policies", async () => {+ const channelPolicy = createMemoryChannelPolicyStore();+ const surface = createSurfaceToolDeps({+ deps: { deliveries: {}, channelPolicy, auditLog: { record() {} } },+ input: { surfaceTools: true },+ actor: { id: "U1" },+ conversation: { kind: "channel", channelRef: "C1" },+ session: { id: "S1" },+ scopeId: "channel:C1",+ defaultDestination: {},+ } as unknown as SurfaceToolsContext)!;+ const ctx = ctxFor({ surface });+ const tool = createAgentTools({ current: ctx }, { controlTools: true }).find((t) => t.name === "guidance")!;+ const replace = (params: Record<string, unknown>) =>+ tool.execute("metadata", { action: "replace", scope: "channel", ...params }, undefined, undefined, {} as never);+ await replace({ ambientEnabled: true });+ assert.equal((await channelPolicy.get("C1"))!.orders, "");+ assert.equal((await channelPolicy.get("C1"))!.ambientEnabled, true);+ const read = ctx.getStandingOrder;+ ctx.getStandingOrder = async () => {+ const snapshot = await read();+ await surface.setStandingOrder("Concurrent edit.");+ return snapshot;+ };+ await replace({ ambientEnabled: false, bots: { news: { mode: "ignore" } } });+ const stored = (await channelPolicy.get("C1"))!;+ assert.equal(stored.orders, "Concurrent edit.");+ assert.equal(stored.ambientEnabled, false);+ assert.deepEqual(stored.bots, { news: { mode: "ignore" } });+ assert.equal((await channelPolicy.history("C1"))[0]!.orders, stored.orders);+ await replace({ content: "Explicit replacement." });+ assert.equal((await channelPolicy.get("C1"))!.orders, "Explicit replacement.");+ await replace({ content: 42, ambientEnabled: true });+ assert.equal((await channelPolicy.get("C1"))!.orders, "Concurrent edit.");+});+test("without control/controlClaims wired, every control method returns CONTROL_UNAVAILABLE", async () => {const ctx = ctxFor({});assert.deepEqual(await ctx.cronCreate({ schedule: { everyMs: 1000 }, action: "x" }), CONTROL_UNAVAILABLE);diff --git a/test/postgres-surface-cache.test.ts b/test/postgres-surface-cache.test.tsindex 3b298ed6b..570bc9cbe 100644--- a/test/postgres-surface-cache.test.ts+++ b/test/postgres-surface-cache.test.ts@@ -441,3 +441,37 @@ test("channel history includes broadcasts while exact roots exclude them", { skiawait cache.close();}});++test("pg channel guidance edits compare the stored text atomically across connections", { skip }, async () => {+ const left = createPostgresChannelPolicyStore(URL!);+ const right = createPostgresChannelPolicyStore(URL!);+ const initial = "First rule. Second rule.";+ try {+ await left.set("CAS", initial, { ambientEnabled: true, bots: { news: { mode: "ignore" } } });+ const attempts = await Promise.allSettled([+ left.set("CAS", "First updated. Second rule.", { expectedOrders: initial }),+ right.set("CAS", "First rule. Second updated.", { expectedOrders: initial }),+ ]);+ assert.equal(attempts.filter((result) => result.status === "fulfilled").length, 1);+ const rejected = attempts.find((result) => result.status === "rejected");+ assert.ok(rejected?.status === "rejected");+ assert.match(String(rejected.reason), /guidance changed/);+ assert.equal((await left.history("CAS")).length, 2);+ const current = (await right.get("CAS"))!;+ assert.equal(current.ambientEnabled, true);+ assert.deepEqual(current.bots, { news: { mode: "ignore" } });+ await right.set("CAS", "First updated. Second updated.", { expectedOrders: current.orders });+ assert.equal((await left.get("CAS"))!.orders, "First updated. Second updated.");+ await assert.rejects(left.set("CAS-missing", "new", { expectedOrders: "old" }), /guidance changed/);+ assert.equal(await right.get("CAS-missing"), null);+ await left.set("CAS", undefined, { ambientEnabled: false });+ assert.equal((await right.get("CAS"))!.orders, "First updated. Second updated.");+ assert.equal((await left.history("CAS"))[0]!.orders, "First updated. Second updated.");+ await right.set("CAS-new", undefined, { bots: { news: { mode: "ignore" } } });+ assert.equal((await left.get("CAS-new"))!.orders, "");+ await left.set("CAS", "replace");+ assert.equal((await right.get("CAS"))!.orders, "replace");+ } finally {+ await Promise.all([left.close(), right.close()]);+ }+});