@zgeoff/atc 2.41.0 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zgeoff/atc",
-  "version": "2.41.0",
+  "version": "3.0.0",
   "description": "Terminal control tower for coding-agent sessions",
   "homepage": "https://github.com/zgeoff/atc#readme",
   "bugs": "https://github.com/zgeoff/atc/issues",

package/src/federation/id-rules.ts

@@ -38,6 +38,7 @@ export const ID_RULES: Readonly<Record<string, ReadonlyMap<string, IDRule>>> = {
   'session.update': new Map(),
   'session.kill': new Map(),
   'session.ack': new Map(),
+  'session.forget': new Map([['confirmToken', 'opaque']]),
   'session.list': buildPrefixedRules('sessions[].', DESCRIPTOR_RULES),
   'session.spawn': buildPrefixedRules('session.', DESCRIPTOR_RULES),
   'session.get': buildPrefixedRules('session.', DESCRIPTOR_RULES),
@@ -68,13 +69,15 @@ export const ID_RULES: Readonly<Record<string, ReadonlyMap<string, IDRule>>> = {
 /**
  * The rule for every id-bearing field of an error's `data`, whatever the
  * method: `effectRef` holds the session or message an uncertain or
- * conflicting keyed request made.
+ * conflicting keyed request made, and `host` holds the session that owns
+ * a host a refusal concerns.
  */
 export const ERROR_DATA_RULES: ReadonlyMap<string, IDRule> = new Map([
   ['effectRef', 'id'],
   ['session', 'id'],
   ['message', 'id'],
   ['parent', 'id'],
+  ['host', 'id'],
 ]);
 
 function buildPrefixedRules(

package/src/mcp/mcp-tools.ts

@@ -474,6 +474,31 @@ export const MCP_TOOLS: readonly MCPToolDefinition[] = [
     description: 'Kill a session. A second kill on a dead session removes it from the list.',
     inputSchema: SESSION_INPUT,
   },
+  {
+    name: 'atc_session_forget',
+    annotations: DESTRUCTIVE,
+    scope: 'kill',
+    description:
+      'Forget a session for good: it leaves the list. A live local sub-session of the session is not stopped: it stays alive and moves to the top level. On a target that can destroy its host (an imp), the first call changes nothing and returns { confirmToken, expiresAt }, a token good for 60 seconds; a second call with that token destroys the host and returns { forgotten: true, destroyed: true }, except that a sub-session on the imp host of its parent does not destroy that host and returns destroyed: false. On any other target one call forgets and returns { forgotten: true, destroyed: false }. A live session is refused unless stop is true, which stops it as part of the forget. A pinned session, or a sub-session of a pinned session, is refused: unpin it with atc_session_update first.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        session: { type: 'string', description: 'The atc session id' },
+        confirmToken: {
+          type: 'string',
+          minLength: 1,
+          description: 'The token an earlier call on the same session returned',
+        },
+        stop: {
+          type: 'boolean',
+          description: 'Stop the session when it is live; omit or false refuses a live session',
+        },
+      },
+      required: ['session'],
+      additionalProperties: false,
+    },
+    requires: { tool: 'session.forget' },
+  },
   {
     name: 'atc_session_ack',
     annotations: ADDITIVE,

package/src/mcp/require-daemon-features.ts

@@ -10,7 +10,7 @@ const FEATURE_USES: Readonly<Record<DaemonFeature, string>> = {
   'message.idempotency': "atc_session_message's idempotencyKey",
   'message.turn': "atc_message_get's turn and answeredWith",
   'message.wait': "atc_message_get's waitMs",
-  'session.forget': 'session.forget',
+  'session.forget': 'atc_session_forget',
   'session.locator': "a session's locator",
   'session.submit': 'atc_session_input',
   'spawn.idempotency': "atc_session_spawn's idempotencyKey",

package/src/mcp/run-tool.ts

@@ -146,6 +146,22 @@ export function runTool(
 
       return { text: 'killed', structured: null };
     })
+    .with('atc_session_forget', async () => {
+      await requireForgettable(caller, args['session'], args['stop'] === true);
+
+      const ok = await caller.sendRequest(
+        'session.forget',
+        {
+          session: args['session'],
+          ...(typeof args['confirmToken'] === 'string'
+            ? { confirmToken: args['confirmToken'] }
+            : {}),
+        },
+        ['session.forget'],
+      );
+
+      return buildObjectResult(ok);
+    })
     .with('atc_session_ack', async () => {
       await caller.sendRequest('session.ack', { session: args['session'] });
 
@@ -269,6 +285,37 @@ function buildObjectResult(value: unknown): ToolResult {
   };
 }
 
+// A forget is for good, so it reads the session first: an unseen or unknown
+// session fails here before the daemon mints a token, and a pinned or live
+// session is refused with the step that unblocks it.
+async function requireForgettable(
+  caller: FleetCaller,
+  session: unknown,
+  stops: boolean,
+): Promise<void> {
+  const got = await caller.sendRequest('session.get', { session });
+
+  const descriptor = isRecord(got['session']) ? got['session'] : {};
+  const parent = descriptor['parent'];
+  let pinned = descriptor['pinned'] === true;
+
+  if (!pinned && typeof parent === 'string') {
+    const owner = await caller.sendRequest('session.get', { session: parent });
+
+    pinned = isRecord(owner['session']) && owner['session']['pinned'] === true;
+  }
+
+  if (pinned) {
+    throw new Error(
+      'session_pinned: the session is pinned, or is a sub-session of a pinned session. Unpin it with atc_session_update before forgetting it.',
+    );
+  }
+
+  if (descriptor['alive'] === true && !stops) {
+    throw new Error('session_live: the session is live. Pass stop: true to stop and forget it.');
+  }
+}
+
 // The inherited id can point at a session another daemon hosts, or one
 // this daemon no longer lists; the spawn then lands top-level instead of
 // failing the tool call. The top-level spawn has a different payload, so it