aismemory 0.7.5 → 0.8.2

package/README.md

@@ -37,7 +37,7 @@ Add to your IDE's MCP server config:
   "mcpServers": {
     "aismemory": {
       "command": "npx",
-      "args": ["aismemory@latest"],
+      "args": ["aismemory@0.8.2"],
       "env": {
         "npm_config_audit": "false",
         "npm_config_fund": "false"
@@ -47,10 +47,16 @@ 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.
+Pin an exact version rather than `aismemory@latest`. With `@latest`, every
+client startup makes `npx` resolve the tag against the npm registry before it
+can even launch the cached install — on a slow or congested connection that
+resolution call can itself hang, and clients with a startup connect timeout
+(for example Claude Code's 30s `CONNECT_TIMEOUT`) will kill the launch before
+the server ever starts (GitHub issue #6635). A pinned version skips that
+resolution call entirely and reuses the local `npx` cache. The version-check
+module (`AISMEMORY_VERSION_CHECK`) already tells you in-session when a newer
+release is available, so pinning no longer trades away staleness detection —
+bump the pinned version when it does.
 
 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.
@@ -74,7 +80,8 @@ After bonding, your agent has persistent memory. Every future session signs in o
 | `remember` | Store a memory (fact, event, lesson, context, goal, task) |
 | `recall` | Search memories by natural language query |
 | `whoami` | Get agent identity and status |
-| `full_context` | Load complete agent context (personality, goals, facts, skills) |
+| `orientation_check` | Diff an owner-approved expected-environment manifest against this session's evidence — read-only, same comparator as `aismemory doctor --orientation`, reachable without a filesystem |
+| `full_context` | Load complete agent context (personality, goals, facts, skills, and the versioned operating layer — constitution rules plus the skills index) |
 | `dream` | Trigger memory consolidation (promotes important, archives old) |
 | `handoff` | Save session context for the next session |
 | `agent_load` | Switch the active agent by name — triggers on "get me X", "bring me X", "load X", "/agent X", "switch to X" |
@@ -85,6 +92,25 @@ After bonding, your agent has persistent memory. Every future session signs in o
 | `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
 
@@ -106,6 +132,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) |
+| `AIS_MCP_REQUEST_TIMEOUT_MS` | `20000` | Client-side timeout, in milliseconds, for every HTTP call this server makes to AIS. A stalled call fails with a clear error instead of hanging. Must be a positive number; anything else falls back to the default |
 | `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)
@@ -140,11 +168,140 @@ 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`, `full_context`, and `handoff` data. Tools
 that need a broader route — `agent_load` (switching agents, which needs
-tenant-wide agent listing) — return an explicit "not available with agent API
+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.
+
+Generate a separate portable MCP config for each agent (use its **agent ID**
+from `whoami`, not its display name; this offline command does not resolve names):
+
+```sh
+aismemory install --identity <agent-a-id> --out ./agent-configs
+aismemory install --identity <agent-b-id> --out ./agent-configs
+```
+
+Each command writes `aismemory-<agent-id>.mcp.json` with that ID in the server's
+`AIS_AGENT_ID` env, and prints a shell/start-script snippet:
+
+```sh
+AIS_AGENT_ID='<agent-a-id>' claude --strict-mcp-config --mcp-config '/absolute/path/agent-configs/aismemory-<agent-a-id>.mcp.json'
+```
+
+The default output directory is `./aismemory-configs`. Existing files are never
+overwritten; use a new output directory to regenerate. The config contains no
+secrets and copies no credentials. Authenticate as needed and run `whoami` in
+each new session. `--strict-mcp-config` selects only this file for the session;
+add other needed MCP servers to it. Other clients can load the generated MCP
+server entry in their **session-specific** config.
+
+Never put `AIS_AGENT_ID` in user-scope `~/.claude.json` or a shared shell profile.
+Install does not edit shared config or create legacy harness pins. Doctor warns
+when user-scope Claude env blocks contain an agent ID and explains how to move
+to separate session configs; it never edits or deletes those defaults.
+
+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.
+
+## Unattended credentials
+
+Credential mode order is deterministic:
+
+1. `AIS_WORKSPACE_KEY` (or `AIS_API_KEY=ais_wk_...`)
+2. `AIS_AGENT_API_KEY` (or `AIS_API_KEY=ais_ak_...`)
+3. `AIS_RUN_PASS_FILE`
+4. saved sign-in / browser sign-in
+
+When `AIS_RUN_PASS_FILE` is unset, explicit keys keep their existing
+precedence over saved sign-in. If `AIS_RUN_PASS_FILE` is set together with
+`AIS_WORKSPACE_KEY`, `AIS_AGENT_API_KEY`, or `AIS_API_KEY`, startup is refused
+instead of silently falling back to a long-lived key.
+
+## 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@0.8.2"],
+      "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.
+
+## One run pass for one run (`AIS_RUN_PASS_FILE`)
+
+Launchers can set `AIS_RUN_PASS_FILE` to the path of a file containing a
+short-lived run pass (`ais_rp_...`) and `AIS_AGENT_ID` to the agent for that
+run. On every AIS request, aismemory re-reads the file and sends only:
+
+```http
+x-run-pass: ais_rp_...
+```
+
+It never sends a workspace key, agent key, bearer token, or service key in
+run-pass mode. If the file is missing, unreadable, empty, or does not contain
+a valid run pass, the request is refused locally and the pass value is never
+printed.
+
+**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
@@ -172,6 +329,73 @@ 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
 
 If aismemory "doesn't work," run the built-in self-diagnosis before filing a
@@ -188,6 +412,22 @@ with a PASS/WARN/FAIL line and a remediation hint. Nothing is written to the
 API. Pass `--json` for machine-readable output. Exits `0` unless a check
 FAILs.
 
+## Source and provenance
+
+Source is private. This package is published from GitHub Actions via npm
+Trusted Publishing (OIDC) — no long-lived token, and the publish is bound to
+this project's own CI workflow (verify with `npm view aismemory --json` and
+check `_npmUser.trustedPublisher`). Every package on npm, including this one,
+carries npm's registry signature, checkable locally with `npm audit
+signatures`. That is separate from npm's build provenance/attestation
+feature (a public, source-linked attestation), which requires a public
+source repository and is not enabled here while the source stays private.
+
+Official domains: https://www.agentsandswarms.ai and
+https://ais.agentsandswarms.ai. Security contact: security@agentsandswarms.ai.
+The human bonding link above (`agentsandswarms.ai/activate`) is issued at
+runtime by Agent Identity Service, not hardcoded in this package.
+
 ## License
 
 MIT

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

@@ -10,7 +10,8 @@
  *     hitting the network; a 403 from the server is surfaced, not swallowed.
  */
 import { describe, expect, it, vi } from 'vitest';
-import { AgentApiKeyConfigError, dispatchToolKeyMode, loadAgentApiKeyConfig, OutOfScopeToolError, UNKNOWN_TOOL_KEY_MODE, } from '../agent-key-mode.js';
+import { AisHttpError } from '../ais-http-error.js';
+import { AgentApiKeyConfigError, aisKeyGet, dispatchToolKeyMode, loadAgentApiKeyConfig, OutOfScopeToolError, UNKNOWN_TOOL_KEY_MODE, } from '../agent-key-mode.js';
 const AIS_URL = 'https://ais.example.test';
 function jsonResponse(status, body) {
     return new Response(JSON.stringify(body), {
@@ -95,6 +96,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);
@@ -124,22 +141,120 @@ describe('dispatchToolKeyMode — in-scope tools send the scoped header only', (
         const [url] = fetchMock.mock.calls[0];
         expect(url).toBe(`${AIS_URL}/v1/agents/agent-42/memory`);
     });
-    it('whoami: answers from AIS_AGENT_ID and probes an allowed route (no identity route call)', async () => {
+    it('whoami: asks the self-description route and passes its fields through (CORBOT-49535E96)', async () => {
         const calledPaths = [];
         const fetchMock = vi.fn(async (url) => {
             calledPaths.push(String(url));
-            return jsonResponse(200, { success: true, data: { memories: [] } });
+            return jsonResponse(200, {
+                success: true,
+                data: {
+                    agentId: 'agent-42',
+                    tenantId: 'tenant-1',
+                    mode: 'agent-api-key',
+                    scopeModel: 'allowlist',
+                    scopes: ['memory', 'whoami'],
+                    restrictions: ['cannot mint, list or revoke API keys'],
+                    actsAsGrantedAgent: false,
+                    expiresAt: '2027-01-01T00:00:00.000Z',
+                },
+            });
         });
         const result = await dispatchToolKeyMode(AIS_URL, config, 'whoami', {}, fetchMock);
-        expect(calledPaths).toHaveLength(1);
-        expect(calledPaths[0]).toContain('/v1/agents/agent-42/memory?limit=1');
+        expect(calledPaths).toEqual([`${AIS_URL}/v1/agents/agent-42/whoami`]);
         // Must never call the bare identity route — it has no allowlisted subresource.
         expect(calledPaths.some((p) => /\/v1\/agents\/agent-42$/.test(p))).toBe(false);
         expect(result).toMatchObject({
             success: true,
-            data: { agentId: 'agent-42', authMode: 'agent-api-key', keyValid: true },
+            data: {
+                agentId: 'agent-42',
+                authMode: 'agent-api-key',
+                keyValid: true,
+                selfDescribed: true,
+                scopes: ['memory', 'whoami'],
+                expiresAt: '2027-01-01T00:00:00.000Z',
+            },
+        });
+    });
+    it('whoami: an older server without the route still gets the liveness probe answer', async () => {
+        const calledPaths = [];
+        const fetchMock = vi.fn(async (url) => {
+            calledPaths.push(String(url));
+            return String(url).endsWith('/whoami')
+                ? jsonResponse(403, { success: false, error: { code: 'FORBIDDEN', message: 'scoped' } })
+                : jsonResponse(200, { success: true, data: { memories: [] } });
+        });
+        const result = await dispatchToolKeyMode(AIS_URL, config, 'whoami', {}, fetchMock);
+        expect(calledPaths).toHaveLength(2);
+        expect(calledPaths[1]).toContain('/v1/agents/agent-42/memory?limit=1');
+        expect(result).toMatchObject({
+            success: true,
+            data: { agentId: 'agent-42', authMode: 'agent-api-key', keyValid: true, selfDescribed: false },
         });
     });
+    it('orientation_check: evaluates locally, without any fetch call', async () => {
+        const fetchMock = vi.fn();
+        const manifest = {
+            version: 1,
+            identity: '00000000-0000-4000-8000-000000000001',
+            requirements: { host: 'cloud-vm', account: 'fleet-account', channels: ['ais'] },
+            current: { host: 'cloud-vm', account: 'fleet-account', session: 'agent-key-1' },
+            evidence: {
+                session: 'agent-key-1', host: 'cloud-vm', account: 'fleet-account',
+                credentials: 'pass', credentialSource: 'ais-agent-key',
+                channels: { ais: 'pass', mcp: 'missing', inbox: 'missing' },
+            },
+            relocation: { verified: false },
+        };
+        const result = await dispatchToolKeyMode(AIS_URL, config, 'orientation_check', manifest, fetchMock);
+        expect(fetchMock).not.toHaveBeenCalled();
+        expect(result).toMatchObject({ scope: 'public-orientation', exitCode: 0 });
+    });
+});
+describe('aisKeyGet retries once on a transient 502/503 (CORBOT-6F45EDFA)', () => {
+    // Mirrors ais-http.test.ts's aisGet retry coverage (CORBOT-9492F31A):
+    // the same idempotent-GET reasoning applies to x-agent-api-key GETs.
+    it('bounds scoped-key GETs with an abort signal so whoami cannot hang indefinitely', async () => {
+        const fetchMock = vi.fn(async () => jsonResponse(200, { success: true, data: { id: 'agent-42' } }));
+        await expect(aisKeyGet(AIS_URL, '/v1/agents/agent-42/whoami', 'ais_ak_scoped', fetchMock)).resolves.toEqual({ success: true, data: { id: 'agent-42' } });
+        const [, init] = fetchMock.mock.calls[0];
+        expect(init?.signal).toBeInstanceOf(AbortSignal);
+    });
+    it('times out with a clear error instead of hanging when AIS never responds (issue #6635)', async () => {
+        process.env['AIS_MCP_REQUEST_TIMEOUT_MS'] = '20';
+        const hangingFetch = vi.fn((_url, init) => new Promise((_resolve, reject) => {
+            init?.signal?.addEventListener('abort', () => reject(init.signal.reason));
+        }));
+        await expect(aisKeyGet(AIS_URL, '/v1/agents/agent-42/whoami', 'ais_ak_scoped', hangingFetch)).rejects.toThrow('AIS request to /v1/agents/agent-42/whoami timed out after 20ms');
+        delete process.env['AIS_MCP_REQUEST_TIMEOUT_MS'];
+    });
+    it('retries once on a 502 and returns the retry success', async () => {
+        const successBody = { success: true, data: { id: 'agent-42' } };
+        const fetchMock = vi.fn();
+        fetchMock
+            .mockResolvedValueOnce(new Response('upstream error', { status: 502 }))
+            .mockResolvedValueOnce(jsonResponse(200, successBody));
+        await expect(aisKeyGet(AIS_URL, '/v1/agents/agent-42', 'ais_ak_scoped', fetchMock)).resolves.toEqual(successBody);
+        expect(fetchMock).toHaveBeenCalledTimes(2);
+    });
+    it('retries once on a 503 and returns the retry success', async () => {
+        const successBody = { success: true, data: { id: 'agent-42' } };
+        const fetchMock = vi.fn();
+        fetchMock
+            .mockResolvedValueOnce(new Response('service unavailable', { status: 503 }))
+            .mockResolvedValueOnce(jsonResponse(200, successBody));
+        await expect(aisKeyGet(AIS_URL, '/v1/agents/agent-42', 'ais_ak_scoped', fetchMock)).resolves.toEqual(successBody);
+        expect(fetchMock).toHaveBeenCalledTimes(2);
+    });
+    it('only retries once — a second 502 still throws AisHttpError', async () => {
+        const fetchMock = vi.fn(async () => jsonResponse(502, { error: { code: 'UPSTREAM', message: 'upstream error' } }));
+        await expect(aisKeyGet(AIS_URL, '/v1/agents/agent-42', 'ais_ak_scoped', fetchMock)).rejects.toBeInstanceOf(AisHttpError);
+        expect(fetchMock).toHaveBeenCalledTimes(2);
+    });
+    it('does not retry non-retryable statuses (e.g. 500)', async () => {
+        const fetchMock = vi.fn(async () => jsonResponse(500, { error: { code: 'INTERNAL', message: 'server error' } }));
+        await expect(aisKeyGet(AIS_URL, '/v1/agents/agent-42', 'ais_ak_scoped', fetchMock)).rejects.toBeInstanceOf(AisHttpError);
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+    });
 });
 describe('dispatchToolKeyMode — inbox tools (CORBOT-7115B8AE, in-scope per CORBOT-04DABA89)', () => {
     const config = { apiKey: 'ais_ak_scoped', agentId: 'agent-42' };