aismemory 0.7.4 → 0.8.0

package/dist/memory-pull.js

@@ -0,0 +1,171 @@
+/**
+ * Memory pull — read an agent's own memories back out of the Agent Identity
+ * Service and into a local JSON Lines backup (CORBOT-31C43CBD).
+ *
+ * WHY THIS EXISTS
+ * The package could only ever push local -> Agent Identity Service
+ * (LocalMirror, aismemory-sync). Nothing an agent API key can call brought
+ * memories back down, so memories written from the Claude app or from Codex
+ * never reached the local copy. The two export routes do not help a key-only
+ * caller:
+ *   * POST /v1/agents/:agentId/export          -> 403, `export` is not in the
+ *     agent-API-key allowlist (agentApiKeyAuth.ts ALLOWED_AGENT_SUBRESOURCES).
+ *   * POST /v1/agents/:agentId/memory/export    -> 400 "platform is required";
+ *     it pushes to a third-party platform adapter and refuses file paths over
+ *     HTTP, so it cannot produce a local file.
+ *
+ * WHAT THIS DOES INSTEAD
+ * Pages the browse path of GET /v1/agents/:agentId/memory, which IS already on
+ * the allowlist and already supports `limit` + `offset` pagination. No server
+ * change and no access scope change: this is a client that uses a route the
+ * key can call today.
+ *
+ * SCOPE SAFETY
+ * The agent id is taken from the caller's own configuration and interpolated
+ * into the path; the server additionally rejects any request whose path agent
+ * does not equal the agent the key encodes. `principalAgentId` (the delegated
+ * cross-agent read parameter) is never sent, so a pull can only ever read the
+ * caller's own memories.
+ */
+import { AisHttpError } from './ais-http-error.js';
+import { aisKeyGet } from './agent-key-mode.js';
+/**
+ * Server-side cap on `limit` for GET /v1/agents/:agentId/memory
+ * (agent-identity-service `env.benchQueryLimitCap`; a larger value is a 400).
+ */
+export const MAX_PAGE_SIZE = 100;
+/** Page size used when the caller does not choose one. */
+export const DEFAULT_PAGE_SIZE = 100;
+/**
+ * Hard stop on pages fetched, so a server that never reports exhaustion cannot
+ * spin forever. At the maximum page size this covers 500,000 memories, an order
+ * of magnitude above the 50,000 the `.aismem` export format itself allows.
+ */
+export const MAX_PAGES = 5_000;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+/**
+ * Pull `data.memories` and `data.totalCount` out of a browse response, rejecting
+ * anything that does not have the documented shape. A silently-empty parse would
+ * be indistinguishable from "this agent has no memories" and would write an
+ * empty backup over a good one.
+ */
+export function parseBrowsePage(payload) {
+    if (!isRecord(payload) || !isRecord(payload['data'])) {
+        throw new Error('Unexpected response from the memory browse route: no `data` object. ' +
+            'The Agent Identity Service may be returning an error page.');
+    }
+    const data = payload['data'];
+    const rawMemories = data['memories'];
+    if (!Array.isArray(rawMemories)) {
+        throw new Error('Unexpected response from the memory browse route: `data.memories` is not an array.');
+    }
+    const memories = [];
+    for (const entry of rawMemories) {
+        if (!isRecord(entry) || typeof entry['id'] !== 'string') {
+            throw new Error('Unexpected response from the memory browse route: a memory has no string `id`.');
+        }
+        memories.push(entry);
+    }
+    const rawTotal = data['totalCount'];
+    const totalCount = typeof rawTotal === 'number' && Number.isFinite(rawTotal) ? rawTotal : undefined;
+    return totalCount === undefined ? { memories } : { memories, totalCount };
+}
+/** Clamp a requested page size into the range the server accepts. */
+export function clampPageSize(requested) {
+    if (requested === undefined || !Number.isFinite(requested))
+        return DEFAULT_PAGE_SIZE;
+    const floored = Math.floor(requested);
+    if (floored < 1)
+        return 1;
+    if (floored > MAX_PAGE_SIZE)
+        return MAX_PAGE_SIZE;
+    return floored;
+}
+/**
+ * Page the whole corpus for one agent, newest first.
+ *
+ * Deduplicates by memory id. This is load-bearing rather than defensive: the
+ * browse path orders by `createdAt` descending, so a memory written while the
+ * walk is in progress lands at offset 0 and shifts every later row down one,
+ * which would otherwise re-read a row that has already been captured.
+ */
+export async function pullMemories(options) {
+    const { aisUrl, agentId, apiKey, fetchImpl, onProgress } = options;
+    const pageSize = clampPageSize(options.pageSize);
+    const seen = new Set();
+    const memories = [];
+    let offset = 0;
+    let pagesFetched = 0;
+    let totalCount;
+    let truncated = false;
+    for (;;) {
+        if (pagesFetched >= MAX_PAGES) {
+            truncated = true;
+            break;
+        }
+        const params = new URLSearchParams();
+        params.set('limit', String(pageSize));
+        params.set('offset', String(offset));
+        // Browse, not recall: no `query`, and relationship expansion off so a
+        // backup carries the stored memories rather than a graph walk around them.
+        params.set('expandRelationships', 'false');
+        const payload = await aisKeyGet(aisUrl, `/v1/agents/${encodeURIComponent(agentId)}/memory?${params.toString()}`, apiKey, fetchImpl);
+        pagesFetched += 1;
+        const page = parseBrowsePage(payload);
+        if (page.totalCount !== undefined)
+            totalCount = page.totalCount;
+        let added = 0;
+        for (const memory of page.memories) {
+            if (seen.has(memory.id))
+                continue;
+            seen.add(memory.id);
+            memories.push(memory);
+            added += 1;
+        }
+        onProgress?.(totalCount === undefined
+            ? { page: pagesFetched, added, total: memories.length }
+            : { page: pagesFetched, added, total: memories.length, totalCount });
+        // A short page means the corpus is exhausted. Advance by the page length
+        // actually returned, not by the number of NEW rows, or a shifted window
+        // would make the walk step backwards and never terminate.
+        if (page.memories.length < pageSize)
+            break;
+        offset += page.memories.length;
+    }
+    return totalCount === undefined
+        ? { memories, pagesFetched, truncated }
+        : { memories, pagesFetched, totalCount, truncated };
+}
+/**
+ * Render memories as JSON Lines: one memory object per line, in the order they
+ * were pulled (newest first). Always ends with a newline so the file can be
+ * appended to or concatenated cleanly.
+ */
+export function toJsonLines(memories) {
+    if (memories.length === 0)
+        return '';
+    return `${memories.map((memory) => JSON.stringify(memory)).join('\n')}\n`;
+}
+/**
+ * Turn an out-of-scope or rejected pull into a message that names the cause,
+ * rather than leaving a bare HTTP status for the operator to decode.
+ */
+export function describePullFailure(error) {
+    if (error instanceof AisHttpError) {
+        if (error.status === 401) {
+            return 'The Agent Identity Service rejected the agent API key (HTTP 401). Check AIS_API_KEY.';
+        }
+        if (error.status === 403) {
+            return ('The Agent Identity Service refused the read (HTTP 403). An agent API key may only read ' +
+                'its own memories — check that AIS_AGENT_ID is the agent this key was minted for.');
+        }
+        if (error.status === 404) {
+            return 'No such agent in this tenant (HTTP 404). Check AIS_AGENT_ID.';
+        }
+        return `The Agent Identity Service returned HTTP ${error.status}.`;
+    }
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=memory-pull.js.map

package/dist/memory-pull.js.map

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

package/dist/pending-device-flow.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Pending device-flow persistence (CORBOT-8F96A8EF).
+ *
+ * The orphan bug, client side. `startDeviceFlow` can hand the server the
+ * provisional token from an earlier un-finalized flow, and the server will
+ * then reuse that provisional agent instead of minting another
+ * (tryReuseProvisional, CORBOT-CDDC15FA). But the only place that token
+ * lived was `activeFlow`, a module-level variable — process-local, and null
+ * in every newly spawned process. A stdio server is respawned constantly, so
+ * in practice the token was almost never sent and sign-in minted a fresh
+ * agent nearly every run. That is where Jaire's leftovers came from.
+ *
+ * So the token is persisted next to the credentials file, under the same
+ * 0700 directory / 0600 file permissions: it is a bearer proof-of-session
+ * for an unbonded agent and must not be world-readable.
+ *
+ * It is deliberately NOT part of OAuthCredentials: those are the live bonded
+ * session, this is a half-finished sign-in. Keeping them in separate files
+ * means a stale pending flow can never be mistaken for a usable credential,
+ * and clearing one does not disturb the other.
+ */
+/**
+ * A device flow that started but was never bonded. `provisionalToken` is the
+ * only field the server needs; the rest is there so a human reading the file
+ * (or a support session) can tell what it belongs to.
+ */
+export interface PendingDeviceFlow {
+    provisionalToken: string;
+    agentId: string;
+    provisionalTenantId: string;
+    /** ISO timestamp of when this flow was started. */
+    startedAt: string;
+}
+/**
+ * Sits beside credentials.json, so it follows the same per-agent isolation
+ * that `credentialsFilePath` already implements (AIS_CREDENTIALS_FILE
+ * override, then AIS_AGENT_ID sub-directory, then the shared default).
+ */
+export declare function pendingDeviceFlowPath(home?: string): string;
+/** Persist the un-finalized flow so the next process reuses this agent. */
+export declare function savePendingDeviceFlow(flow: PendingDeviceFlow, home?: string): void;
+/**
+ * Read a still-usable pending flow, or null. Returns null (and does not
+ * throw) for a missing, unreadable, malformed, or expired file: every one of
+ * those means "no token to reuse", and the caller's fallback is correct.
+ */
+export declare function loadPendingDeviceFlow(home?: string, now?: number): PendingDeviceFlow | null;
+/** Drop the record once the flow has bonded (or is known dead). */
+export declare function clearPendingDeviceFlow(home?: string): void;

package/dist/pending-device-flow.js

@@ -0,0 +1,96 @@
+/**
+ * Pending device-flow persistence (CORBOT-8F96A8EF).
+ *
+ * The orphan bug, client side. `startDeviceFlow` can hand the server the
+ * provisional token from an earlier un-finalized flow, and the server will
+ * then reuse that provisional agent instead of minting another
+ * (tryReuseProvisional, CORBOT-CDDC15FA). But the only place that token
+ * lived was `activeFlow`, a module-level variable — process-local, and null
+ * in every newly spawned process. A stdio server is respawned constantly, so
+ * in practice the token was almost never sent and sign-in minted a fresh
+ * agent nearly every run. That is where Jaire's leftovers came from.
+ *
+ * So the token is persisted next to the credentials file, under the same
+ * 0700 directory / 0600 file permissions: it is a bearer proof-of-session
+ * for an unbonded agent and must not be world-readable.
+ *
+ * It is deliberately NOT part of OAuthCredentials: those are the live bonded
+ * session, this is a half-finished sign-in. Keeping them in separate files
+ * means a stale pending flow can never be mistaken for a usable credential,
+ * and clearing one does not disturb the other.
+ */
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { credentialsFilePath } from './oauth-credentials.js';
+/**
+ * Provisional tokens are signed with a 7-day expiry server-side, matching the
+ * claim window. Past that the server rejects reuse anyway, so a local record
+ * older than this is dead weight and is discarded rather than sent.
+ */
+const PENDING_FLOW_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+/**
+ * Sits beside credentials.json, so it follows the same per-agent isolation
+ * that `credentialsFilePath` already implements (AIS_CREDENTIALS_FILE
+ * override, then AIS_AGENT_ID sub-directory, then the shared default).
+ */
+export function pendingDeviceFlowPath(home = homedir()) {
+    return join(dirname(credentialsFilePath(home)), 'pending-device-flow.json');
+}
+/** Persist the un-finalized flow so the next process reuses this agent. */
+export function savePendingDeviceFlow(flow, home = homedir()) {
+    const file = pendingDeviceFlowPath(home);
+    try {
+        mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+        writeFileSync(file, JSON.stringify(flow, null, 2), { mode: 0o600 });
+        // writeFileSync's mode is umask-dependent; chmod is the reliable path.
+        if (process.platform !== 'win32') {
+            chmodSync(file, 0o600);
+        }
+    }
+    catch {
+        // Best effort only. A read-only or full home directory must not break
+        // sign-in — the caller simply falls back to minting, which is today's
+        // behavior, not a regression.
+    }
+}
+/**
+ * Read a still-usable pending flow, or null. Returns null (and does not
+ * throw) for a missing, unreadable, malformed, or expired file: every one of
+ * those means "no token to reuse", and the caller's fallback is correct.
+ */
+export function loadPendingDeviceFlow(home = homedir(), now = Date.now()) {
+    const file = pendingDeviceFlowPath(home);
+    try {
+        if (!existsSync(file))
+            return null;
+        const parsed = JSON.parse(readFileSync(file, 'utf-8'));
+        if (typeof parsed.provisionalToken !== 'string' || parsed.provisionalToken.length === 0) {
+            return null;
+        }
+        const startedAt = typeof parsed.startedAt === 'string' ? Date.parse(parsed.startedAt) : NaN;
+        if (Number.isFinite(startedAt) && now - startedAt > PENDING_FLOW_MAX_AGE_MS) {
+            return null;
+        }
+        return {
+            provisionalToken: parsed.provisionalToken,
+            agentId: typeof parsed.agentId === 'string' ? parsed.agentId : '',
+            provisionalTenantId: typeof parsed.provisionalTenantId === 'string' ? parsed.provisionalTenantId : '',
+            startedAt: typeof parsed.startedAt === 'string' ? parsed.startedAt : '',
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** Drop the record once the flow has bonded (or is known dead). */
+export function clearPendingDeviceFlow(home = homedir()) {
+    try {
+        rmSync(pendingDeviceFlowPath(home), { force: true });
+    }
+    catch {
+        // Same best-effort rationale as save: a stale file costs one rejected
+        // reuse attempt, which degrades to minting.
+    }
+}
+//# sourceMappingURL=pending-device-flow.js.map

package/dist/pending-device-flow.js.map

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

package/dist/retry-after.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Retry-After handling (Jaire C9, CORBOT-D452451A).
+ *
+ * AIS sends `Retry-After` on every 429 and 503. A read that is told to wait a
+ * few seconds waits and tries once more; a longer wait is not slept through
+ * inside a tool call — the error says, in plain words, how long to wait.
+ */
+/** Longest server-requested wait a GET sleeps through before its one retry. */
+export declare const MAX_HONOURED_RETRY_AFTER_SECONDS = 5;
+/** Statuses whose `Retry-After` means "back off, then the same call can work". */
+export declare const RETRY_AFTER_STATUSES: ReadonlySet<number>;
+/**
+ * Seconds to wait, from a `Retry-After` value (delta-seconds or HTTP-date).
+ * Null when the header is absent or unreadable.
+ */
+export declare function parseRetryAfterSeconds(value: string | null | undefined, nowMs?: number): number | null;
+/** The server's requested wait on a 429/503, or null when there is none. */
+export declare function retryAfterOf(res: {
+    status: number;
+    headers?: {
+        get(name: string): string | null;
+    };
+}): number | null;
+/** True when a GET should sleep `seconds` and try once more. */
+export declare function shouldHonourRetryAfter(seconds: number | null): seconds is number;
+export declare function sleepSeconds(seconds: number): Promise<void>;

package/dist/retry-after.js

@@ -0,0 +1,42 @@
+/**
+ * Retry-After handling (Jaire C9, CORBOT-D452451A).
+ *
+ * AIS sends `Retry-After` on every 429 and 503. A read that is told to wait a
+ * few seconds waits and tries once more; a longer wait is not slept through
+ * inside a tool call — the error says, in plain words, how long to wait.
+ */
+/** Longest server-requested wait a GET sleeps through before its one retry. */
+export const MAX_HONOURED_RETRY_AFTER_SECONDS = 5;
+/** Statuses whose `Retry-After` means "back off, then the same call can work". */
+export const RETRY_AFTER_STATUSES = new Set([429, 503]);
+/**
+ * Seconds to wait, from a `Retry-After` value (delta-seconds or HTTP-date).
+ * Null when the header is absent or unreadable.
+ */
+export function parseRetryAfterSeconds(value, nowMs = Date.now()) {
+    if (value === null || value === undefined)
+        return null;
+    const trimmed = value.trim();
+    if (/^\d+$/.test(trimmed))
+        return Number(trimmed);
+    if (!/[A-Za-z]/.test(trimmed))
+        return null;
+    const at = Date.parse(trimmed);
+    if (Number.isNaN(at))
+        return null;
+    return Math.max(0, Math.ceil((at - nowMs) / 1000));
+}
+/** The server's requested wait on a 429/503, or null when there is none. */
+export function retryAfterOf(res) {
+    if (!RETRY_AFTER_STATUSES.has(res.status))
+        return null;
+    return parseRetryAfterSeconds(res.headers?.get('retry-after'));
+}
+/** True when a GET should sleep `seconds` and try once more. */
+export function shouldHonourRetryAfter(seconds) {
+    return seconds !== null && seconds <= MAX_HONOURED_RETRY_AFTER_SECONDS;
+}
+export function sleepSeconds(seconds) {
+    return new Promise((resolve) => setTimeout(resolve, seconds * 1000));
+}
+//# sourceMappingURL=retry-after.js.map

package/dist/retry-after.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry-after.js","sourceRoot":"","sources":["../src/retry-after.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,+EAA+E;AAC/E,MAAM,CAAC,MAAM,gCAAgC,GAAG,CAAC,CAAC;AAElD,kFAAkF;AAClF,MAAM,CAAC,MAAM,oBAAoB,GAAwB,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;AAE7E;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAgC,EAAE,QAAgB,IAAI,CAAC,GAAG,EAAE;IACjG,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACvD,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC;IAClD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,IAAI,CAAC;IAC3C,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC/B,IAAI,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QAAE,OAAO,IAAI,CAAC;IAClC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,GAAG,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;AACrD,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,YAAY,CAAC,GAAuE;IAClG,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IACvD,OAAO,sBAAsB,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC;AACjE,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,sBAAsB,CAAC,OAAsB;IAC3D,OAAO,OAAO,KAAK,IAAI,IAAI,OAAO,IAAI,gCAAgC,CAAC;AACzE,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC;AACvE,CAAC"}

package/dist/session-identity.d.ts

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+declare const sessionIdentitySchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    source: z.ZodEnum<{
+        agent_load: "agent_load";
+        env: "env";
+    }>;
+    agentId: z.ZodString;
+}, z.core.$strict>;
+export type SessionIdentity = z.infer<typeof sessionIdentitySchema>;
+export declare const IDENTITY_REPAIR = "Set AIS_AGENT_ID for THIS session only \u2014 export it in the shell that launches aismemory, or set it in the env block of this session's own MCP config \u2014 then restart the session and run aismemory doctor. Switch agents inside a session with agent_load. Never pin a machine, install or harness to one agent; other sessions on this machine run as other agents.";
+/**
+ * Lists leftover per-harness manifest files from the removed machine-wide pin.
+ * They are read by nothing; doctor only reports them so a human can delete
+ * them deliberately. Never deletes anything.
+ */
+export declare function legacyHarnessManifests(home?: string): string[];
+/** Reads this process's own identity. No file, no shared state, no machine-wide pin. */
+export declare function loadSessionIdentity(env?: NodeJS.ProcessEnv): SessionIdentity | null;
+/** The identity this session holds after a successful in-session agent_load switch. */
+export declare function switchedTo(previous: SessionIdentity, agentId: string): SessionIdentity;
+export declare function assertPinnedAgent(pin: SessionIdentity | null, agentId: string): void;
+/** Verify the same whoami response exposed by the selected auth adapter, before every mutation. */
+export declare function verifyPinnedIdentity(pin: SessionIdentity | null, agentId: string, whoami: () => Promise<unknown>): Promise<void>;
+export declare function requiresIdentityGate(name: string, args: Record<string, unknown>): boolean;
+export {};

package/dist/session-identity.js

@@ -0,0 +1,89 @@
+/**
+ * Session identity — one identity per PROCESS, never per machine.
+ *
+ * A session's identity is chosen at launch through the AIS_AGENT_ID
+ * environment variable (exported in the launching shell, or set in the `env`
+ * block of that session's own MCP config) and can be switched in-session with
+ * the agent_load tool. Many agents run on one machine at the same time; that
+ * is the product. Nothing here pins a machine, an install or a harness to a
+ * single agent (CORBOT-FBDC8652).
+ *
+ * The gate below only REFUSES a write whose live agent does not match the
+ * identity this session selected. It never installs a pin anywhere, and it
+ * never reads shared per-machine state.
+ */
+import { readdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { z } from 'zod';
+const sessionIdentitySchema = z.object({
+    version: z.literal(1),
+    /** How this session's identity was selected. */
+    source: z.enum(['env', 'agent_load']),
+    agentId: z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9-]{0,127}$/),
+}).strict();
+export const IDENTITY_REPAIR = 'Set AIS_AGENT_ID for THIS session only — export it in the shell that launches aismemory, or set it in the env block of this session\'s own MCP config — then restart the session and run aismemory doctor. Switch agents inside a session with agent_load. Never pin a machine, install or harness to one agent; other sessions on this machine run as other agents.';
+/** The directory the removed per-harness manifest pin used to write to. */
+const LEGACY_HARNESS_DIR = ['.aismemory', 'harnesses'];
+/**
+ * Lists leftover per-harness manifest files from the removed machine-wide pin.
+ * They are read by nothing; doctor only reports them so a human can delete
+ * them deliberately. Never deletes anything.
+ */
+export function legacyHarnessManifests(home = homedir()) {
+    try {
+        const dir = join(home, ...LEGACY_HARNESS_DIR);
+        return readdirSync(dir).filter((name) => name.endsWith('.json')).sort().map((name) => join(dir, name));
+    }
+    catch {
+        return [];
+    }
+}
+/** Reads this process's own identity. No file, no shared state, no machine-wide pin. */
+export function loadSessionIdentity(env = process.env) {
+    // Trim before validating: secret injection (a sourced .env file, a CI secret,
+    // a Kubernetes secret mount) commonly appends a trailing newline. This runs
+    // BEFORE main()'s agent-API-key check, so an untrimmed value failed the
+    // agentId regex here and killed the process with a raw schema error — agent
+    // API key mode could never engage even though its own loader trims for
+    // exactly this reason (CORBOT-D8D35CF0).
+    const agentId = env['AIS_AGENT_ID']?.trim();
+    if (agentId === undefined || agentId === '')
+        return null;
+    return sessionIdentitySchema.parse({ version: 1, source: 'env', agentId });
+}
+/** The identity this session holds after a successful in-session agent_load switch. */
+export function switchedTo(previous, agentId) {
+    return sessionIdentitySchema.parse({ version: previous.version, source: 'agent_load', agentId });
+}
+export function assertPinnedAgent(pin, agentId) {
+    if (!pin)
+        return;
+    if (pin.agentId !== agentId) {
+        throw new Error(`Identity gate: expected ${pin.agentId}, received ${agentId}. Writes stopped. ${IDENTITY_REPAIR}`);
+    }
+}
+/** Verify the same whoami response exposed by the selected auth adapter, before every mutation. */
+export async function verifyPinnedIdentity(pin, agentId, whoami) {
+    if (!pin)
+        return;
+    assertPinnedAgent(pin, agentId);
+    let result;
+    try {
+        result = await whoami();
+    }
+    catch {
+        throw new Error(`Identity gate: whoami unavailable for ${agentId}. Writes stopped. ${IDENTITY_REPAIR}`);
+    }
+    const parsed = z.object({ success: z.literal(true), data: z.object({
+            id: z.string().optional(), agentId: z.string().optional(),
+        }) }).safeParse(result);
+    if (!parsed.success || (parsed.data.data.id ?? parsed.data.data.agentId) !== agentId) {
+        throw new Error(`Identity gate: whoami did not confirm ${agentId}. Writes stopped. ${IDENTITY_REPAIR}`);
+    }
+}
+export function requiresIdentityGate(name, args) {
+    return ['remember', 'handoff', 'dream', 'inbox_send'].includes(name) ||
+        (name === 'inbox_read' && args['ack'] === true);
+}
+//# sourceMappingURL=session-identity.js.map

package/dist/session-identity.js.map

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

package/dist/telemetry.d.ts

@@ -1,4 +1,4 @@
-export type TelemetryEventName = 'auth.device_flow.start' | 'auth.key.success' | 'auth.key.fallback' | 'auth.key.autoenroll' | 'auth.renew.success' | 'auth.renew.retry' | 'auth.renew.hard_expiry' | 'tool.call' | 'ais.http.failure';
+export type TelemetryEventName = 'auth.device_flow.start' | 'auth.key.success' | 'auth.key.fallback' | 'auth.key.autoenroll' | 'auth.renew.success' | 'auth.renew.retry' | 'auth.renew.hard_expiry' | 'tool.call' | 'ais.http.failure' | 'ais.http.retry';
 export interface TelemetryEvent {
     event: TelemetryEventName;
     ts: string;

package/dist/telemetry.js.map

@@ -1 +1 @@
-{"version":3,"file":"telemetry.js","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AA2BzC,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;AAEnD,gEAAgE;AAChE,MAAM,UAAU,kBAAkB;IAChC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACrE,OAAO,GAAG,KAAK,SAAS,IAAI,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAC9C,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,WAAW,CAAC,OAAe;IACzC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AACzE,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,aAAa,CAAC,KAAmD;IAC/E,IAAI,CAAC,kBAAkB,EAAE;QAAE,OAAO;IAClC,MAAM,OAAO,GAAmB;QAC9B,GAAG,KAAK;QACR,EAAE,EAAE,KAAK,CAAC,EAAE,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACzC,CAAC;IACF,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,yBAAyB,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;AAC7E,CAAC"}
+{"version":3,"file":"telemetry.js","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AA4BzC,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;AAEnD,gEAAgE;AAChE,MAAM,UAAU,kBAAkB;IAChC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACrE,OAAO,GAAG,KAAK,SAAS,IAAI,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAC9C,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,WAAW,CAAC,OAAe;IACzC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AACzE,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,aAAa,CAAC,KAAmD;IAC/E,IAAI,CAAC,kBAAkB,EAAE;QAAE,OAAO;IAClC,MAAM,OAAO,GAAmB;QAC9B,GAAG,KAAK;QACR,EAAE,EAAE,KAAK,CAAC,EAAE,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACzC,CAAC;IACF,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,yBAAyB,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;AAC7E,CAAC"}

package/dist/tool-args.d.ts

@@ -18,6 +18,7 @@ export declare const rememberArgsSchema: z.ZodObject<{
         task: "task";
     }>>>;
     importance: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
 export declare const recallArgsSchema: z.ZodObject<{
     principalAgentId: z.ZodOptional<z.ZodString>;
@@ -31,10 +32,13 @@ export declare const recallArgsSchema: z.ZodObject<{
         goal: "goal";
         task: "task";
     }>>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
 export declare const handoffArgsSchema: z.ZodObject<{
     summary: z.ZodOptional<z.ZodString>;
     keyLearnings: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    docPath: z.ZodOptional<z.ZodString>;
+    docPrUrl: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const agentLoadArgsSchema: z.ZodObject<{
     query: z.ZodString;

package/dist/tool-args.js

@@ -8,6 +8,13 @@ export const MAX_MEMORY_CONTENT_LENGTH = 256 * 1024;
 /** Max recall limit (matches AIS memory-handlers). */
 export const MAX_QUERY_LIMIT = 100;
 const memoryTypeSchema = z.enum(['fact', 'event', 'lesson', 'context', 'goal', 'task']);
+/**
+ * Memory tags (Jaire C5). The service trims, lower-cases, de-duplicates and
+ * validates them (1-64 chars of a-z 0-9 . _ : -, at most 20); this only
+ * checks the shape.
+ */
+const tagsArgSchema = z.array(z.string({ message: 'tags must be strings' }), { message: 'tags must be an array of strings' })
+    .max(20, 'a memory can carry at most 20 tags');
 export const rememberArgsSchema = z.object({
     content: z
         .string({ message: 'content is required and must be a string' })
@@ -15,6 +22,7 @@ export const rememberArgsSchema = z.object({
         .max(MAX_MEMORY_CONTENT_LENGTH, `content exceeds maximum length of ${MAX_MEMORY_CONTENT_LENGTH} bytes`),
     type: memoryTypeSchema.optional().default('context'),
     importance: z.number().min(0).max(1).optional().default(0.5),
+    tags: tagsArgSchema.optional(),
 });
 /**
  * Optional delegated-read principal (CORBOT-3785D10D).
@@ -34,6 +42,8 @@ export const recallArgsSchema = z.object({
         .max(MAX_MEMORY_CONTENT_LENGTH, `query exceeds maximum length of ${MAX_MEMORY_CONTENT_LENGTH} bytes`),
     limit: z.number().int().min(1).max(MAX_QUERY_LIMIT).optional(),
     type: memoryTypeSchema.optional(),
+    /** Only memories carrying every one of these tags. */
+    tags: tagsArgSchema.optional(),
 });
 export const handoffArgsSchema = z.object({
     summary: z
@@ -46,6 +56,12 @@ export const handoffArgsSchema = z.object({
         .max(MAX_MEMORY_CONTENT_LENGTH, `keyLearnings item exceeds maximum length of ${MAX_MEMORY_CONTENT_LENGTH} bytes`))
         .max(100, 'keyLearnings exceeds maximum of 100 items')
         .optional(),
+    // CORBOT-E3541A7F: the route accepts these two and persists them in the
+    // doc_path / doc_pr_url columns. Same shape the route validates — a string
+    // it ignores when blank — so nothing is added here beyond letting the
+    // caller's value survive the parse instead of being stripped.
+    docPath: z.string().optional(),
+    docPrUrl: z.string().optional(),
 });
 export const agentLoadArgsSchema = z.object({
     query: z