aismemory 0.7.1 → 0.7.3

package/dist/index.js

@@ -9,27 +9,33 @@
  */
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { readFileSync } from 'node:fs';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { tryKeyAuth, enrollKeyIfNeeded, hasEnrolledKey } from './key-auth.js';
-import { isCredsStale, isAuthErrorResult } from './auth-staleness.js';
+import { isCredsStale, isAuthErrorResult, isNoRegisteredKeysAuthError } from './auth-staleness.js';
 import { AisHttpError } from './ais-http-error.js';
+import { aisGet, aisPost, aisPatch } from './ais-http.js';
 import { CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
-import { homedir } from 'os';
-import { loadOAuthCredentials, saveOAuthCredentials } from './oauth-credentials.js';
+import { homedir } from 'node:os';
+import { loadOAuthCredentials, loadNonStaleDiskBearer, saveOAuthCredentials, } from './oauth-credentials.js';
 import { saveAgentPreference, loadAgentPreference, migrateCredentialsFileIfNeeded } from './agent-preference.js';
-import { createTokenManager } from './token-manager.js';
+import { createTokenManager, isNoRegisteredKeyFailure } from './token-manager.js';
 import { hydrateIdentity } from './hydration.js';
 import { assemblePrompt } from './prompt-resource.js';
 import { startRefreshTimer, stopRefreshTimer } from './refresh.js';
 import { ActivityTracker, setupAutoHandoff } from './auto-handoff.js';
 import { assertEnvAgentInTenant, selectAgentForSession } from './env-agent.js';
 import { emitTelemetry, hashAgentId } from './telemetry.js';
-import { parseAgentLoadArgs, parseEmptyToolArgs, parseHandoffArgs, parseRecallArgs, parseRememberArgs, } from './tool-args.js';
+import { parseAgentLoadArgs, parseEmptyToolArgs, parseHandoffArgs, parseRecallArgs, parseFullContextArgs, parseRememberArgs, parseInboxSendArgs, parseInboxReadArgs, parseInboxAckArgs, parseGoalCreateArgs, parseGoalListArgs, parseGoalUpdateProgressArgs, parseGoalCompleteArgs, INBOX_MAX_BODY_CHARS, INBOX_MAX_TASK_ID_CHARS, INBOX_MIN_TTL_SECONDS, INBOX_MAX_TTL_SECONDS, INBOX_DEFAULT_TTL_SECONDS, INBOX_MAX_PAGE_SIZE, INBOX_DEFAULT_PAGE_SIZE, INBOX_MAX_ACK_IDS, GOAL_MAX_TITLE_CHARS, GOAL_MAX_DESCRIPTION_CHARS, GOAL_MAX_CRITERIA_ITEMS, GOAL_DEFAULT_PAGE_SIZE, GOAL_MAX_PAGE_SIZE, } from './tool-args.js';
+import { loadHarnessIdentity, installHarnessIdentity, optionValue, assertPinnedAgent, verifyPinnedIdentity, requiresIdentityGate } from './harness-identity.js';
+import { readInboxAndMaybeAck } from './inbox-client.js';
 import { runPollLoop, DeviceFlowRestartedError } from './device-poll.js';
 import { loadAgentApiKeyConfig, AgentApiKeyConfigError, dispatchToolKeyMode, UNKNOWN_TOOL_KEY_MODE, } from './agent-key-mode.js';
+import { loadWorkspaceKeyConfig, WorkspaceKeyConfigError, dispatchToolWorkspaceKeyMode, UNKNOWN_TOOL_WORKSPACE_KEY_MODE, } from './workspace-key-mode.js';
 // ── Config ──────────────────────────────────────────────
 const AIS_URL = process.env['AIS_URL'] ?? 'https://ais.agentsandswarms.ai';
 const PACKAGE_VERSION = readPackageVersion();
+let harnessIdentity = null;
 function readPackageVersion() {
     const packageJsonUrl = new URL('../package.json', import.meta.url);
     const packageJson = JSON.parse(readFileSync(packageJsonUrl, 'utf-8'));
@@ -65,71 +71,24 @@ function loadCredentials() {
 function stderr(msg) {
     process.stderr.write(`[aismemory] ${msg}\n`);
 }
-async function aisPost(path, body, token) {
-    const headers = { 'Content-Type': 'application/json' };
-    if (token)
-        headers['Authorization'] = `Bearer ${token}`;
-    let res;
-    try {
-        res = await fetch(`${AIS_URL}${path}`, {
-            method: 'POST',
-            headers,
-            body: JSON.stringify(body),
-        });
-    }
-    catch (err) {
-        emitTelemetry({
-            event: 'ais.http.failure',
-            path,
-            error: err instanceof Error ? err.message : String(err),
-        });
-        throw err;
-    }
-    const data = await res.json().catch(() => null);
-    if (!res.ok) {
-        emitTelemetry({
-            event: 'ais.http.failure',
-            path,
-            httpStatus: res.status,
-            error: `HTTP ${res.status}`,
-        });
-        // Token-rejection bodies feed the silent re-auth-and-retry loop; every
-        // other non-2xx must throw so a failed write surfaces as an MCP error
-        // instead of being mistaken for a successful one.
-        if (isAuthErrorResult(data))
-            return data;
-        throw new AisHttpError(res.status, path, data);
-    }
-    return data;
+function isSafeClaudeSessionId(sessionId) {
+    return sessionId !== '.' && sessionId !== '..' && /^[A-Za-z0-9._-]+$/.test(sessionId);
 }
-async function aisGet(path, token) {
-    let res;
-    try {
-        res = await fetch(`${AIS_URL}${path}`, {
-            headers: { 'Authorization': `Bearer ${token}` },
-        });
+function persistClaudeSessionAgentName(sessionId, agentName) {
+    if (!sessionId)
+        return;
+    if (!isSafeClaudeSessionId(sessionId)) {
+        stderr('Skipping Claude session marker: CLAUDE_SESSION_ID contains unsafe path characters');
+        return;
     }
-    catch (err) {
-        emitTelemetry({
-            event: 'ais.http.failure',
-            path,
-            error: err instanceof Error ? err.message : String(err),
-        });
-        throw err;
+    try {
+        const sessionsDir = join(homedir(), '.claude', 'ais-agent-sessions');
+        mkdirSync(sessionsDir, { recursive: true });
+        writeFileSync(join(sessionsDir, sessionId), agentName, 'utf-8');
     }
-    const data = await res.json().catch(() => null);
-    if (!res.ok) {
-        emitTelemetry({
-            event: 'ais.http.failure',
-            path,
-            httpStatus: res.status,
-            error: `HTTP ${res.status}`,
-        });
-        if (isAuthErrorResult(data))
-            return data;
-        throw new AisHttpError(res.status, path, data);
+    catch (error) {
+        stderr(`Skipping Claude session marker: ${error instanceof Error ? error.message : String(error)}`);
     }
-    return data;
 }
 /**
  * Fetch EVERY agent in the tenant, following server pagination.
@@ -182,13 +141,13 @@ async function resolveAgentForLoad(token, query) {
  * User can override with AIS_AGENT_ID or AIS_AGENT_NAME env vars.
  */
 async function resolveAgent(token, fallbackAgentId, fallbackTenantId, preferredAgentId) {
-    // Explicit env var overrides everything — must belong to this tenant.
-    const envAgentId = process.env['AIS_AGENT_ID'];
+    // The harness pin overrides shared preferences and must belong to this tenant.
+    const envAgentId = harnessIdentity?.agentId;
     if (envAgentId) {
         const agents = await listAllAgents(token);
         try {
             const match = assertEnvAgentInTenant(envAgentId, agents);
-            stderr(`Using agent from AIS_AGENT_ID: ${match.name} (${match.id})`);
+            stderr(`Using pinned agent: ${match.name} (${match.id})`);
             return { agentId: match.id, tenantId: fallbackTenantId };
         }
         catch (error) {
@@ -237,6 +196,11 @@ async function resolveAgent(token, fallbackAgentId, fallbackTenantId, preferredA
         return { agentId: fallbackAgentId, tenantId: fallbackTenantId };
     }
 }
+const MISSING_CREDENTIAL_HELP = 'Missing AIS credential: no authenticated aismemory MCP session, AIS_WORKSPACE_KEY / AIS_API_KEY, or usable local OAuth cache. ' +
+    'Connect aismemory and complete AIS sign-in, or ask your workspace owner for a scoped ais_wk_ key ' +
+    '(ais_ak_ for a single agent) and configure AIS_WORKSPACE_KEY / AIS_API_KEY with AIS_AGENT_ID. ' +
+    'Local sign-in can use ~/.aismemory/credentials.json. ' +
+    'Railway is an operator-only last resort for locating an existing scoped key; client surfaces never fetch AIS_SERVICE_KEY or DATABASE_URL.';
 /**
  * Bond URL/code surfaced when a tool is called before the user has approved
  * the device flow. Caller catches this and returns a friendly error to the MCP
@@ -247,7 +211,7 @@ class BondPendingError extends Error {
     userCode;
     bondPending = true;
     constructor(verificationUri, userCode) {
-        super(`Memory bond required — ask your human to approve now.\n\n` +
+        super(`Memory bond required — ask your human to approve now.\n\n${MISSING_CREDENTIAL_HELP}\n\n` +
             `Visit: ${verificationUri}\n` +
             `Code: ${userCode}\n\n` +
             `Enter your email and tap Approve, then retry this tool. Takes about 30 seconds.\n` +
@@ -396,9 +360,10 @@ flowRef) {
     // reconnected silently. migrateCredentialsFileIfNeeded() (agent-preference.ts)
     // is what later removes this token from disk, once a key gets enrolled.
     if (hasEnrolledKey()) {
-        saveAgentPreference({ agentId: creds.agentId, tenantId: creds.tenantId });
+        if (!harnessIdentity)
+            saveAgentPreference({ agentId: creds.agentId, tenantId: creds.tenantId });
     }
-    else {
+    else if (!harnessIdentity) {
         saveOAuthCredentials(creds);
     }
     stderr('Authenticated successfully!');
@@ -423,13 +388,15 @@ const tools = [
     },
     {
         name: 'recall',
-        description: 'Search memories by natural language query.',
+        description: "Search memories by natural language query. Set principalAgentId to search a DIFFERENT " +
+            "agent's memories under a 'memory:read' grant from that agent's owner.",
         inputSchema: {
             type: 'object',
             properties: {
                 query: { type: 'string', description: 'Search query' },
                 limit: { type: 'number', description: 'Max results (default 10)' },
                 type: { type: 'string', enum: ['fact', 'event', 'lesson', 'context', 'goal', 'task'], description: 'Filter by type' },
+                principalAgentId: { type: 'string', description: "Optional: search ANOTHER agent's memories instead of your own (its agent UUID). Requires that agent's owner to have granted you the 'memory:read' scope and that you share a tenant; otherwise the call is refused with 403. Read-only — your own identity and write access are unchanged." },
             },
             required: ['query'],
         },
@@ -441,8 +408,15 @@ const tools = [
     },
     {
         name: 'full_context',
-        description: 'Load the full agent context — identity, personality, goals, facts, skills, and last handoff.',
-        inputSchema: { type: 'object', properties: {} },
+        description: 'Load the full agent context — identity, personality, goals, facts, skills, and last handoff. ' +
+            "Set principalAgentId to load ANOTHER agent's context under a 'memory:read' grant.",
+        inputSchema: {
+            type: 'object',
+            properties: {
+                principalAgentId: { type: 'string', description: "Optional: search ANOTHER agent's memories instead of your own (its agent UUID). Requires that agent's owner to have granted you the 'memory:read' scope and that you share a tenant; otherwise the call is refused with 403. Read-only — your own identity and write access are unchanged." },
+                memoriesLimit: { type: 'number', description: 'Number of memories to load (1-50, default 5). Lower values reduce context size.' },
+            },
+        },
     },
     {
         name: 'dream',
@@ -471,10 +445,185 @@ const tools = [
                     type: 'string',
                     description: 'Agent name to look up (e.g., "Corbot", "Data", "code-assistant")',
                 },
+                memoriesLimit: { type: 'integer', minimum: 1, maximum: 50, description: 'Number of memories to load (1-50). Omit to use the AIS default.' },
             },
             required: ['query'],
         },
     },
+    // Agent inbox (CORBOT-7115B8AE / server-side CORBOT-6194EDC3) — mirrors
+    // packages/agent-identity-service/src/mcp/tools/inbox-tools.ts, which this
+    // package cannot import (it ships standalone to npm).
+    {
+        name: 'inbox_send',
+        description: 'Send a message to another agent that holds an AIS identity in your tenant — hand off a task, ask a peer a question, ' +
+            'report an update, flag a decision, or acknowledge something they sent you. ' +
+            'Call it when you have something a specific peer needs and you are not going to wait for the answer: delivery is pull-based, ' +
+            'so the message sits in their inbox until they next call inbox_read, and nothing wakes the agent — never block your turn on a reply. ' +
+            "Fields: recipientAgentId is the peer's AIS agent id; kind labels the intent so the reader can triage; body is the message itself. " +
+            'Set threadId (and inReplyTo) to continue an existing exchange rather than starting a new one, taskId to tie the message to a ticket, ' +
+            'messageId to make a retry idempotent (a re-send of the same id delivers nothing twice and comes back with duplicate: true), ' +
+            'and ttlSeconds to shorten how long the message survives unread (default 7 days).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                recipientAgentId: {
+                    type: 'string',
+                    description: "The peer's AIS agent id (uuid). Must be an active agent in your own tenant; anything else is reported as not found.",
+                },
+                kind: {
+                    type: 'string',
+                    enum: ['task', 'update', 'question', 'decision', 'handoff', 'ack'],
+                    description: "Intent label the reader triages on: 'task' (do this), 'update' (status, no action), 'question' (needs an answer), " +
+                        "'decision' (a fork the peer owns), 'handoff' (work is now theirs), 'ack' (received/acted).",
+                },
+                body: {
+                    type: 'string',
+                    description: `Message body, 1-${INBOX_MAX_BODY_CHARS} characters. Write it for a peer with no view of your session: say what it is and what you want back.`,
+                },
+                threadId: {
+                    type: 'string',
+                    description: 'Optional uuid of an existing exchange to continue. Omit to start a new thread — the first message becomes its own thread root.',
+                },
+                taskId: {
+                    type: 'string',
+                    description: `Optional ticket or task identifier this message belongs to, up to ${INBOX_MAX_TASK_ID_CHARS} characters (e.g. a kanban ticket id).`,
+                },
+                inReplyTo: {
+                    type: 'string',
+                    description: 'Optional uuid of the specific message being answered.',
+                },
+                messageId: {
+                    type: 'string',
+                    description: 'Optional client-generated uuid for idempotency. Re-sending an id already stored delivers nothing new and returns duplicate: true, ' +
+                        'so a retried call after a timeout cannot double-deliver.',
+                },
+                ttlSeconds: {
+                    type: 'number',
+                    description: `Optional lifetime in seconds, ${INBOX_MIN_TTL_SECONDS}-${INBOX_MAX_TTL_SECONDS} (default ${INBOX_DEFAULT_TTL_SECONDS}, one week). After it the message is purged whether read or not.`,
+                },
+            },
+            required: ['recipientAgentId', 'kind', 'body'],
+        },
+    },
+    {
+        name: 'inbox_read',
+        description: 'Read the messages other agents have sent you, oldest first. ' +
+            'Call it at the start of every turn and after any wake-up — delivery is pull-based and nothing wakes the agent, ' +
+            'so a peer\'s task or question is invisible until you read for it. ' +
+            'It returns only unread messages by default; pass ack: true once you have taken them in so they stop being returned, ' +
+            'and unreadOnly: false to re-read messages you already acked (they survive until their TTL). ' +
+            'Use limit to size the page and pass the returned nextCursor back as cursor to continue; a null nextCursor means you have reached the end. ' +
+            'unreadRemaining, when present, is how many unread messages are still waiting after this read.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                cursor: {
+                    type: 'string',
+                    description: 'Opaque cursor from a previous call\'s nextCursor. Omit to start from the oldest message.',
+                },
+                limit: {
+                    type: 'number',
+                    description: `Maximum messages to return, 1-${INBOX_MAX_PAGE_SIZE} (default ${INBOX_DEFAULT_PAGE_SIZE}).`,
+                },
+                unreadOnly: {
+                    type: 'boolean',
+                    description: 'Return only messages you have not acked. Defaults to true; set false to re-read the full stream including acked messages.',
+                },
+                ack: {
+                    type: 'boolean',
+                    description: 'Ack the messages this call returns, so they stop coming back as unread. Defaults to false; set true when you have actually read them ' +
+                        'and intend to act — acking is a read cursor, not a delete, so an acked message is still readable with unreadOnly: false until its TTL.',
+                },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'inbox_ack',
+        description: 'Ack specific inbox messages by id without doing a fresh inbox_read — use it when you already know the ' +
+            'messageIds (e.g. from a prior inbox_read you did not ack at the time) and just need to mark them handled ' +
+            'so they stop coming back as unread.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                messageIds: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: `Ids of the messages to ack, 1-${INBOX_MAX_ACK_IDS} items.`,
+                },
+            },
+            required: ['messageIds'],
+        },
+    },
+    // Goal tools (CORBOT-721e9a8b, L4 one-client-surface) — the same lifecycle
+    // as agent-identity-service/src/mcp/tools/goal-tools.ts, wired through this
+    // package's existing REST connection rather than a second server.
+    {
+        name: 'goal_create',
+        description: 'Create a new goal for the current agent. Goals track progress and success rates over time.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                title: { type: 'string', description: `Title of the goal, up to ${GOAL_MAX_TITLE_CHARS} characters.` },
+                description: { type: 'string', description: `Detailed description of what needs to be accomplished, up to ${GOAL_MAX_DESCRIPTION_CHARS} characters.` },
+                successCriteria: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: `List of criteria that define successful completion, up to ${GOAL_MAX_CRITERIA_ITEMS} items.`,
+                },
+                parentGoalId: { type: 'string', description: 'Id of the parent goal, if this is a sub-goal.' },
+            },
+            required: ['title', 'description'],
+        },
+    },
+    {
+        name: 'goal_list',
+        description: 'List goals for the current agent, with optional status and parent-goal filters.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                status: {
+                    type: 'string',
+                    enum: ['draft', 'active', 'completing', 'completed', 'failed', 'cancelled'],
+                    description: 'Filter by goal status.',
+                },
+                page: { type: 'number', description: 'Page number (default 1).' },
+                limit: { type: 'number', description: `Maximum goals per page, 1-${GOAL_MAX_PAGE_SIZE} (default ${GOAL_DEFAULT_PAGE_SIZE}).` },
+                parentGoalId: { type: 'string', description: 'Filter to sub-goals of this parent goal id.' },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'goal_update_progress',
+        description: 'Update the progress (0-100) of a goal the current agent owns.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                goalId: { type: 'string', description: 'The id of the goal.' },
+                progress: { type: 'number', minimum: 0, maximum: 100, description: 'Progress percentage (0-100).' },
+            },
+            required: ['goalId', 'progress'],
+        },
+    },
+    {
+        name: 'goal_complete',
+        description: 'Mark a goal as complete (success or failure). Records the outcome for success-rate tracking.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                goalId: { type: 'string', description: 'The id of the goal.' },
+                success: { type: 'boolean', description: 'Whether the goal was successfully completed.' },
+                notes: { type: 'string', description: 'Completion notes.' },
+                lessonsLearned: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: `Lessons learned during goal execution, up to ${GOAL_MAX_CRITERIA_ITEMS} items.`,
+                },
+            },
+            required: ['goalId', 'success'],
+        },
+    },
 ];
 // ── MCP Server ──────────────────────────────────────────
 /**
@@ -494,6 +643,82 @@ function decodeJwtClaims(token) {
         return {};
     }
 }
+/**
+ * MCP server entrypoint for workspace-key auth mode (CORBOT-3103ED88).
+ *
+ * Like agent-API-key mode but supports agent_load: when agent_load succeeds,
+ * the active agentId is updated for subsequent calls. The workspace key can
+ * access multiple agents within a workspace (subject to server grants).
+ */
+async function runWorkspaceKeyModeServer(config) {
+    // Mutable copy so agent_load can switch the active agent.
+    let activeConfig = { ...config };
+    stderr(`Workspace key auth mode — agent starts at ${activeConfig.agentId} (agent_load can switch).`);
+    const server = new Server({ name: 'aismemory', version: PACKAGE_VERSION }, { capabilities: { tools: {}, prompts: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+    server.setRequestHandler(ListPromptsRequestSchema, async () => ({ prompts: [] }));
+    server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+        throw new Error(`Unknown prompt: ${request.params.name}`);
+    });
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        const rawArgs = args ?? {};
+        activityTracker.recordToolUse(name);
+        const toolStartedAt = Date.now();
+        try {
+            const callConfig = activeConfig;
+            if (requiresIdentityGate(name, rawArgs)) {
+                await verifyPinnedIdentity(harnessIdentity, callConfig.agentId, () => dispatchToolWorkspaceKeyMode(AIS_URL, callConfig, 'whoami', {}));
+            }
+            const result = await dispatchToolWorkspaceKeyMode(AIS_URL, callConfig, name, rawArgs);
+            if (result === UNKNOWN_TOOL_WORKSPACE_KEY_MODE) {
+                return {
+                    content: [{ type: 'text', text: JSON.stringify({ error: `Unknown tool: ${name}` }) }],
+                    isError: true,
+                };
+            }
+            // agent_load: update the active agentId for subsequent calls.
+            if (name === 'agent_load' &&
+                typeof result === 'object' &&
+                result !== null &&
+                'switched' in result &&
+                result.switched) {
+                const switchResult = result;
+                if (harnessIdentity) {
+                    await verifyPinnedIdentity(harnessIdentity, switchResult.agentId, () => dispatchToolWorkspaceKeyMode(AIS_URL, { ...callConfig, agentId: switchResult.agentId }, 'whoami', {}));
+                }
+                activeConfig = { ...activeConfig, agentId: switchResult.agentId };
+                stderr(`Switched active agent to ${switchResult.agentId}`);
+            }
+            emitTelemetry({
+                event: 'tool.call',
+                tool: name,
+                agentIdHash: hashAgentId(activeConfig.agentId),
+                latencyMs: Date.now() - toolStartedAt,
+                status: 'ok',
+            });
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'Unknown error';
+            emitTelemetry({
+                event: 'tool.call',
+                tool: name,
+                agentIdHash: hashAgentId(activeConfig.agentId),
+                latencyMs: Date.now() - toolStartedAt,
+                status: 'error',
+                error: message,
+            });
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ error: message }) }],
+                isError: true,
+            };
+        }
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    stderr(`MCP server running (workspace key mode). Tools: ${tools.map((t) => t.name).join(', ')}`);
+}
 /**
  * MCP server entrypoint for agent-API-key auth mode (CORBOT-B1D3244C).
  *
@@ -519,6 +744,9 @@ async function runAgentKeyModeServer(config) {
         activityTracker.recordToolUse(name);
         const toolStartedAt = Date.now();
         try {
+            if (requiresIdentityGate(name, rawArgs)) {
+                await verifyPinnedIdentity(harnessIdentity, config.agentId, () => dispatchToolKeyMode(AIS_URL, config, 'whoami', {}));
+            }
             const result = await dispatchToolKeyMode(AIS_URL, config, name, rawArgs);
             if (result === UNKNOWN_TOOL_KEY_MODE) {
                 return {
@@ -566,16 +794,43 @@ async function main() {
         return; // sync-memory.ts calls process.exit() on failure
     }
     if (process.argv[2] === 'doctor') {
-        await import('./cli/doctor.js');
+        await (await import('./cli/doctor.js')).main(process.argv.slice(3));
         return; // doctor.ts calls process.exit() itself
     }
+    if (process.argv[2] === 'install') {
+        const source = optionValue(process.argv.slice(3), '--manifest');
+        if (!source)
+            throw new Error('Usage: aismemory install --manifest <file>');
+        const pin = installHarnessIdentity(source);
+        process.stdout.write(`Installed identity pin for ${pin.harness}: ${pin.agentId}. Launch: aismemory --harness ${pin.harness}\nVerify: aismemory doctor --harness ${pin.harness}\n`);
+        return;
+    }
+    harnessIdentity = loadHarnessIdentity();
+    const adapterEnv = { ...process.env, AIS_AGENT_ID: harnessIdentity?.agentId };
+    // Workspace key auth mode (CORBOT-3103ED88) — multi-agent workspace
+    // credentials. Checked FIRST: workspace key -> agent API key -> device flow.
+    let workspaceKeyConfig;
+    try {
+        workspaceKeyConfig = loadWorkspaceKeyConfig(adapterEnv);
+    }
+    catch (err) {
+        if (err instanceof WorkspaceKeyConfigError) {
+            stderr(err.message);
+            process.exit(1);
+        }
+        throw err;
+    }
+    if (workspaceKeyConfig) {
+        await runWorkspaceKeyModeServer(workspaceKeyConfig);
+        return;
+    }
     // Agent API key auth mode (CORBOT-B1D3244C) — unattended machines. Checked
     // before any device-flow / OAuth-credential / DID-key-auth setup below so
     // this mode NEVER falls back to those paths (that fallback is what used to
     // silently mint duplicate provisional agents in prod).
     let agentKeyConfig;
     try {
-        agentKeyConfig = loadAgentApiKeyConfig();
+        agentKeyConfig = loadAgentApiKeyConfig(adapterEnv);
     }
     catch (err) {
         if (err instanceof AgentApiKeyConfigError) {
@@ -591,6 +846,11 @@ async function main() {
     // Lazy-auth state. We connect the MCP transport before the user has approved
     // the device flow so Claude Code's 30s connection timeout is not blocked on
     // human approval. The first tool call surfaces the bond URL via its result.
+    // Capture any seeded register bearer before loadCredentials() migrates v1
+    // files away once a local DID key exists (F5a). qa-monitor seeds token +
+    // agentId while an unregistered key file may also be present; did-prove then
+    // 401s NO_REGISTERED_KEYS but this bearer still works for REST memory.
+    const diskBearerFallback = loadNonStaleDiskBearer();
     let creds = loadCredentials();
     let activeFlow = null;
     let postAuthDone = false;
@@ -616,16 +876,30 @@ async function main() {
     // background, retries with backoff, and never serializes a token to disk.
     const tokenManager = createTokenManager({
         authenticate: async () => {
-            const keyResult = await tryKeyAuth({ aisUrl: AIS_URL });
-            if (!keyResult)
-                throw new Error('no enrolled device key');
-            return { token: keyResult.token, expiresAt: keyResult.expiresAt };
+            try {
+                const keyResult = await tryKeyAuth({ aisUrl: AIS_URL });
+                if (!keyResult)
+                    throw new Error('no enrolled device key');
+                return { token: keyResult.token, expiresAt: keyResult.expiresAt };
+            }
+            catch (err) {
+                // Leftover local DID key + seeded register bearer (qa-monitor): did-prove
+                // 401s NO_REGISTERED_KEYS but the disk JWT still works for REST memory.
+                if (isNoRegisteredKeysAuthError(err)) {
+                    const diskBearer = diskBearerFallback ?? loadNonStaleDiskBearer();
+                    if (diskBearer) {
+                        return diskBearer;
+                    }
+                }
+                throw err;
+            }
         },
         resolveIdentity: async (token) => {
             const claims = decodeJwtClaims(token);
             const tenantId = claims.tenantId ?? '';
             const resolved = await resolveAgent(token, '', tenantId, loadAgentPreference()?.agentId);
-            saveAgentPreference({ agentId: resolved.agentId, tenantId: resolved.tenantId || tenantId });
+            if (!harnessIdentity)
+                saveAgentPreference({ agentId: resolved.agentId, tenantId: resolved.tenantId || tenantId });
             return { agentId: resolved.agentId, tenantId: resolved.tenantId || tenantId };
         },
         onEvent: (event, detail) => {
@@ -655,30 +929,53 @@ async function main() {
         // propagate to the tool result verbatim — that IS the structured
         // "no action needed, self-healing in the background" message.
         if (hasEnrolledKey()) {
-            const mc = await tokenManager.getCredentials();
-            if (!firstKeyAcquireDone) {
-                firstKeyAcquireDone = true;
-                emitTelemetry({ event: 'auth.key.success', agentIdHash: hashAgentId(mc.agentId) });
-                stderr('Authenticated via DID key auth (no browser required)');
+            try {
+                const mc = await tokenManager.getCredentials();
+                if (!firstKeyAcquireDone) {
+                    firstKeyAcquireDone = true;
+                    emitTelemetry({ event: 'auth.key.success', agentIdHash: hashAgentId(mc.agentId) });
+                    stderr('Authenticated via DID key auth (no browser required)');
+                }
+                // Compose token/expiresAt from the manager, but let a live agent_load
+                // switch win over the manager's cached identity — never let a renewal
+                // silently revert the session back to the originally-resolved agent.
+                creds = sessionAgentOverride
+                    ? { token: mc.token, expiresAt: mc.expiresAt, agentId: sessionAgentOverride.agentId, tenantId: sessionAgentOverride.tenantId }
+                    : mc;
+                if (!postAuthDone) {
+                    postAuthDone = true;
+                    void runPostAuth(creds);
+                }
+                return creds;
             }
-            // Compose token/expiresAt from the manager, but let a live agent_load
-            // switch win over the manager's cached identity — never let a renewal
-            // silently revert the session back to the originally-resolved agent.
-            creds = sessionAgentOverride
-                ? { token: mc.token, expiresAt: mc.expiresAt, agentId: sessionAgentOverride.agentId, tenantId: sessionAgentOverride.tenantId }
-                : mc;
-            if (!postAuthDone) {
-                postAuthDone = true;
-                void runPostAuth(creds);
+            catch (err) {
+                if (isNoRegisteredKeyFailure(err)) {
+                    const disk = loadOAuthCredentials();
+                    if (disk && !isCredsStale(disk.expiresAt, Date.now())) {
+                        emitTelemetry({ event: 'auth.key.fallback', agentIdHash: hashAgentId(disk.agentId) });
+                        stderr('Key auth reports no registered key server-side; falling back to disk OAuth bearer.');
+                        creds = disk;
+                        if (!postAuthDone) {
+                            postAuthDone = true;
+                            void runPostAuth(creds);
+                        }
+                        return creds;
+                    }
+                }
+                throw err;
             }
-            return creds;
         }
         // ── No-key path: browser device flow (unchanged bond URL semantics) ──
         if (creds && !isCredsStale(creds.expiresAt, Date.now())) {
             return creds;
         }
         if (!activeFlow || activeFlow.dead) {
-            activeFlow = await startDeviceFlow(activeFlow?.provisional_token);
+            try {
+                activeFlow = await startDeviceFlow(activeFlow?.provisional_token);
+            }
+            catch (error) {
+                throw new Error(`${MISSING_CREDENTIAL_HELP} AIS sign-in could not start; check AIS_URL and connectivity, then retry.`, { cause: error });
+            }
         }
         const sentinel = Symbol('bond-pending');
         // poll is always set by startDeviceFlow before it returns; this guard
@@ -724,7 +1021,8 @@ async function main() {
         });
     }
     /** Identity hydration, prompt refresh, and auto-handoff — all post-auth. */
-    async function runPostAuth(c) {
+    async function runPostAuth(credentials) {
+        const c = { ...credentials, agentId: harnessIdentity?.agentId ?? credentials.agentId };
         // Auto-enroll a DID key so re-auth stays silent after the 7-day bond
         // token expires. Without this, key enrollment was a manual opt-in step
         // (`enable-key-auth`) and every normal user was re-prompted to bond at
@@ -752,7 +1050,7 @@ async function main() {
             setupAutoHandoff(AIS_URL, c.agentId, c.token, activityTracker, () => {
                 stopRefreshTimer();
                 stderr('Session handoff saved');
-            });
+            }, () => verifyPinnedIdentity(harnessIdentity, c.agentId, () => aisGet(`/v1/agents/${c.agentId}`, c.token)));
         }
         catch (e) {
             stderr(`Post-auth setup failed: ${e instanceof Error ? e.message : String(e)}`);
@@ -782,11 +1080,17 @@ async function main() {
         activityTracker.recordToolUse(name);
         const toolStartedAt = Date.now();
         try {
+            if (requiresIdentityGate(name, rawArgs)) {
+                assertPinnedAgent(harnessIdentity, harnessIdentity?.agentId ?? 'unselected');
+            }
             const UNKNOWN_TOOL = Symbol('unknown-tool');
             const dispatchTool = async (c) => {
                 const token = c.token;
                 // agentId is mutable across `agent_load` calls within this session.
-                let agentId = c.agentId;
+                let agentId = harnessIdentity?.agentId ?? c.agentId;
+                if (requiresIdentityGate(name, rawArgs)) {
+                    await verifyPinnedIdentity(harnessIdentity, agentId, () => aisGet(`/v1/agents/${agentId}`, token));
+                }
                 let result;
                 switch (name) {
                     case 'remember': {
@@ -807,6 +1111,9 @@ async function main() {
                             params.set('limit', String(recallArgs.limit));
                         if (recallArgs.type !== undefined)
                             params.set('types', recallArgs.type);
+                        if (recallArgs.principalAgentId !== undefined) {
+                            params.set('principalAgentId', recallArgs.principalAgentId);
+                        }
                         result = await aisGet(`/v1/agents/${agentId}/memory?${params}`, token);
                         break;
                     }
@@ -814,10 +1121,20 @@ async function main() {
                         parseEmptyToolArgs(rawArgs);
                         result = await aisGet(`/v1/agents/${agentId}`, token);
                         break;
-                    case 'full_context':
-                        parseEmptyToolArgs(rawArgs);
-                        result = await aisGet(`/v1/agents/${agentId}/full-context`, token);
+                    case 'full_context': {
+                        const fcArgs = parseFullContextArgs(rawArgs);
+                        const fcParams = new URLSearchParams();
+                        if (fcArgs.principalAgentId !== undefined)
+                            fcParams.set('principalAgentId', fcArgs.principalAgentId);
+                        if (fcArgs.memoriesLimit !== undefined)
+                            fcParams.set('memoriesLimit', String(fcArgs.memoriesLimit));
+                        if (fcArgs.view !== undefined)
+                            fcParams.set('view', fcArgs.view);
+                        const fcQs = fcParams.toString();
+                        const fcPath = `/v1/agents/${agentId}/full-context${fcQs ? `?${fcQs}` : ''}`;
+                        result = await aisGet(fcPath, token);
                         break;
+                    }
                     case 'dream':
                         parseEmptyToolArgs(rawArgs);
                         result = await aisPost(`/v1/agents/${agentId}/dream`, {}, token);
@@ -831,8 +1148,11 @@ async function main() {
                         break;
                     }
                     case 'agent_load': {
-                        const { query } = parseAgentLoadArgs(rawArgs);
+                        const { query, memoriesLimit } = parseAgentLoadArgs(rawArgs);
                         const target = await resolveAgentForLoad(token, query);
+                        if (harnessIdentity)
+                            assertPinnedAgent(harnessIdentity, target.id);
+                        persistClaudeSessionAgentName(process.env.CLAUDE_SESSION_ID, target.name);
                         agentId = target.id;
                         // Persist the switch so subsequent tool calls use the new agent.
                         // saveAgentPreference() MUST be called here so that a process
@@ -846,9 +1166,10 @@ async function main() {
                         if (creds) {
                             creds = { ...creds, agentId };
                             sessionAgentOverride = { agentId, tenantId: creds.tenantId };
-                            saveAgentPreference({ agentId, tenantId: creds.tenantId });
+                            if (!harnessIdentity)
+                                saveAgentPreference({ agentId, tenantId: creds.tenantId });
                         }
-                        agentContext = await hydrateIdentity(AIS_URL, agentId, token);
+                        agentContext = await hydrateIdentity(AIS_URL, agentId, token, memoriesLimit);
                         applyMemoryRefresh(agentId, token);
                         server.notification({ method: 'notifications/prompts/list_changed' });
                         stderr(`agent_load: switched to "${target.name}" (${target.id})`);
@@ -863,6 +1184,74 @@ async function main() {
                         };
                         break;
                     }
+                    case 'inbox_send': {
+                        const inboxSendArgs = parseInboxSendArgs(rawArgs);
+                        result = await aisPost(`/v1/agents/${agentId}/inbox`, {
+                            recipientAgentId: inboxSendArgs.recipientAgentId,
+                            kind: inboxSendArgs.kind,
+                            body: inboxSendArgs.body,
+                            ...(inboxSendArgs.threadId !== undefined ? { threadId: inboxSendArgs.threadId } : {}),
+                            ...(inboxSendArgs.taskId !== undefined ? { taskId: inboxSendArgs.taskId } : {}),
+                            ...(inboxSendArgs.inReplyTo !== undefined ? { inReplyTo: inboxSendArgs.inReplyTo } : {}),
+                            ...(inboxSendArgs.messageId !== undefined ? { messageId: inboxSendArgs.messageId } : {}),
+                            ...(inboxSendArgs.ttlSeconds !== undefined ? { ttlSeconds: inboxSendArgs.ttlSeconds } : {}),
+                        }, token);
+                        break;
+                    }
+                    case 'inbox_read': {
+                        const inboxReadArgs = parseInboxReadArgs(rawArgs);
+                        const inboxParams = new URLSearchParams();
+                        if (inboxReadArgs.cursor !== undefined)
+                            inboxParams.set('cursor', inboxReadArgs.cursor);
+                        inboxParams.set('limit', String(inboxReadArgs.limit));
+                        inboxParams.set('unreadOnly', String(inboxReadArgs.unreadOnly));
+                        result = await readInboxAndMaybeAck(inboxReadArgs, () => aisGet(`/v1/agents/${agentId}/inbox?${inboxParams}`, token), (messageIds) => aisPost(`/v1/agents/${agentId}/inbox/ack`, { messageIds }, token));
+                        break;
+                    }
+                    case 'inbox_ack': {
+                        const inboxAckArgs = parseInboxAckArgs(rawArgs);
+                        result = await aisPost(`/v1/agents/${agentId}/inbox/ack`, { messageIds: inboxAckArgs.messageIds }, token);
+                        break;
+                    }
+                    case 'goal_create': {
+                        const goalCreateArgs = parseGoalCreateArgs(rawArgs);
+                        result = await aisPost(`/v1/agents/${agentId}/goals`, {
+                            title: goalCreateArgs.title,
+                            description: goalCreateArgs.description,
+                            ...(goalCreateArgs.successCriteria !== undefined ? { successCriteria: goalCreateArgs.successCriteria } : {}),
+                            ...(goalCreateArgs.parentGoalId !== undefined ? { parentGoalId: goalCreateArgs.parentGoalId } : {}),
+                        }, token);
+                        break;
+                    }
+                    case 'goal_list': {
+                        const goalListArgs = parseGoalListArgs(rawArgs);
+                        const goalParams = new URLSearchParams();
+                        if (goalListArgs.status !== undefined)
+                            goalParams.set('status', goalListArgs.status);
+                        if (goalListArgs.page !== undefined)
+                            goalParams.set('page', String(goalListArgs.page));
+                        goalParams.set('limit', String(goalListArgs.limit));
+                        if (goalListArgs.parentGoalId !== undefined)
+                            goalParams.set('parentGoalId', goalListArgs.parentGoalId);
+                        result = await aisGet(`/v1/agents/${agentId}/goals?${goalParams}`, token);
+                        break;
+                    }
+                    case 'goal_update_progress': {
+                        const goalProgressArgs = parseGoalUpdateProgressArgs(rawArgs);
+                        result = await aisPatch(`/v1/agents/${agentId}/goals/${goalProgressArgs.goalId}`, {
+                            progress: goalProgressArgs.progress,
+                        }, token);
+                        break;
+                    }
+                    case 'goal_complete': {
+                        const goalCompleteArgs = parseGoalCompleteArgs(rawArgs);
+                        result = await aisPost(`/v1/agents/${agentId}/goals/${goalCompleteArgs.goalId}/complete`, {
+                            success: goalCompleteArgs.success,
+                            ...(goalCompleteArgs.notes !== undefined ? { notes: goalCompleteArgs.notes } : {}),
+                            ...(goalCompleteArgs.lessonsLearned !== undefined ? { lessonsLearned: goalCompleteArgs.lessonsLearned } : {}),
+                        }, token);
+                        break;
+                    }
                     default:
                         emitTelemetry({
                             event: 'tool.call',
@@ -961,7 +1350,7 @@ async function main() {
         stderr('Device key enrolled — deferring session setup to the first key-auth token acquire.');
     }
     else {
-        stderr('No saved credentials. Bond URL will be surfaced on first tool call.');
+        stderr(`${MISSING_CREDENTIAL_HELP} Bond URL will be surfaced on first tool call.`);
     }
 }
 main().catch((error) => {