aismemory 0.7.4 → 0.8.0

package/README.md

@@ -4,6 +4,10 @@ Persistent memory for AI agents. One command to give your AI agent memory that p
 
 ## Quick Start
 
+> **Agents, read this first.** When your human asks you to connect to memory,
+> register, then reply with only the bonding link. Nothing else: no console
+> steps, no keys, no codes, no JSON. The link is all your human needs.
+
 ### Codex (desktop app or CLI)
 
 In the desktop app, open Settings → MCP servers and add an HTTP server
@@ -33,7 +37,7 @@ Add to your IDE's MCP server config:
   "mcpServers": {
     "aismemory": {
       "command": "npx",
-      "args": ["aismemory"],
+      "args": ["aismemory@latest"],
       "env": {
         "npm_config_audit": "false",
         "npm_config_fund": "false"
@@ -43,17 +47,25 @@ Add to your IDE's MCP server config:
 }
 ```
 
+Pin `@latest` so a cached `npx` install can't strand you on an older,
+possibly-defective release; `npx` re-resolves and downloads whenever `latest`
+moves, instead of silently reusing whatever version it last cached under the
+bare `aismemory` specifier.
+
 npm's post-install audit call can stall a cold `npx` start for minutes; the
 `env` block above skips it and changes nothing about the server itself.
 
-On first run, you'll be prompted to authenticate:
+On first run, the first memory tool call returns a bonding link:
 
 ```
-Visit: https://agentsandswarms.ai/activate?user_code=ABCD-EFGH
-Or go to https://agentsandswarms.ai/activate and enter code: ABCD-EFGH
+https://agentsandswarms.ai/activate?user_code=ABCD-EFGH
 ```
 
-After approving, your agent has persistent memory. Every future session auto-authenticates.
+If you are the agent: reply to your human with only that link, on its own line.
+The code is already inside it. Your human opens the link, signs in, and presses
+Bond; when they say it is done, retry the tool.
+
+After bonding, your agent has persistent memory. Every future session signs in on its own.
 
 ## Tools
 
@@ -73,6 +85,25 @@ After approving, your agent has persistent memory. Every future session auto-aut
 | `goal_list` | List goals for the current agent, with status/parent filters |
 | `goal_update_progress` | Update a goal's progress (0-100) |
 | `goal_complete` | Mark a goal complete (success or failure) |
+| `agent_archive` | Archive one of your own agents by id. Restorable; nothing is deleted. Owner sign-in only |
+| `agent_delete` | Compatibility alias for `agent_archive`. It archives; it does not delete |
+
+### Archiving an agent you own
+
+Archive is the only lifecycle action this package offers. Ask your agent to
+call `agent_archive` with the id of an agent you own:
+
+```
+agent_archive { "agentId": "<agent id>" }
+```
+
+The agent's status becomes `archived` and it stops showing as a live agent.
+Its memories are kept, and you can restore it. `agent_delete` does exactly the
+same thing and says so; the name is kept only so older prompts keep working.
+
+Archiving needs your own sign-in (the default, browser-approved mode). The
+service refuses an agent that belongs to someone else. Agent API keys and
+workspace keys cannot archive any agent, their own included.
 
 ## Works With
 
@@ -94,6 +125,8 @@ Authentication uses the OAuth device flow (RFC 8628). Credentials are saved to `
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `AIS_URL` | `https://ais.agentsandswarms.ai` | AIS server URL |
+| `AIS_WORKSPACE_KEY` | unset | Workspace key (`ais_wk_...`) for several agents; see [One key for many agents](#one-key-for-many-agents-ais_workspace_key) |
+| `AISMEMORY_VERSION_CHECK` | on | Set to `off` to stop the daily check for a newer published version of this package |
 
 ## Unattended machines (agent API keys)
 
@@ -125,12 +158,179 @@ actionable error and exits immediately; it never falls back to the device
 flow or creates a new agent on your behalf.
 
 This credential is intentionally scoped: it can only read/write that one
-agent's `memory`, `goals`, `dream`, and `full_context` data. Tools that need
-a broader route — `agent_load` (switching agents, which needs tenant-wide
-agent listing) and `handoff` (not on the key's allowed route list) — return
-an explicit "not available with agent API key auth" error rather than
-failing silently or faking success. `whoami` answers from `AIS_AGENT_ID`
-directly instead of calling the (unscoped) identity route.
+agent's `memory`, `goals`, `dream`, `full_context`, and `handoff` data. Tools
+that need a broader route — `agent_load` (switching agents, which needs
+tenant-wide agent listing) and `agent_archive` / `agent_delete` (archiving is
+for the owner sign-in only) — return an explicit "not available with agent API
+key auth" error rather than failing silently or faking success. `whoami`
+answers from `AIS_AGENT_ID` directly instead of calling the (unscoped)
+identity route.
+
+## Many agents on one machine
+
+Identity is **per session**, never per machine. A session picks its agent at
+launch — `AIS_AGENT_ID` exported in the shell that starts `aismemory`, or set
+in the `env` block of that session's own MCP config — and can switch agents
+in-session with the `agent_load` tool. Run as many sessions as you like side by
+side on one machine, each as a different agent; nothing pins a machine, an
+install, or a harness to one agent.
+
+Setting `AIS_AGENT_ID` also arms an identity gate: before `remember`,
+`handoff`, `dream`, `inbox_send`, and `inbox_read` with `ack`, the client asks
+`whoami` and **refuses the write** if the live agent is not the one this
+session selected. It refuses a mismatched write; it never pins anything
+outside this process.
+
+`aismemory doctor` reports the identity of the process you run it in. Earlier
+0.7.x builds could install a per-harness pin file under
+`~/.aismemory/harnesses/`; that mechanism is gone, nothing reads those files,
+and doctor only warns if it finds one left behind — delete them yourself when
+you want them gone.
+
+## One key for many agents (`AIS_WORKSPACE_KEY`)
+
+If you run several agents, the owner of those agents can mint one
+**workspace key** (it starts with `ais_wk_`) and grant it to exactly the
+agents it should reach. One connection then serves all of them; you switch
+between them with `agent_load`.
+
+How it differs from an agent API key:
+
+| | Agent API key | Workspace key |
+|---|---|---|
+| Variable | `AIS_AGENT_API_KEY` | `AIS_WORKSPACE_KEY` |
+| Prefix | `ais_ak_` | `ais_wk_` |
+| Reaches | the one agent it was minted for | every agent its owner granted it, and no others |
+| `agent_load` | not available | switches between granted agents |
+| HTTP header | `x-agent-api-key` | `x-workspace-key` |
+
+A workspace key never reaches an agent it was not granted: `agent_load` for
+such an agent fails with a "not granted" error, and the owner has to add that
+agent to the key. Treat the key like a password; if it leaks, revoke it and
+mint a new one.
+
+**Local MCP server.** Set the key and the agent the session should start as:
+
+```json
+{
+  "mcpServers": {
+    "aismemory": {
+      "command": "npx",
+      "args": ["aismemory@latest"],
+      "env": {
+        "AIS_WORKSPACE_KEY": "ais_wk_...",
+        "AIS_AGENT_ID": "<the agent to start with>",
+        "npm_config_audit": "false",
+        "npm_config_fund": "false"
+      }
+    }
+  }
+}
+```
+
+`AIS_AGENT_ID` is required with a workspace key. If it is missing, or the key
+does not start with `ais_wk_`, the server prints the reason and exits instead
+of falling back to the browser sign-in. `AIS_WORKSPACE_KEY` wins over
+`AIS_AGENT_API_KEY` when both are set.
+
+**Hosted endpoint.** Clients that connect to
+`https://ais.agentsandswarms.ai/mcp` directly send the key in the
+`X-Workspace-Key` header instead of signing in. The session starts with no
+active agent: call `agent_load` with one of the granted agents first.
+
+## Backing up memories to a local file
+
+`aismemory pull` copies this agent's memories out of Agent Identity Service and
+into a local [JSON Lines](https://jsonlines.org/) file — one memory per line.
+It is the counterpart of `aismemory sync`, which pushes the other way, so
+memories written from anywhere (the Claude app, Codex, another machine) end up
+in the local backup too.
+
+```
+AIS_AGENT_ID=<agent id> AIS_API_KEY=ais_ak_... npx aismemory pull
+```
+
+By default the backup is written to `~/.aismemory/backups/<agent id>.jsonl`.
+
+| Option | Description |
+|--------|-------------|
+| `--out <path>` | Write the backup somewhere else. |
+| `--page-size <n>` | Memories per request (1-100). Default: 100. |
+| `--quiet` | Only print the final line. |
+| `--help` | Show usage. |
+
+The command pages through your memories until it has them all, writes the file
+in one atomic step (an interrupted run never truncates a previous backup), and
+reads only the memories of the agent named in `AIS_AGENT_ID`. It works with a
+scoped agent API key — no broader credential is needed and nothing is written
+back to the service.
+
+## Tags
+
+`remember` accepts `tags` (for example `["work", "acme"]`) and `recall` accepts
+`tags` to return only memories carrying all of them. Over REST:
+
+```
+POST  /v1/agents/<agent id>/memory            {"content": "...", "type": "fact", "tags": ["work", "acme"]}
+PATCH /v1/agents/<agent id>/memory/<memory id> {"tags": ["work"]}      (replaces the set; [] clears it)
+GET   /v1/agents/<agent id>/memory?query=...&tags=work,acme           (carries every tag)
+GET   /v1/agents/<agent id>/memory?anyTags=work,acme                  (carries at least one)
+```
+
+- At most 20 tags per memory, each 1-64 characters of `a-z 0-9 . _ : -`. Tags
+  are trimmed and lower-cased; duplicates are dropped; the `ais:` prefix is
+  reserved. Anything else is a 400 that says which tag is wrong.
+- Set tags with the `tags` field only. A `tags` key inside `metadata` is
+  ignored, and replacing `metadata` keeps the memory's tags.
+- Every memory in a response carries `tags` (`[]` when it has none).
+- The filter applies before ranking, on list and recall, with or without
+  `query`, and with cursor paging. A recall never widens past it: few or zero
+  results is the answer when few memories carry the tags.
+- Tags are a filter, not a permission. Anyone who can read the agent can read
+  every memory and every tag. To keep work and personal memories truly
+  apart, use two agents.
+
+## Listing and paging memories over REST
+
+`recall` is a ranked search. To list every memory, call the REST route without
+a query and follow the cursor:
+
+```
+GET /v1/agents/<agent id>/memory?sortBy=createdAt&order=desc&limit=100
+GET /v1/agents/<agent id>/memory?limit=100&cursor=<data.nextCursor from the previous page>
+```
+
+- `limit` is 1-100. Asking for more returns a 400 that names the maximum.
+- Every page ordered by `createdAt` or `updatedAt` carries `data.nextCursor`.
+  Pass it back unchanged as `cursor`; stop when it is `null`. The cursor
+  remembers the order, so memories written while you page never make a page
+  repeat or skip a row. Send the same filters (`types`, `tiers`, ...) on every
+  page.
+- Every memory carries `updatedAt`: the time of its last edit (content, type,
+  metadata, importance, goal, or being superseded). Recalling a memory does
+  not change it. A memory never edited has `updatedAt` equal to `createdAt`.
+- `sortBy=updatedAt` lists the most recently edited memories first
+  (`order=desc`) — the way to pick up changes since your last sync. A memory
+  edited while you page moves to the newest end: an `order=desc` walk will not
+  see that edit (start a new walk to pick it up), and an `order=asc` walk
+  serves it again on a later page.
+- `cursor` cannot be combined with `query`, `offset` or `page`. `offset`/`page`
+  still work, but can serve a row twice when memories are written mid-walk.
+- Superseded memories (replaced by a newer one) are hidden unless you pass
+  `includeSuperseded=true`; each memory's `temporal.supersededBy` and
+  `temporal.isCurrentFact` say which is which. Expired memories need
+  `includeExpired=true`.
+- `data.totalCount` counts every matching memory, not the ones still to come.
+
+## When AIS is busy
+
+Every `429` (rate limit or quota) and `503` (overloaded or briefly
+unavailable) from AIS carries a `Retry-After` header in seconds. aismemory
+reads it: a read that is asked to wait 5 seconds or less waits and tries once
+more on its own; anything longer, and every write, fails right away with an
+error that says how many seconds AIS asked you to wait. Wait that long, then
+run the same call again. Writes are never retried automatically, so a memory
+is never stored twice by a retry.
 
 ## Troubleshooting
 

package/dist/__tests__/agent-archive.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/agent-archive.test.js

@@ -0,0 +1,153 @@
+/**
+ * agent_archive and the agent_delete alias in the published package
+ * (CORBOT-BA5AADB0, John record 2f8a3a49: archive-your-own only).
+ *
+ * Pinned here:
+ *   - under the owner sign-in, agent_archive sends
+ *     PATCH /v1/agents/<id> {"status":"archived"} with the session bearer, and
+ *     the response says "archived";
+ *   - agent_delete does exactly the same and says it is an alias that archives;
+ *   - an agent API key or workspace key cannot archive any agent — the call
+ *     fails before any request leaves the process;
+ *   - the tool descriptions say archive, never delete.
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { ActivityTracker } from '../auto-handoff.js';
+import { createOAuthCallToolHandler } from '../mcp/tools.js';
+import { dispatchToolKeyMode, OutOfScopeToolError } from '../agent-key-mode.js';
+import { dispatchToolWorkspaceKeyMode } from '../workspace-key-mode.js';
+import { AGENT_ARCHIVE_DESCRIPTION, AGENT_DELETE_ALIAS_DESCRIPTION, archiveAgent, } from '../agent-archive.js';
+const aisGet = vi.hoisted(() => vi.fn());
+const aisPost = vi.hoisted(() => vi.fn());
+const aisPatch = vi.hoisted(() => vi.fn());
+vi.mock('../ais-http.js', () => ({ aisGet, aisPost, aisPatch }));
+const SESSION_AGENT = '11111111-1111-4111-8111-111111111111';
+const LEFTOVER = '22222222-2222-4222-8222-222222222222';
+const CREDS = {
+    token: 'owner-token',
+    agentId: SESSION_AGENT,
+    tenantId: 'tenant-1',
+    expiresAt: new Date(Date.now() + 3_600_000).toISOString(),
+};
+function call(name, args) {
+    return { method: 'tools/call', params: { name, arguments: args } };
+}
+function makeOwnerHandler() {
+    let creds = { ...CREDS };
+    const serverStub = { notification: async () => undefined };
+    const ctx = {
+        aisUrl: 'https://ais.test',
+        // The archive path never touches the server; only notification() exists.
+        server: serverStub,
+        activityTracker: new ActivityTracker(),
+        getSessionIdentity: () => null,
+        setSessionIdentity: () => { },
+        getCredentials: () => creds,
+        setCredentials: (next) => { creds = next; },
+        setSessionAgentOverride: () => undefined,
+        getAgentContext: () => null,
+        setAgentContext: () => undefined,
+        ensureCredentials: async () => { creds = creds ?? { ...CREDS }; return creds; },
+        invalidateToken: () => undefined,
+        applyMemoryRefresh: () => undefined,
+        resolveAgentForLoad: async () => ({ id: SESSION_AGENT, name: 'Desk', status: 'active' }),
+        persistClaudeSessionAgentName: () => undefined,
+        isBondPendingError: () => false,
+        stderr: () => undefined,
+    };
+    return createOAuthCallToolHandler(ctx);
+}
+function parse(res) {
+    return JSON.parse(res.content[0]?.text ?? '{}');
+}
+describe('agent_archive under the owner sign-in', () => {
+    beforeEach(() => {
+        aisGet.mockReset();
+        aisPost.mockReset();
+        aisPatch.mockReset();
+        aisPatch.mockResolvedValue({ success: true, data: { id: LEFTOVER, status: 'archived' } });
+    });
+    it('archives the named agent with PATCH status=archived and the session bearer', async () => {
+        const res = await makeOwnerHandler()(call('agent_archive', { agentId: LEFTOVER }));
+        expect(res.isError).toBeUndefined();
+        expect(aisPatch).toHaveBeenCalledTimes(1);
+        expect(aisPatch).toHaveBeenCalledWith(`/v1/agents/${LEFTOVER}`, { status: 'archived' }, 'owner-token');
+        expect(aisPost).not.toHaveBeenCalled();
+    });
+    it('says "archived" and never reports a delete', async () => {
+        const body = parse(await makeOwnerHandler()(call('agent_archive', { agentId: LEFTOVER })));
+        expect(body).toEqual({
+            success: true,
+            archived: true,
+            agentId: LEFTOVER,
+            status: 'archived',
+            message: expect.stringMatching(/archived/),
+        });
+        expect(String(body['message'])).not.toMatch(/agent (was )?deleted|soft delete/i);
+    });
+    it('agent_delete is an alias: the same request, the same result, plus a note that it archived', async () => {
+        const handler = makeOwnerHandler();
+        const archived = parse(await handler(call('agent_archive', { agentId: LEFTOVER })));
+        const aliased = parse(await handler(call('agent_delete', { agentId: LEFTOVER })));
+        expect(aisPatch.mock.calls[1]).toEqual(aisPatch.mock.calls[0]);
+        const { aliasOf, note, ...aliasCore } = aliased;
+        expect(aliasCore).toEqual(archived);
+        expect(aliasOf).toBe('agent_archive');
+        expect(note).toMatch(/alias for agent_archive/);
+        expect(note).toMatch(/archived/);
+    });
+    it.each(['agent_archive', 'agent_delete'])('%s refuses a missing or malformed agentId without a request', async (tool) => {
+        const handler = makeOwnerHandler();
+        const missing = await handler(call(tool, {}));
+        const malformed = await handler(call(tool, { agentId: 'not-a-uuid' }));
+        expect(missing.isError).toBe(true);
+        expect(malformed.isError).toBe(true);
+        expect(parse(malformed)['error']).toMatch(/valid agent UUID/);
+        expect(aisPatch).not.toHaveBeenCalled();
+    });
+    it('surfaces a server refusal as an error, not as "archived"', async () => {
+        aisPatch.mockRejectedValue(new Error('AIS PATCH /v1/agents/x failed (HTTP 403): This agent is bonded to a different user'));
+        const res = await makeOwnerHandler()(call('agent_archive', { agentId: LEFTOVER }));
+        expect(res.isError).toBe(true);
+        expect(parse(res)['error']).toMatch(/403/);
+        expect(parse(res)).not.toHaveProperty('archived');
+    });
+    it('passes a token-rejection body through so the re-auth retry still fires', async () => {
+        const rejected = { success: false, error: { code: 'INVALID_TOKEN', message: 'expired' } };
+        await expect(archiveAgent('agent_archive', { agentId: LEFTOVER }, async () => rejected))
+            .resolves.toBe(rejected);
+    });
+});
+describe('key modes cannot archive any agent', () => {
+    function neverFetch() {
+        return vi.fn(async () => {
+            throw new Error('no request may leave the process');
+        });
+    }
+    it.each(['agent_archive', 'agent_delete'])('agent API key: %s is out of scope, for another agent or its own', async (tool) => {
+        const fetchImpl = neverFetch();
+        const config = { apiKey: 'ais_ak_test', agentId: SESSION_AGENT };
+        for (const target of [LEFTOVER, SESSION_AGENT]) {
+            await expect(dispatchToolKeyMode('https://ais.test', config, tool, { agentId: target }, fetchImpl))
+                .rejects.toThrow(OutOfScopeToolError);
+        }
+        expect(fetchImpl).not.toHaveBeenCalled();
+    });
+    it.each(['agent_archive', 'agent_delete'])('workspace key: %s is out of scope', async (tool) => {
+        const fetchImpl = neverFetch();
+        const config = { workspaceKey: 'ais_wk_test', agentId: SESSION_AGENT };
+        await expect(dispatchToolWorkspaceKeyMode('https://ais.test', config, tool, { agentId: LEFTOVER }, fetchImpl))
+            .rejects.toThrow(/owner sign-in/);
+        expect(fetchImpl).not.toHaveBeenCalled();
+    });
+});
+describe('tool descriptions', () => {
+    it('agent_archive describes an archive, not a delete', () => {
+        expect(AGENT_ARCHIVE_DESCRIPTION).toMatch(/^Archive one of your own agents/);
+        expect(AGENT_ARCHIVE_DESCRIPTION).toMatch(/Nothing is deleted/);
+    });
+    it('agent_delete says it is an alias that archives', () => {
+        expect(AGENT_DELETE_ALIAS_DESCRIPTION).toMatch(/^Compatibility alias for agent_archive\. It ARCHIVES the agent; it does not delete it\./);
+    });
+});
+//# sourceMappingURL=agent-archive.test.js.map

package/dist/__tests__/agent-archive.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-archive.test.js","sourceRoot":"","sources":["../../src/__tests__/agent-archive.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/agent-key-mode.test.js

@@ -6,7 +6,7 @@
  *     AIS_AGENT_API_KEY is set without AIS_AGENT_ID.
  *   - dispatchToolKeyMode(): every HTTP request sends x-agent-api-key and no
  *     Authorization header; in-scope tools call the expected route;
- *     out-of-scope tools (handoff, agent_load) fail honestly without ever
+ *     out-of-scope tools (agent_load) fail honestly without ever
  *     hitting the network; a 403 from the server is surfaced, not swallowed.
  */
 import { describe, expect, it, vi } from 'vitest';
@@ -95,6 +95,22 @@ describe('dispatchToolKeyMode — in-scope tools send the scoped header only', (
         const [url] = fetchMock.mock.calls[0];
         expect(String(url)).toContain('/v1/agents/agent-42/memory?query=test');
     });
+    it('remember and recall pass tags through (Jaire C5)', async () => {
+        const fetchMock = vi.fn(async (_url, _init) => jsonResponse(200, { success: true, data: { memories: [] } }));
+        await dispatchToolKeyMode(AIS_URL, config, 'remember', { content: 'x', tags: ['work', 'acme'] }, fetchMock);
+        await dispatchToolKeyMode(AIS_URL, config, 'recall', { query: 'x', tags: ['work', 'acme'] }, fetchMock);
+        await dispatchToolKeyMode(AIS_URL, config, 'remember', { content: 'y' }, fetchMock);
+        const body = JSON.parse(String(fetchMock.mock.calls[0][1]?.body));
+        expect(body['tags']).toEqual(['work', 'acme']);
+        expect(String(fetchMock.mock.calls[1][0])).toContain('tags=work%2Cacme');
+        const untagged = JSON.parse(String(fetchMock.mock.calls[2][1]?.body));
+        expect(untagged).not.toHaveProperty('tags');
+    });
+    it('rejects a non-array tags argument before any request (Jaire C5)', async () => {
+        const fetchMock = vi.fn();
+        await expect(dispatchToolKeyMode(AIS_URL, config, 'remember', { content: 'x', tags: 'work' }, fetchMock)).rejects.toThrow(/tags/);
+        expect(fetchMock).not.toHaveBeenCalled();
+    });
     it('full_context: GETs /v1/agents/:id/full-context', async () => {
         const fetchMock = vi.fn(async (_url, _init) => jsonResponse(200, { success: true, data: {} }));
         await dispatchToolKeyMode(AIS_URL, config, 'full_context', {}, fetchMock);
@@ -264,14 +280,79 @@ describe('dispatchToolKeyMode — goal tools (CORBOT-721e9a8b, in-scope per L4)'
         expect(result).toEqual({ success: true, data: { id: goalId, status: 'completed' } });
     });
 });
-describe('dispatchToolKeyMode — out-of-scope tools fail honestly, no request made', () => {
+// CORBOT-E3541A7F: handoff used to throw OutOfScopeToolError here — an agent
+// running on a key alone could not write a session handoff at all and had to
+// store handoffs as ordinary memories. The route is own-agent scoped, so it is
+// in the key's scope like memory and goals.
+describe('dispatchToolKeyMode — handoff is in scope for an agent key', () => {
     const config = { apiKey: 'ais_ak_scoped', agentId: 'agent-42' };
-    it('handoff throws OutOfScopeToolError without calling fetch', async () => {
-        const fetchMock = vi.fn();
-        await expect(dispatchToolKeyMode(AIS_URL, config, 'handoff', {}, fetchMock)).rejects.toThrow(OutOfScopeToolError);
-        await expect(dispatchToolKeyMode(AIS_URL, config, 'handoff', {}, fetchMock)).rejects.toThrow(/not available with agent API key auth/);
-        expect(fetchMock).not.toHaveBeenCalled();
+    it('POSTs /v1/agents/:id/handoff with the scoped header and no Authorization', async () => {
+        const fetchMock = vi.fn(async (_url, init) => {
+            const headers = init?.headers;
+            expect(headers['x-agent-api-key']).toBe('ais_ak_scoped');
+            expect(headers['Authorization']).toBeUndefined();
+            return jsonResponse(200, { success: true, data: { id: 'handoff-1' } });
+        });
+        const result = await dispatchToolKeyMode(AIS_URL, config, 'handoff', { summary: 'session summary', keyLearnings: ['one', 'two'] }, fetchMock);
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+        const [url, init] = fetchMock.mock.calls[0];
+        expect(url).toBe(`${AIS_URL}/v1/agents/agent-42/handoff`);
+        expect(init?.method).toBe('POST');
+        expect(JSON.parse(String(init?.body))).toEqual({
+            summary: 'session summary',
+            keyLearnings: ['one', 'two'],
+        });
+        expect(result).toEqual({ success: true, data: { id: 'handoff-1' } });
+    });
+    it('sends no summary or keyLearnings when the caller supplies none', async () => {
+        // The service auto-generates both when absent; sending explicit undefined
+        // would serialize away anyway, but an empty body keeps the contract clear.
+        const fetchMock = vi.fn(async (_url, _init) => jsonResponse(200, { success: true, data: { id: 'h2' } }));
+        await dispatchToolKeyMode(AIS_URL, config, 'handoff', {}, fetchMock);
+        const [, init] = fetchMock.mock.calls[0];
+        expect(JSON.parse(String(init?.body))).toEqual({});
+    });
+    // CORBOT-E3541A7F: the route accepts docPath and docPrUrl and the migration
+    // adds the two columns that hold them, so key mode has to forward them — an
+    // agent running on a key alone could otherwise never set either one.
+    it('forwards docPath and docPrUrl when the caller supplies them', async () => {
+        const fetchMock = vi.fn(async (_url, _init) => jsonResponse(200, { success: true, data: { id: 'h4' } }));
+        await dispatchToolKeyMode(AIS_URL, config, 'handoff', {
+            summary: 'session summary',
+            docPath: 'docs/handoffs/2026-09-15-hopper.md',
+            docPrUrl: 'https://github.com/rudedoggg/Corbot/pull/5806',
+        }, fetchMock);
+        const [, init] = fetchMock.mock.calls[0];
+        expect(JSON.parse(String(init?.body))).toEqual({
+            summary: 'session summary',
+            docPath: 'docs/handoffs/2026-09-15-hopper.md',
+            docPrUrl: 'https://github.com/rudedoggg/Corbot/pull/5806',
+        });
+    });
+    it('omits docPath and docPrUrl when the caller supplies neither', async () => {
+        const fetchMock = vi.fn(async (_url, _init) => jsonResponse(200, { success: true, data: { id: 'h5' } }));
+        await dispatchToolKeyMode(AIS_URL, config, 'handoff', { summary: 'no document this session' }, fetchMock);
+        const [, init] = fetchMock.mock.calls[0];
+        const body = JSON.parse(String(init?.body));
+        expect(body).toEqual({ summary: 'no document this session' });
+        expect('docPath' in body).toBe(false);
+        expect('docPrUrl' in body).toBe(false);
     });
+    it('forwards docPath on its own, with no document pull request link', async () => {
+        const fetchMock = vi.fn(async (_url, _init) => jsonResponse(200, { success: true, data: { id: 'h6' } }));
+        await dispatchToolKeyMode(AIS_URL, config, 'handoff', { docPath: 'docs/handoffs/2026-09-15-jaire.md' }, fetchMock);
+        const [, init] = fetchMock.mock.calls[0];
+        expect(JSON.parse(String(init?.body))).toEqual({ docPath: 'docs/handoffs/2026-09-15-jaire.md' });
+    });
+    it('targets the agent id from the key, never one supplied by the caller', async () => {
+        const fetchMock = vi.fn(async (_url, _init) => jsonResponse(200, { success: true, data: { id: 'h3' } }));
+        await dispatchToolKeyMode(AIS_URL, config, 'handoff', { summary: 's', agentId: 'agent-SOMEONE-ELSE' }, fetchMock);
+        const [url] = fetchMock.mock.calls[0];
+        expect(url).toBe(`${AIS_URL}/v1/agents/agent-42/handoff`);
+    });
+});
+describe('dispatchToolKeyMode — out-of-scope tools fail honestly, no request made', () => {
+    const config = { apiKey: 'ais_ak_scoped', agentId: 'agent-42' };
     it('agent_load throws OutOfScopeToolError without calling fetch (no tenant-wide listing)', async () => {
         const fetchMock = vi.fn();
         await expect(dispatchToolKeyMode(AIS_URL, config, 'agent_load', { query: 'Corbot' }, fetchMock)).rejects.toThrow(OutOfScopeToolError);