aismemory 0.8.3 → 0.8.4

package/dist/device-poll.d.ts

@@ -20,6 +20,7 @@ export declare class DeviceFlowRestartedError extends Error {
 }
 export interface PollTokenResponse {
     access_token?: string;
+    refresh_token?: string;
     expires_in?: number;
     error?: string;
     pending_reason?: string;

package/dist/device-poll.js.map

@@ -1 +1 @@
-{"version":3,"file":"device-poll.js","sourceRoot":"","sources":["../src/device-poll.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,gFAAgF;AAChF,MAAM,CAAC,MAAM,qBAAqB,GAAG,MAAM,CAAC;AAE5C,+EAA+E;AAC/E,MAAM,OAAO,wBAAyB,SAAQ,KAAK;IAG/B;IACA;IAHT,qBAAqB,GAAG,IAAI,CAAC;IACtC,YACkB,kBAA0B,EAC1B,WAAmB;QAEnC,KAAK,CACH,oDAAoD;YAClD,UAAU,kBAAkB,IAAI;YAChC,SAAS,WAAW,EAAE,CACzB,CAAC;QAPc,uBAAkB,GAAlB,kBAAkB,CAAQ;QAC1B,gBAAW,GAAX,WAAW,CAAQ;QAOnC,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;IACzC,CAAC;CACF;AA4BD;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,MAAwB,EACxB,IAAkB;IAElB,MAAM,EACJ,QAAQ,EACR,YAAY,EACZ,UAAU,EACV,KAAK,GAAG,GAAW,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,EAChC,cAAc,GAAG,KAAK,GACvB,GAAG,IAAI,CAAC;IAET,MAAM,QAAQ,GAAG,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,SAAS;IACpD,IAAI,eAAe,GAAG,CAAC,CAAC;IACxB,MAAM,WAAW,GAAG,MAAM,CAAC,WAAW,CAAC;IAEvC,OAAO,KAAK,EAAE,GAAG,QAAQ,EAAE,CAAC;QAC1B,MAAM,IAAI,OAAO,CAAO,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC;QAE9D,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,WAAW,CAAC,CAAC;QAEzC,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YACtB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,IAAI,IAAI,CAAC,KAAK,KAAK,uBAAuB,EAAE,CAAC;YAC3C,sBAAsB;YACtB,MAAM,GAAG,GAAG,KAAK,EAAE,CAAC;YACpB,IAAI,GAAG,GAAG,eAAe,IAAI,qBAAqB,EAAE,CAAC;gBACnD,eAAe,GAAG,GAAG,CAAC;gBACtB,IAAI,IAAI,CAAC,cAAc,KAAK,WAAW,EAAE,CAAC;oBACxC,UAAU,CAAC,kDAAkD,CAAC,CAAC;gBACjE,CAAC;qBAAM,CAAC;oBACN,UAAU,CAAC,yBAAyB,CAAC,CAAC;gBACxC,CAAC;YACH,CAAC;YACD,SAAS;QACX,CAAC;QAED,IAAI,IAAI,CAAC,KAAK,KAAK,WAAW,EAAE,CAAC;YAC/B,MAAM,IAAI,OAAO,CAAO,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC;YAC9D,SAAS;QACX,CAAC;QAED,IAAI,IAAI,CAAC,KAAK,KAAK,eAAe,EAAE,CAAC;YACnC,mEAAmE;YACnE,MAAM,OAAO,GAAG,MAAM,YAAY,EAAE,CAAC;YACrC,MAAM,IAAI,wBAAwB,CAChC,OAAO,CAAC,yBAAyB,EACjC,OAAO,CAAC,SAAS,CAClB,CAAC;QACJ,CAAC;QAED,IAAI,IAAI,CAAC,KAAK,KAAK,eAAe,EAAE,CAAC;YACnC,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;QAClD,CAAC;QAED,sCAAsC;QACtC,MAAM,IAAI,KAAK,CAAC,6BAA6B,IAAI,CAAC,KAAK,IAAI,kBAAkB,EAAE,CAAC,CAAC;IACnF,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAC;AAC9C,CAAC"}
+{"version":3,"file":"device-poll.js","sourceRoot":"","sources":["../src/device-poll.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,gFAAgF;AAChF,MAAM,CAAC,MAAM,qBAAqB,GAAG,MAAM,CAAC;AAE5C,+EAA+E;AAC/E,MAAM,OAAO,wBAAyB,SAAQ,KAAK;IAG/B;IACA;IAHT,qBAAqB,GAAG,IAAI,CAAC;IACtC,YACkB,kBAA0B,EAC1B,WAAmB;QAEnC,KAAK,CACH,oDAAoD;YAClD,UAAU,kBAAkB,IAAI;YAChC,SAAS,WAAW,EAAE,CACzB,CAAC;QAPc,uBAAkB,GAAlB,kBAAkB,CAAQ;QAC1B,gBAAW,GAAX,WAAW,CAAQ;QAOnC,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;IACzC,CAAC;CACF;AA6BD;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,MAAwB,EACxB,IAAkB;IAElB,MAAM,EACJ,QAAQ,EACR,YAAY,EACZ,UAAU,EACV,KAAK,GAAG,GAAW,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,EAChC,cAAc,GAAG,KAAK,GACvB,GAAG,IAAI,CAAC;IAET,MAAM,QAAQ,GAAG,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,SAAS;IACpD,IAAI,eAAe,GAAG,CAAC,CAAC;IACxB,MAAM,WAAW,GAAG,MAAM,CAAC,WAAW,CAAC;IAEvC,OAAO,KAAK,EAAE,GAAG,QAAQ,EAAE,CAAC;QAC1B,MAAM,IAAI,OAAO,CAAO,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC;QAE9D,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,WAAW,CAAC,CAAC;QAEzC,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YACtB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,IAAI,IAAI,CAAC,KAAK,KAAK,uBAAuB,EAAE,CAAC;YAC3C,sBAAsB;YACtB,MAAM,GAAG,GAAG,KAAK,EAAE,CAAC;YACpB,IAAI,GAAG,GAAG,eAAe,IAAI,qBAAqB,EAAE,CAAC;gBACnD,eAAe,GAAG,GAAG,CAAC;gBACtB,IAAI,IAAI,CAAC,cAAc,KAAK,WAAW,EAAE,CAAC;oBACxC,UAAU,CAAC,kDAAkD,CAAC,CAAC;gBACjE,CAAC;qBAAM,CAAC;oBACN,UAAU,CAAC,yBAAyB,CAAC,CAAC;gBACxC,CAAC;YACH,CAAC;YACD,SAAS;QACX,CAAC;QAED,IAAI,IAAI,CAAC,KAAK,KAAK,WAAW,EAAE,CAAC;YAC/B,MAAM,IAAI,OAAO,CAAO,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC;YAC9D,SAAS;QACX,CAAC;QAED,IAAI,IAAI,CAAC,KAAK,KAAK,eAAe,EAAE,CAAC;YACnC,mEAAmE;YACnE,MAAM,OAAO,GAAG,MAAM,YAAY,EAAE,CAAC;YACrC,MAAM,IAAI,wBAAwB,CAChC,OAAO,CAAC,yBAAyB,EACjC,OAAO,CAAC,SAAS,CAClB,CAAC;QACJ,CAAC;QAED,IAAI,IAAI,CAAC,KAAK,KAAK,eAAe,EAAE,CAAC;YACnC,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;QAClD,CAAC;QAED,sCAAsC;QACtC,MAAM,IAAI,KAAK,CAAC,6BAA6B,IAAI,CAAC,KAAK,IAAI,kBAAkB,EAAE,CAAC,CAAC;IACnF,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAC;AAC9C,CAAC"}

package/dist/dream-poll.d.ts

@@ -0,0 +1,19 @@
+export declare const DEFAULT_DREAM_POLL_MS = 120000;
+export declare const DEFAULT_DREAM_POLL_INTERVAL_MS = 2000;
+export declare function getDreamPollMs(env?: Record<string, string | undefined>): number;
+export declare function getDreamPollIntervalMs(env?: Record<string, string | undefined>): number;
+export interface DreamPollOptions {
+    /** GET /v1/agents/:agentId/dream/:runId through the caller's own auth mode. */
+    getStatus: (runId: string) => Promise<unknown>;
+    deadlineMs?: number;
+    intervalMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+}
+/**
+ * Resolve a dream POST response. A finished (old synchronous) response is
+ * returned untouched. A 202 is polled to completion: completed/partial return
+ * {success:true, data:<run>}, failed throws with the server's error text, and
+ * a spent deadline returns a non-error "still running" result.
+ */
+export declare function resolveDreamResponse(response: unknown, opts: DreamPollOptions): Promise<unknown>;

package/dist/dream-poll.js

@@ -0,0 +1,93 @@
+/**
+ * Async dream handling (CORBOT-F88FD791). A dream cycle can outlast the 20 s
+ * per-request cap, so the server answers POST /dream either with the finished
+ * run (200, the original shape) or, when the run is still going, 202 with
+ * {runId, status:'running', pollUrl}. This module turns the 202 back into the
+ * synchronous result by polling GET /dream/:runId, so callers see one shape.
+ *
+ * The overall wait is AIS_DREAM_POLL_MS (default 120000) and is separate from
+ * AIS_MCP_REQUEST_TIMEOUT_MS: every poll GET still carries the per-request cap.
+ */
+import { isAisRequestTimeout, AisRequestTimeoutError } from './request-timeout.js';
+export const DEFAULT_DREAM_POLL_MS = 120_000;
+export const DEFAULT_DREAM_POLL_INTERVAL_MS = 2_000;
+function positiveEnvMs(raw, fallback) {
+    const parsed = Number(raw?.trim());
+    return raw !== undefined && raw.trim() !== '' && Number.isFinite(parsed) && parsed > 0
+        ? parsed
+        : fallback;
+}
+export function getDreamPollMs(env = process.env) {
+    return positiveEnvMs(env['AIS_DREAM_POLL_MS'], DEFAULT_DREAM_POLL_MS);
+}
+export function getDreamPollIntervalMs(env = process.env) {
+    return positiveEnvMs(env['AIS_DREAM_POLL_INTERVAL_MS'], DEFAULT_DREAM_POLL_INTERVAL_MS);
+}
+function asRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+/** The accepted-but-unfinished body of a 202, or null for a finished (200) result. */
+function acceptedRun(response) {
+    const data = asRecord(asRecord(response)?.['data']);
+    if (data === null)
+        return null;
+    const runId = data['runId'];
+    if (data['status'] === 'running' && typeof runId === 'string' && runId !== '') {
+        return { runId };
+    }
+    return null;
+}
+function stillRunning(runId) {
+    return {
+        success: true,
+        data: {
+            runId,
+            status: 'running',
+            message: `Dream run ${runId} is still running on the server; it will finish on its own. ` +
+                'Calling dream again while it is active returns this same run; once it has finished, a new call starts a fresh cycle.',
+        },
+    };
+}
+/**
+ * Resolve a dream POST response. A finished (old synchronous) response is
+ * returned untouched. A 202 is polled to completion: completed/partial return
+ * {success:true, data:<run>}, failed throws with the server's error text, and
+ * a spent deadline returns a non-error "still running" result.
+ */
+export async function resolveDreamResponse(response, opts) {
+    const accepted = acceptedRun(response);
+    if (accepted === null)
+        return response;
+    const { runId } = accepted;
+    const now = opts.now ?? Date.now;
+    const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const intervalMs = opts.intervalMs ?? getDreamPollIntervalMs();
+    const deadline = now() + (opts.deadlineMs ?? getDreamPollMs());
+    while (now() < deadline) {
+        await sleep(Math.min(intervalMs, Math.max(0, deadline - now())));
+        let status;
+        try {
+            status = await opts.getStatus(runId);
+        }
+        catch (err) {
+            // A single slow poll is not a failed run; keep waiting until the deadline.
+            if (isAisRequestTimeout(err) || err instanceof AisRequestTimeoutError)
+                continue;
+            throw err;
+        }
+        const run = asRecord(asRecord(status)?.['data']);
+        const state = run?.['status'];
+        if (run === null)
+            continue;
+        if (state === 'completed' || state === 'partial')
+            return { success: true, data: run };
+        if (state === 'failed') {
+            const detail = typeof run['error'] === 'string' && run['error'] !== '' ? run['error'] : 'no error text';
+            throw new Error(`Dream run ${runId} failed: ${detail}`);
+        }
+    }
+    return stillRunning(runId);
+}
+//# sourceMappingURL=dream-poll.js.map

package/dist/dream-poll.js.map

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

package/dist/env-agent.d.ts

@@ -8,6 +8,10 @@ export interface TenantAgentSummary {
  * Throws with a message suitable for stderr when the id is missing or unknown.
  */
 export declare function assertEnvAgentInTenant(envAgentId: string, agents: TenantAgentSummary[]): TenantAgentSummary;
+/** AIS_AGENT_NAME names no agent, or more than one, in the tenant (CORBOT-C1A01EB3). */
+export declare class EnvAgentNameError extends Error {
+    constructor(message: string);
+}
 export interface AgentSelection {
     agentId: string;
     reason: 'env-name' | 'preferred' | 'first-active' | 'fallback';
@@ -17,7 +21,8 @@ export interface AgentSelection {
 /**
  * Pick which agent this session connects to (CORBOT-B0FA4A79).
  *
- * Priority: AIS_AGENT_NAME match > previously bonded agent > first active >
+ * Priority: AIS_AGENT_NAME match (throws EnvAgentNameError on no match or
+ * several) > previously bonded agent > first active >
  * fallback (fresh provisional agent when the tenant has none). The bonded
  * preference is the load-bearing part: without it, a re-auth reconnected a
  * multi-agent user to whichever agent the server listed first — a different

package/dist/env-agent.js

@@ -11,10 +11,18 @@ export function assertEnvAgentInTenant(envAgentId, agents) {
     throw new Error(`AIS_AGENT_ID="${envAgentId}" is not a valid agent in this tenant. ` +
         `Available: ${available || '(none)'}`);
 }
+/** AIS_AGENT_NAME names no agent, or more than one, in the tenant (CORBOT-C1A01EB3). */
+export class EnvAgentNameError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'EnvAgentNameError';
+    }
+}
 /**
  * Pick which agent this session connects to (CORBOT-B0FA4A79).
  *
- * Priority: AIS_AGENT_NAME match > previously bonded agent > first active >
+ * Priority: AIS_AGENT_NAME match (throws EnvAgentNameError on no match or
+ * several) > previously bonded agent > first active >
  * fallback (fresh provisional agent when the tenant has none). The bonded
  * preference is the load-bearing part: without it, a re-auth reconnected a
  * multi-agent user to whichever agent the server listed first — a different
@@ -29,11 +37,16 @@ export function selectAgentForSession(opts) {
         return { agentId: opts.fallbackAgentId, reason: 'fallback', notes };
     }
     if (opts.envAgentName) {
-        const match = opts.agents.find((a) => a.name.toLowerCase() === opts.envAgentName.toLowerCase());
-        if (match) {
-            return { agentId: match.id, reason: 'env-name', notes };
+        const wanted = opts.envAgentName.toLowerCase();
+        const matches = opts.agents.filter((a) => a.name.toLowerCase() === wanted);
+        if (matches.length === 1) {
+            return { agentId: matches[0].id, reason: 'env-name', notes };
+        }
+        // An explicit name asks for one identity: never connect as a different agent.
+        if (matches.length === 0) {
+            throw new EnvAgentNameError(`AIS_AGENT_NAME="${opts.envAgentName}" matches no agent. Available: ${opts.agents.map((a) => a.name).join(', ')}`);
         }
-        notes.push(`AIS_AGENT_NAME="${opts.envAgentName}" not found. Available: ${opts.agents.map((a) => a.name).join(', ')}`);
+        throw new EnvAgentNameError(`AIS_AGENT_NAME="${opts.envAgentName}" matches ${matches.length} agents (${matches.map((a) => a.id).join(', ')}). Set AIS_AGENT_ID to the one this session should use.`);
     }
     if (opts.preferredAgentId) {
         const match = opts.agents.find((a) => a.id === opts.preferredAgentId);

package/dist/env-agent.js.map

@@ -1 +1 @@
-{"version":3,"file":"env-agent.js","sourceRoot":"","sources":["../src/env-agent.ts"],"names":[],"mappings":"AAMA;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CACpC,UAAkB,EAClB,MAA4B;IAE5B,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,UAAU,CAAC,CAAC;IAC9D,IAAI,KAAK,EAAE,CAAC;QACV,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAClF,MAAM,IAAI,KAAK,CACb,iBAAiB,UAAU,yCAAyC;QAClE,cAAc,SAAS,IAAI,QAAQ,EAAE,CACxC,CAAC;AACJ,CAAC;AASD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAQrC;IACC,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,eAAe,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;IACtE,CAAC;IAED,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;QACtB,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,IAAI,CAAC,YAAa,CAAC,WAAW,EAAE,CAAC,CAAC;QACjG,IAAI,KAAK,EAAE,CAAC;YACV,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;QAC1D,CAAC;QACD,KAAK,CAAC,IAAI,CACR,mBAAmB,IAAI,CAAC,YAAY,2BAA2B,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC3G,CAAC;IACJ,CAAC;IAED,IAAI,IAAI,CAAC,gBAAgB,EAAE,CAAC;QAC1B,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,IAAI,CAAC,gBAAgB,CAAC,CAAC;QACtE,IAAI,KAAK,EAAE,CAAC;YACV,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC;QAC3D,CAAC;QACD,KAAK,CAAC,IAAI,CACR,2BAA2B,IAAI,CAAC,gBAAgB,wCAAwC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAE,CAAC,IAAI,MAAM,IAAI,CAAC,MAAM,CAAC,CAAC,CAAE,CAAC,EAAE,IAAI,CACzI,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAE,CAAC,EAAE,EAAE,MAAM,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC;AACxE,CAAC"}
+{"version":3,"file":"env-agent.js","sourceRoot":"","sources":["../src/env-agent.ts"],"names":[],"mappings":"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"}

package/dist/hydration.js

@@ -1,4 +1,5 @@
 import { getAisRequestTimeoutMs } from './request-timeout.js';
+import { withDeclaredAgent } from './declared-agent.js';
 const LOG_PREFIX = '[aismemory]';
 function redactHydrationMessage(message) {
     return message
@@ -29,7 +30,7 @@ export async function hydrateIdentity(aisUrl, agentId, token, memoriesLimit) {
     try {
         const query = memoriesLimit === undefined ? '' : `?memoriesLimit=${memoriesLimit}`;
         const res = await fetch(`${aisUrl}/v1/agents/${agentId}/full-context${query}`, {
-            headers: { Authorization: `Bearer ${token}` },
+            headers: withDeclaredAgent({ Authorization: `Bearer ${token}` }),
             signal: AbortSignal.timeout(getAisRequestTimeoutMs()),
         });
         if (!res.ok) {

package/dist/hydration.js.map

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

package/dist/index.js

@@ -11,23 +11,25 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { tryKeyAuth, enrollKeyIfNeeded, hasEnrolledKey } from './key-auth.js';
+import { tryKeyAuth, enrollKeyIfNeeded, formatAutoEnrollFailureStderr, hasEnrolledKey } from './key-auth.js';
 import { isCredsStale, isNoRegisteredKeysAuthError } from './auth-staleness.js';
 import { AisHttpError } from './ais-http-error.js';
 import { aisGet, aisPost, DEFAULT_AIS_URL } from './ais-http.js';
 import { CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { homedir } from 'node:os';
-import { loadOAuthCredentials, loadNonStaleDiskBearer, saveOAuthCredentials, } from './oauth-credentials.js';
+import { credentialsFilePath, loadOAuthCredentials, loadNonStaleDiskBearer, saveOAuthCredentials, } from './oauth-credentials.js';
 import { clearPendingDeviceFlow, isResumableDeviceFlow, loadPendingDeviceFlow, savePendingDeviceFlow, } from './pending-device-flow.js';
 import { saveAgentPreference, loadAgentPreference, migrateCredentialsFileIfNeeded } from './agent-preference.js';
+import { credentialsFromOwnerKeychain, isSigninKeychainAvailable, ownerUserIdFromAccessToken, requireOwnerKeychainCredentials, saveOwnerSignInToKeychain, } from './signin-keychain.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 { assertEnvAgentInTenant, EnvAgentNameError, selectAgentForSession } from './env-agent.js';
 import { emitTelemetry, hashAgentId } from './telemetry.js';
 import { 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 { setDeclaredAgentSource } from './declared-agent.js';
 import { identityCredentialFingerprint, loadSessionIdentity, verifyPinnedIdentity } from './session-identity.js';
 import { runPollLoop, DeviceFlowRestartedError } from './device-poll.js';
 import { loadAgentApiKeyConfig, AgentApiKeyConfigError, } from './agent-key-mode.js';
@@ -35,7 +37,9 @@ import { loadWorkspaceKeyConfig, WorkspaceKeyConfigError, } from './workspace-ke
 import { loadRunPassConfig, RunPassConfigError, } from './run-pass-mode.js';
 import { createAgentKeyCallToolHandler, createOAuthCallToolHandler, createRunPassCallToolHandler, createWorkspaceKeyCallToolHandler, } from './mcp/tools.js';
 import { readPackageVersion, startVersionCheck } from './version-check.js';
+import { AIS_MCP_INSTRUCTIONS } from './mcp-instructions.js';
 import { HUMAN_HOWTO_TEXT, resolveInfoRequest } from './cli-info.js';
+import { describeStartupIdentity, findDuplicateServerNames, formatDuplicateServerWarning, formatStartupIdentityLine, setServerNameConflicts, setStartupIdentity, } from './startup-identity.js';
 import { AGENT_ARCHIVE_DESCRIPTION, AGENT_ARCHIVE_INPUT_SCHEMA, AGENT_DELETE_ALIAS_DESCRIPTION } from './agent-archive.js';
 // ── Config ──────────────────────────────────────────────
 const AIS_URL = process.env['AIS_URL']?.trim() || DEFAULT_AIS_URL;
@@ -52,8 +56,12 @@ function loadCredentials() {
     // owns the live session and this v1 disk bearer must never be treated
     // as it (F4) — see the hasEnrolledKey() guard at the bottom of main().
     migrateCredentialsFileIfNeeded();
+    const pref = loadAgentPreference();
+    const fromKeychain = pref ? credentialsFromOwnerKeychain(AIS_URL, pref) : null;
+    if (fromKeychain)
+        return fromKeychain;
     const data = loadOAuthCredentials();
-    if (!data)
+    if (!data?.token)
         return null;
     if (isCredsStale(data.expiresAt, Date.now())) {
         stderr('Saved credentials expired or expiring soon. Re-authenticating...');
@@ -65,6 +73,23 @@ function loadCredentials() {
 function stderr(msg) {
     process.stderr.write(`[aismemory] ${msg}\n`);
 }
+/**
+ * CORBOT-5D16CF2A: one stderr line naming the client version, the agent and
+ * where its credential comes from, so version drift and a shadowed config
+ * entry are visible at startup. Also kept for whoami. Never prints a value.
+ */
+function reportStartupIdentity(input) {
+    const identity = describeStartupIdentity(PACKAGE_VERSION, input);
+    setStartupIdentity(identity);
+    stderr(formatStartupIdentityLine(identity));
+}
+/** CORBOT-5D16CF2A: warn when the launching config defines this server name in several scopes. */
+function reportDuplicateServerNames() {
+    const conflicts = findDuplicateServerNames({ home: homedir(), cwd: process.cwd() });
+    setServerNameConflicts(conflicts);
+    for (const conflict of conflicts)
+        stderr(`Warning: ${formatDuplicateServerWarning(conflict)}`);
+}
 function rejectRunPassWithKeyEnv(env) {
     if (env['AIS_RUN_PASS_FILE'] === undefined)
         return;
@@ -195,7 +220,11 @@ async function resolveAgent(token, fallbackAgentId, fallbackTenantId, preferredA
         }
         return { agentId: selection.agentId, tenantId: fallbackTenantId };
     }
-    catch {
+    catch (error) {
+        if (error instanceof EnvAgentNameError) {
+            stderr(error.message);
+            throw error;
+        }
         stderr(`Could not list agents. Using new agent: ${fallbackAgentId}`);
         return { agentId: fallbackAgentId, tenantId: fallbackTenantId };
     }
@@ -454,7 +483,35 @@ flowRef) {
     // a regression versus 0.6.2, which always persisted the token and
     // reconnected silently. migrateCredentialsFileIfNeeded() (agent-preference.ts)
     // is what later removes this token from disk, once a key gets enrolled.
-    if (hasEnrolledKey()) {
+    const refreshToken = pollResp.refresh_token;
+    const ownerUserId = ownerUserIdFromAccessToken(creds.token);
+    const keychainPersisted = !sessionIdentity &&
+        typeof refreshToken === 'string' &&
+        refreshToken.length > 0 &&
+        ownerUserId !== null &&
+        isSigninKeychainAvailable();
+    if (keychainPersisted) {
+        try {
+            saveOwnerSignInToKeychain({
+                aisUrl: AIS_URL,
+                accessToken: creds.token,
+                refreshToken,
+                expiresAt: creds.expiresAt,
+            });
+            saveAgentPreference({ agentId: creds.agentId, tenantId: creds.tenantId, ownerUserId });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            stderr(`Could not store owner sign-in in the OS keychain (${message}); saving to disk instead.`);
+            if (hasEnrolledKey()) {
+                saveAgentPreference({ agentId: creds.agentId, tenantId: creds.tenantId, ownerUserId });
+            }
+            else {
+                saveOAuthCredentials(creds);
+            }
+        }
+    }
+    else if (hasEnrolledKey()) {
         if (!sessionIdentity)
             saveAgentPreference({ agentId: creds.agentId, tenantId: creds.tenantId });
     }
@@ -486,6 +543,7 @@ const tools = [
                 type: { type: 'string', enum: ['fact', 'event', 'lesson', 'context', 'goal', 'task'], description: 'Memory type' },
                 importance: { type: 'number', minimum: 0, maximum: 1, description: 'Importance (0-1, default 0.5)' },
                 tags: { type: 'array', items: { type: 'string' }, description: 'Optional tags to filter on later, e.g. ["work", "acme"]. At most 20; each 1-64 characters of a-z 0-9 . _ : - (stored lower-case). Tags are a filter, not a permission — use separate agents to wall off e.g. work from personal.' },
+                supersedes: { type: 'string', description: 'Optional: the id of an older memory of yours that this one replaces (e.g. a lesson that turned out wrong). The old memory is kept but no longer returned by recall. Refused if that id is not one of your memories or is already superseded.' },
             },
             required: ['content'],
         },
@@ -495,6 +553,7 @@ const tools = [
         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. " +
             "Each memory carries createdAt, updatedAt (its last edit), and tags. " +
+            "Pass orderBy='newest' with type or tags to get the newest matching memories first. " +
             "Memories superseded by a newer one are left out; to list or page through every memory, " +
             "use the REST list route described in the aismemory README (cursor paging, sortBy=updatedAt, includeSuperseded=true)." + BOND_LINK_NOTE,
         inputSchema: {
@@ -504,6 +563,7 @@ const tools = [
                 limit: { type: 'number', description: 'Max results (default 10)' },
                 type: { type: 'string', enum: ['fact', 'event', 'lesson', 'context', 'goal', 'task'], description: 'Filter by type' },
                 tags: { type: 'array', items: { type: 'string' }, description: 'Only memories carrying ALL of these tags. A hard filter: results are never widened past it.' },
+                orderBy: { type: 'string', enum: ['newest'], description: "Set 'newest' to list matching memories newest-first (createdAt descending) instead of ranking by meaning. Use it when you store near-duplicate memories, such as repeated task memories that differ by a counter, and need the latest one first. The query text is not used for ranking, and 'newest' needs type or tags. Default (omitted): ranked search, unchanged." },
                 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'],
@@ -554,12 +614,13 @@ const tools = [
                 memoriesLimit: { type: 'number', description: 'Number of memories to load (1-50, default 5). Lower values reduce context size. Governs recent memories only — on the full view that is a small share of the payload, so prefer view to bound the whole response.' },
                 view: { type: 'string', enum: ['full', 'lean', 'bootstrap'], description: "Which projection to load. 'full' (default) is everything the stores hold, bounded to 6000 tokens. 'lean' is continuity only — last handoff first, then recent memories. 'bootstrap' is lean plus goals and inbox, for starting a session in another harness. All three honour maxTokens." },
                 maxTokens: { type: 'number', description: 'Token ceiling (500-20000; default 6000 for full, 2000 for lean, 3000 for bootstrap). Content is evicted from the tail until the payload fits — assembled context sections, then facts, then goals, then recent memories on the full view — and each eviction is named in receipt.omitted. Identity, the operating layer and the last handoff are never dropped.' },
+                contextWindowSize: { type: 'number', description: "Your model's context window in tokens (1000-10000000). The skills budget scales with it; omit for the server default." },
             },
         },
     },
     {
         name: 'dream',
-        description: 'Trigger a memory consolidation dream cycle — promotes important memories and archives old ones. Promotion only scans the session tier; active-tier memories move via context-clear or handoff, not dream.',
+        description: 'Trigger a memory consolidation dream cycle — promotes important memories and archives old ones. Promotion only scans the session tier; active-tier memories move via context-clear or handoff, not dream. A long cycle runs server-side; the call waits up to AIS_DREAM_POLL_MS (default 120 s) and, if still running, returns status "running" with the runId — the run keeps going on the server; calling dream again while it is active returns the same runId.',
         inputSchema: { type: 'object', properties: {} },
     },
     {
@@ -807,7 +868,7 @@ 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: {} } });
+    const server = new Server({ name: 'aismemory', version: PACKAGE_VERSION }, { capabilities: { tools: {}, prompts: {} }, instructions: AIS_MCP_INSTRUCTIONS });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
     server.setRequestHandler(ListPromptsRequestSchema, async () => ({ prompts: [] }));
     server.setRequestHandler(GetPromptRequestSchema, async (request) => {
@@ -834,7 +895,7 @@ async function runWorkspaceKeyModeServer(config) {
  */
 async function runPassModeServer(config) {
     stderr(`Run-pass auth mode — agent fixed to ${config.agentId}; pass file ${config.runPassFile}`);
-    const server = new Server({ name: 'aismemory', version: PACKAGE_VERSION }, { capabilities: { tools: {}, prompts: {} } });
+    const server = new Server({ name: 'aismemory', version: PACKAGE_VERSION }, { capabilities: { tools: {}, prompts: {} }, instructions: AIS_MCP_INSTRUCTIONS });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
     server.setRequestHandler(ListPromptsRequestSchema, async () => ({ prompts: [] }));
     server.setRequestHandler(GetPromptRequestSchema, async (request) => {
@@ -863,7 +924,7 @@ async function runPassModeServer(config) {
  */
 async function runAgentKeyModeServer(config) {
     stderr(`Agent API key auth mode — agent fixed to ${config.agentId} (no device flow, no DID key-auth).`);
-    const server = new Server({ name: 'aismemory', version: PACKAGE_VERSION }, { capabilities: { tools: {}, prompts: {} } });
+    const server = new Server({ name: 'aismemory', version: PACKAGE_VERSION }, { capabilities: { tools: {}, prompts: {} }, instructions: AIS_MCP_INSTRUCTIONS });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
     server.setRequestHandler(ListPromptsRequestSchema, async () => ({ prompts: [] }));
     server.setRequestHandler(GetPromptRequestSchema, async (request) => {
@@ -891,6 +952,10 @@ async function main() {
         (await import('./cli/install.js')).main(process.argv.slice(3));
         return;
     }
+    if (process.argv[2] === 'hooks') {
+        await (await import('./cli/hooks.js')).main(process.argv.slice(3));
+        return; // hook commands fail open and set process.exitCode themselves
+    }
     if (process.argv[2] === 'enable-key-auth') {
         await import('./cli/enable-key-auth.js');
         return; // CLI calls process.exit() itself
@@ -907,10 +972,19 @@ async function main() {
         await (await import('./cli/pull-memory.js')).main(process.argv.slice(3));
         return;
     }
+    if (process.argv[2] === 'export-harness') {
+        await (await import('./cli/export-harness.js')).main(process.argv.slice(3));
+        return;
+    }
     if (process.argv[2] === 'invite') {
         await (await import('./cli/invite-accept.js')).runFromCli(process.argv.slice(3));
         return;
     }
+    const ownerCommand = process.argv[2];
+    if (ownerCommand === 'rotate-token' || ownerCommand === 'api-keys' || ownerCommand === 'agents') {
+        await (await import('./cli/owner-credentials.js')).runFromCli(ownerCommand, process.argv.slice(3));
+        return;
+    }
     // CORBOT-73753A98: a person at a terminal gets a how-to; MCP clients pipe stdin and see nothing new.
     const humanAtTerminal = process.stdin.isTTY === true;
     if (humanAtTerminal) {
@@ -921,7 +995,9 @@ async function main() {
     // not wait on a third-party registry, and the answer is only needed later,
     // when whoami or full_context is called. Resolves to a skip when offline.
     void startVersionCheck({ currentVersion: PACKAGE_VERSION, onUpdateAvailable: stderr });
+    reportDuplicateServerNames();
     sessionIdentity = loadSessionIdentity();
+    setDeclaredAgentSource(() => sessionIdentity?.agentId);
     const adapterEnv = { ...process.env, AIS_AGENT_ID: sessionIdentity?.agentId };
     rejectRunPassWithKeyEnv(adapterEnv);
     // Explicit key auth modes keep their existing order when AIS_RUN_PASS_FILE is
@@ -939,6 +1015,7 @@ async function main() {
         throw err;
     }
     if (workspaceKeyConfig) {
+        reportStartupIdentity({ kind: 'workspace-key', env: adapterEnv, agentId: workspaceKeyConfig.agentId });
         await runWorkspaceKeyModeServer(workspaceKeyConfig);
         return;
     }
@@ -958,6 +1035,7 @@ async function main() {
         throw err;
     }
     if (agentKeyConfig) {
+        reportStartupIdentity({ kind: 'agent-api-key', env: adapterEnv, agentId: agentKeyConfig.agentId });
         await runAgentKeyModeServer(agentKeyConfig);
         return;
     }
@@ -975,6 +1053,7 @@ async function main() {
         throw err;
     }
     if (runPassConfig) {
+        reportStartupIdentity({ kind: 'run-pass', runPassFile: runPassConfig.runPassFile, agentId: runPassConfig.agentId });
         await runPassModeServer(runPassConfig);
         return;
     }
@@ -987,6 +1066,17 @@ async function main() {
     // 401s NO_REGISTERED_KEYS but this bearer still works for REST memory.
     const diskBearerFallback = loadNonStaleDiskBearer();
     let creds = loadCredentials();
+    const keyEnrolledAtStartup = hasEnrolledKey();
+    const startupPreference = loadAgentPreference();
+    reportStartupIdentity({
+        kind: 'oauth',
+        ...(sessionIdentity ? { sessionAgentId: sessionIdentity.agentId } : {}),
+        enrolledKeyDir: keyEnrolledAtStartup ? join(homedir(), '.aismemory', 'keys') : null,
+        diskAgentId: creds?.agentId ?? null,
+        credentialsFile: credentialsFilePath(),
+        ...(keyEnrolledAtStartup ? { preferredAgentId: startupPreference?.agentId } : {}),
+        ...(startupPreference?.ownerUserId ? { keychainOwnerSession: true } : {}),
+    });
     let activeFlow = null;
     let postAuthDone = false;
     // Fires the auth.key.success telemetry event + the one-line stderr
@@ -1032,9 +1122,15 @@ async function main() {
         resolveIdentity: async (token) => {
             const claims = decodeJwtClaims(token);
             const tenantId = claims.tenantId ?? '';
-            const resolved = await resolveAgent(token, '', tenantId, loadAgentPreference()?.agentId);
-            if (!sessionIdentity)
-                saveAgentPreference({ agentId: resolved.agentId, tenantId: resolved.tenantId || tenantId });
+            const pref = loadAgentPreference();
+            const resolved = await resolveAgent(token, '', tenantId, pref?.agentId);
+            if (!sessionIdentity) {
+                saveAgentPreference({
+                    agentId: resolved.agentId,
+                    tenantId: resolved.tenantId || tenantId,
+                    ...(pref?.ownerUserId ? { ownerUserId: pref.ownerUserId } : {}),
+                });
+            }
             return { agentId: resolved.agentId, tenantId: resolved.tenantId || tenantId };
         },
         onEvent: (event, detail) => {
@@ -1046,7 +1142,7 @@ async function main() {
         },
     });
     // Created here so `agent_load` and post-auth setup can reference it via closure.
-    const server = new Server({ name: 'aismemory', version: PACKAGE_VERSION }, { capabilities: { tools: {}, prompts: {} } });
+    const server = new Server({ name: 'aismemory', version: PACKAGE_VERSION }, { capabilities: { tools: {}, prompts: {} }, instructions: AIS_MCP_INSTRUCTIONS });
     /**
      * Wait briefly for the in-flight device-flow poll to complete. If the user
      * has already approved, this returns the fresh credentials. If not, throws
@@ -1058,6 +1154,18 @@ async function main() {
      * the next tool call without having to restart the MCP process.
      */
     async function ensureCredentials(softTimeoutMs = 7000) {
+        // CORBOT-EBCB2D2B: owner terminal sign-in uses the workspace credential
+        // in the OS keychain (not the DID key or a stale disk bearer) so
+        // agent_load can resolve agents by name via GET /v1/resolve.
+        const ownerPref = loadAgentPreference();
+        if (ownerPref?.ownerUserId) {
+            creds = requireOwnerKeychainCredentials(AIS_URL, ownerPref, sessionAgentOverride?.agentId);
+            if (!postAuthDone) {
+                postAuthDone = true;
+                void runPostAuth(creds);
+            }
+            return creds;
+        }
         // ── Key-enrolled path: all auth flows through the TokenManager ────────
         // The manager owns authenticate + background renewal + backoff; on a
         // sustained AIS outage it rejects with AisUnreachableError, which we let
@@ -1168,8 +1276,8 @@ async function main() {
             stderr('DID key enrolled — future sessions re-authenticate silently (no re-bond)');
             emitTelemetry({ event: 'auth.key.autoenroll', agentIdHash: hashAgentId(c.agentId), status: 'ok' });
         }
-        else if (enroll.reason.startsWith('register-failed')) {
-            stderr(`DID key auto-enroll failed (will retry next session): ${enroll.reason}`);
+        else if (enroll.reason.startsWith('register-failed') || enroll.reason.startsWith('register-refused')) {
+            stderr(formatAutoEnrollFailureStderr(enroll.reason));
             emitTelemetry({ event: 'auth.key.autoenroll', agentIdHash: hashAgentId(c.agentId), status: 'error', error: enroll.reason });
         }
         try {