aismemory 0.8.2 → 0.8.4

package/dist/signin-keychain.js

@@ -0,0 +1,200 @@
+/**
+ * Owner terminal sign-in credentials in the OS keychain (CORBOT-51CAC5E8).
+ *
+ * After device-flow approval, renewal + access tokens live only in the
+ * keychain — never as bearer secrets on disk under ~/.aismemory.
+ * Design: docs/superpowers/specs/2026-09-28-idprog-terminal-signin.md §4.2
+ */
+import { spawnSync } from 'node:child_process';
+import { isCredsStale } from './auth-staleness.js';
+export const SIGNIN_RENEWAL_SERVICE = 'ai.agentsandswarms.aismemory.signin';
+export const SIGNIN_ACCESS_SERVICE = 'ai.agentsandswarms.aismemory.access';
+let backendOverride = null;
+/** Test hook — production uses the platform backend. */
+export function setSigninKeychainBackendForTests(next) {
+    backendOverride = next;
+}
+function decodeJwtClaims(token) {
+    const parts = token.split('.');
+    if (parts.length !== 3)
+        throw new Error('Malformed JWT');
+    const json = Buffer.from(parts[1], 'base64url').toString('utf-8');
+    return JSON.parse(json);
+}
+export function signinKeychainAccount(aisUrl, tenantId, userId) {
+    const host = new URL(aisUrl).host;
+    return `${host}:${tenantId}:${userId}`;
+}
+function spawnSecurityInteractive(securityBin, scriptLine) {
+    const result = spawnSync(securityBin, ['-i'], {
+        input: `${scriptLine}\n`,
+        encoding: 'utf-8',
+    });
+    if (result.status !== 0) {
+        const detail = (result.stderr ?? result.stdout ?? '').trim().slice(0, 200);
+        throw new Error(`keychain write failed (${result.status ?? 'unknown'}): ${detail}`);
+    }
+}
+function linuxSecretToolAvailable() {
+    const lookup = spawnSync('which', ['secret-tool'], { encoding: 'utf-8' });
+    if (lookup.status !== 0)
+        return false;
+    const probe = spawnSync('secret-tool', ['lookup', '--help'], { encoding: 'utf-8' });
+    return probe.status === 0 || probe.status === 1;
+}
+function createPlatformBackend() {
+    if (process.platform === 'darwin') {
+        return {
+            isAvailable: () => {
+                const probe = spawnSync('security', ['help'], { encoding: 'utf-8' });
+                return probe.status === 0;
+            },
+            read: (service, account) => {
+                const result = spawnSync('security', ['find-generic-password', '-s', service, '-a', account, '-w'], { encoding: 'utf-8' });
+                if (result.status !== 0)
+                    return null;
+                const secret = result.stdout?.trim();
+                return secret ? secret : null;
+            },
+            write: (service, account, secret) => {
+                const escapedAccount = account.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+                const escapedService = service.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+                const escapedSecret = secret.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+                spawnSecurityInteractive('security', `add-generic-password -U -s "${escapedService}" -a "${escapedAccount}" -w "${escapedSecret}"`);
+            },
+        };
+    }
+    if (process.platform === 'linux' && linuxSecretToolAvailable()) {
+        return {
+            isAvailable: () => linuxSecretToolAvailable(),
+            read: (service, account) => {
+                const result = spawnSync('secret-tool', ['lookup', 'service', service, 'account', account], { encoding: 'utf-8' });
+                if (result.status !== 0)
+                    return null;
+                const secret = result.stdout?.trim();
+                return secret ? secret : null;
+            },
+            write: (service, account, secret) => {
+                const result = spawnSync('secret-tool', ['store', '--label', service, 'service', service, 'account', account], { input: secret, encoding: 'utf-8' });
+                if (result.status !== 0) {
+                    const detail = (result.stderr ?? result.stdout ?? '').trim().slice(0, 200);
+                    throw new Error(`secret-tool store failed (${result.status ?? 'unknown'}): ${detail}`);
+                }
+            },
+        };
+    }
+    return {
+        isAvailable: () => false,
+        read: () => null,
+        write: () => {
+            throw new Error('No OS keychain available on this platform');
+        },
+    };
+}
+function backend() {
+    return backendOverride ?? createPlatformBackend();
+}
+export function isSigninKeychainAvailable() {
+    return backend().isAvailable();
+}
+export function saveOwnerSignInToKeychain(input) {
+    const claims = decodeJwtClaims(input.accessToken);
+    const userId = claims.user_id ?? claims.sub;
+    const tenantId = claims.tenant_id;
+    if (!userId || !tenantId) {
+        throw new Error('Access token missing user_id or tenant_id for keychain account');
+    }
+    const account = signinKeychainAccount(input.aisUrl, tenantId, userId);
+    const renewal = {
+        refresh_token: input.refreshToken,
+        ...(claims.sid ? { sid: claims.sid } : {}),
+    };
+    const access = {
+        access_token: input.accessToken,
+        expires_at: input.expiresAt,
+    };
+    const store = backend();
+    store.write(SIGNIN_RENEWAL_SERVICE, account, JSON.stringify(renewal));
+    store.write(SIGNIN_ACCESS_SERVICE, account, JSON.stringify(access));
+}
+export function loadOwnerSignInAccessForPreference(aisUrl, pref) {
+    const userId = pref.ownerUserId;
+    if (!userId)
+        return null;
+    const store = backend();
+    if (!store.isAvailable())
+        return null;
+    const account = signinKeychainAccount(aisUrl, pref.tenantId, userId);
+    const raw = store.read(SIGNIN_ACCESS_SERVICE, account);
+    if (!raw)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.access_token !== 'string' || typeof parsed.expires_at !== 'string')
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+export function loadOwnerSignInRenewalForAccount(aisUrl, tenantId, userId) {
+    const store = backend();
+    if (!store.isAvailable())
+        return null;
+    const account = signinKeychainAccount(aisUrl, tenantId, userId);
+    const raw = store.read(SIGNIN_RENEWAL_SERVICE, account);
+    if (!raw)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.refresh_token !== 'string')
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/** Decode owner user id from a bearer without verifying the signature (local cache only). */
+export function ownerUserIdFromAccessToken(accessToken) {
+    try {
+        const claims = decodeJwtClaims(accessToken);
+        return claims.user_id ?? claims.sub ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Shown when preference marks an owner keychain session but access is missing (CORBOT-EBCB2D2B). */
+export const OWNER_KEYCHAIN_SIGNED_OUT = 'Signed out on this device (no AIS access token in the OS keychain). Complete AIS sign-in again before calling agent_load or other AIS tools.';
+export class OwnerKeychainSignedOutError extends Error {
+    constructor(message = OWNER_KEYCHAIN_SIGNED_OUT) {
+        super(message);
+        this.name = 'OwnerKeychainSignedOutError';
+    }
+}
+/**
+ * Bearer + ids for an owner terminal sign-in stored in the OS keychain.
+ * Returns null when the session is signed out or the access token is stale.
+ */
+export function credentialsFromOwnerKeychain(aisUrl, pref, activeAgentId, nowMs = Date.now()) {
+    if (!pref.ownerUserId)
+        return null;
+    const cached = loadOwnerSignInAccessForPreference(aisUrl, pref);
+    if (!cached || isCredsStale(cached.expires_at, nowMs))
+        return null;
+    return {
+        token: cached.access_token,
+        agentId: activeAgentId ?? pref.agentId,
+        tenantId: pref.tenantId,
+        expiresAt: cached.expires_at,
+    };
+}
+export function requireOwnerKeychainCredentials(aisUrl, pref, activeAgentId) {
+    const creds = credentialsFromOwnerKeychain(aisUrl, pref, activeAgentId);
+    if (!creds)
+        throw new OwnerKeychainSignedOutError();
+    return creds;
+}
+//# sourceMappingURL=signin-keychain.js.map

package/dist/signin-keychain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signin-keychain.js","sourceRoot":"","sources":["../src/signin-keychain.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGnD,MAAM,CAAC,MAAM,sBAAsB,GAAG,qCAAqC,CAAC;AAC5E,MAAM,CAAC,MAAM,qBAAqB,GAAG,qCAAqC,CAAC;AA0B3E,IAAI,eAAe,GAAiC,IAAI,CAAC;AAEzD,wDAAwD;AACxD,MAAM,UAAU,gCAAgC,CAAC,IAAkC;IACjF,eAAe,GAAG,IAAI,CAAC;AACzB,CAAC;AAED,SAAS,eAAe,CAAC,KAAa;IACpC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC/B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,eAAe,CAAC,CAAC;IACzD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAE,EAAE,WAAW,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IACnE,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAoB,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,MAAc,EAAE,QAAgB,EAAE,MAAc;IACpF,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC;IAClC,OAAO,GAAG,IAAI,IAAI,QAAQ,IAAI,MAAM,EAAE,CAAC;AACzC,CAAC;AAED,SAAS,wBAAwB,CAAC,WAAmB,EAAE,UAAkB;IACvE,MAAM,MAAM,GAAG,SAAS,CAAC,WAAW,EAAE,CAAC,IAAI,CAAC,EAAE;QAC5C,KAAK,EAAE,GAAG,UAAU,IAAI;QACxB,QAAQ,EAAE,OAAO;KAClB,CAAC,CAAC;IACH,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,MAAM,MAAM,GAAG,CAAC,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QAC3E,MAAM,IAAI,KAAK,CAAC,0BAA0B,MAAM,CAAC,MAAM,IAAI,SAAS,MAAM,MAAM,EAAE,CAAC,CAAC;IACtF,CAAC;AACH,CAAC;AAED,SAAS,wBAAwB;IAC/B,MAAM,MAAM,GAAG,SAAS,CAAC,OAAO,EAAE,CAAC,aAAa,CAAC,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC;IAC1E,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACtC,MAAM,KAAK,GAAG,SAAS,CAAC,aAAa,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC;IACpF,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC;AAClD,CAAC;AAED,SAAS,qBAAqB;IAC5B,IAAI,OAAO,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAClC,OAAO;YACL,WAAW,EAAE,GAAY,EAAE;gBACzB,MAAM,KAAK,GAAG,SAAS,CAAC,UAAU,EAAE,CAAC,MAAM,CAAC,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC;gBACrE,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC;YAC5B,CAAC;YACD,IAAI,EAAE,CAAC,OAAe,EAAE,OAAe,EAAiB,EAAE;gBACxD,MAAM,MAAM,GAAG,SAAS,CACtB,UAAU,EACV,CAAC,uBAAuB,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,EAC7D,EAAE,QAAQ,EAAE,OAAO,EAAE,CACtB,CAAC;gBACF,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;oBAAE,OAAO,IAAI,CAAC;gBACrC,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC;gBACrC,OAAO,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;YAChC,CAAC;YACD,KAAK,EAAE,CAAC,OAAe,EAAE,OAAe,EAAE,MAAc,EAAQ,EAAE;gBAChE,MAAM,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;gBAC3E,MAAM,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;gBAC3E,MAAM,aAAa,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;gBACzE,wBAAwB,CACtB,UAAU,EACV,+BAA+B,cAAc,SAAS,cAAc,SAAS,aAAa,GAAG,CAC9F,CAAC;YACJ,CAAC;SACF,CAAC;IACJ,CAAC;IAED,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,IAAI,wBAAwB,EAAE,EAAE,CAAC;QAC/D,OAAO;YACL,WAAW,EAAE,GAAY,EAAE,CAAC,wBAAwB,EAAE;YACtD,IAAI,EAAE,CAAC,OAAe,EAAE,OAAe,EAAiB,EAAE;gBACxD,MAAM,MAAM,GAAG,SAAS,CACtB,aAAa,EACb,CAAC,QAAQ,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,CAAC,EAClD,EAAE,QAAQ,EAAE,OAAO,EAAE,CACtB,CAAC;gBACF,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;oBAAE,OAAO,IAAI,CAAC;gBACrC,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC;gBACrC,OAAO,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;YAChC,CAAC;YACD,KAAK,EAAE,CAAC,OAAe,EAAE,OAAe,EAAE,MAAc,EAAQ,EAAE;gBAChE,MAAM,MAAM,GAAG,SAAS,CACtB,aAAa,EACb,CAAC,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,CAAC,EACrE,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,CACrC,CAAC;gBACF,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;oBACxB,MAAM,MAAM,GAAG,CAAC,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;oBAC3E,MAAM,IAAI,KAAK,CAAC,6BAA6B,MAAM,CAAC,MAAM,IAAI,SAAS,MAAM,MAAM,EAAE,CAAC,CAAC;gBACzF,CAAC;YACH,CAAC;SACF,CAAC;IACJ,CAAC;IAED,OAAO;QACL,WAAW,EAAE,GAAY,EAAE,CAAC,KAAK;QACjC,IAAI,EAAE,GAAkB,EAAE,CAAC,IAAI;QAC/B,KAAK,EAAE,GAAS,EAAE;YAChB,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;QAC/D,CAAC;KACF,CAAC;AACJ,CAAC;AAED,SAAS,OAAO;IACd,OAAO,eAAe,IAAI,qBAAqB,EAAE,CAAC;AACpD,CAAC;AAED,MAAM,UAAU,yBAAyB;IACvC,OAAO,OAAO,EAAE,CAAC,WAAW,EAAE,CAAC;AACjC,CAAC;AAED,MAAM,UAAU,yBAAyB,CAAC,KAKzC;IACC,MAAM,MAAM,GAAG,eAAe,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;IAClD,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,GAAG,CAAC;IAC5C,MAAM,QAAQ,GAAG,MAAM,CAAC,SAAS,CAAC;IAClC,IAAI,CAAC,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,gEAAgE,CAAC,CAAC;IACpF,CAAC;IACD,MAAM,OAAO,GAAG,qBAAqB,CAAC,KAAK,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;IACtE,MAAM,OAAO,GAAwB;QACnC,aAAa,EAAE,KAAK,CAAC,YAAY;QACjC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC3C,CAAC;IACF,MAAM,MAAM,GAAuB;QACjC,YAAY,EAAE,KAAK,CAAC,WAAW;QAC/B,UAAU,EAAE,KAAK,CAAC,SAAS;KAC5B,CAAC;IACF,MAAM,KAAK,GAAG,OAAO,EAAE,CAAC;IACxB,KAAK,CAAC,KAAK,CAAC,sBAAsB,EAAE,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;IACtE,KAAK,CAAC,KAAK,CAAC,qBAAqB,EAAE,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;AACtE,CAAC;AAED,MAAM,UAAU,kCAAkC,CAChD,MAAc,EACd,IAAiE;IAEjE,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,CAAC;IAChC,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACzB,MAAM,KAAK,GAAG,OAAO,EAAE,CAAC;IACxB,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE;QAAE,OAAO,IAAI,CAAC;IACtC,MAAM,OAAO,GAAG,qBAAqB,CAAC,MAAM,EAAE,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACrE,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,qBAAqB,EAAE,OAAO,CAAC,CAAC;IACvD,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IACtB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAuB,CAAC;QACrD,IAAI,OAAO,MAAM,CAAC,YAAY,KAAK,QAAQ,IAAI,OAAO,MAAM,CAAC,UAAU,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QAClG,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,UAAU,gCAAgC,CAC9C,MAAc,EACd,QAAgB,EAChB,MAAc;IAEd,MAAM,KAAK,GAAG,OAAO,EAAE,CAAC;IACxB,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE;QAAE,OAAO,IAAI,CAAC;IACtC,MAAM,OAAO,GAAG,qBAAqB,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;IAChE,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,sBAAsB,EAAE,OAAO,CAAC,CAAC;IACxD,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IACtB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAwB,CAAC;QACtD,IAAI,OAAO,MAAM,CAAC,aAAa,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QAC1D,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,6FAA6F;AAC7F,MAAM,UAAU,0BAA0B,CAAC,WAAmB;IAC5D,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,eAAe,CAAC,WAAW,CAAC,CAAC;QAC5C,OAAO,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,GAAG,IAAI,IAAI,CAAC;IAC9C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,qGAAqG;AACrG,MAAM,CAAC,MAAM,yBAAyB,GACpC,8IAA8I,CAAC;AAEjJ,MAAM,OAAO,2BAA4B,SAAQ,KAAK;IACpD,YAAY,UAAkB,yBAAyB;QACrD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,6BAA6B,CAAC;IAC5C,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,UAAU,4BAA4B,CAC1C,MAAc,EACd,IAAiE,EACjE,aAAsB,EACtB,QAAgB,IAAI,CAAC,GAAG,EAAE;IAE1B,IAAI,CAAC,IAAI,CAAC,WAAW;QAAE,OAAO,IAAI,CAAC;IACnC,MAAM,MAAM,GAAG,kCAAkC,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAChE,IAAI,CAAC,MAAM,IAAI,YAAY,CAAC,MAAM,CAAC,UAAU,EAAE,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACnE,OAAO;QACL,KAAK,EAAE,MAAM,CAAC,YAAY;QAC1B,OAAO,EAAE,aAAa,IAAI,IAAI,CAAC,OAAO;QACtC,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,SAAS,EAAE,MAAM,CAAC,UAAU;KAC7B,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,+BAA+B,CAC7C,MAAc,EACd,IAAiE,EACjE,aAAsB;IAEtB,MAAM,KAAK,GAAG,4BAA4B,CAAC,MAAM,EAAE,IAAI,EAAE,aAAa,CAAC,CAAC;IACxE,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,2BAA2B,EAAE,CAAC;IACpD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/startup-identity.d.ts

@@ -0,0 +1,71 @@
+/** What this process reports about itself at startup and through whoami. */
+export interface StartupIdentity {
+    clientVersion: string;
+    /** null when no agent is known locally (unbonded, or resolved on first call). */
+    agentId: string | null;
+    /** Where the credential comes from: an env variable name, a file path, or "none". */
+    credentialSource: string;
+}
+/** The auth mode main() selected, with the local facts each mode already holds. */
+export type CredentialSourceInput = {
+    kind: 'workspace-key';
+    env: Record<string, string | undefined>;
+    agentId: string;
+} | {
+    kind: 'agent-api-key';
+    env: Record<string, string | undefined>;
+    agentId: string;
+} | {
+    kind: 'run-pass';
+    runPassFile: string;
+    agentId: string;
+} | {
+    kind: 'oauth';
+    /** AIS_AGENT_ID chosen for this session, if any. */
+    sessionAgentId?: string;
+    /** Keys directory when exactly one device key is enrolled, else null. */
+    enrolledKeyDir: string | null;
+    /** Agent id in a usable saved owner session file, else null. */
+    diskAgentId: string | null;
+    credentialsFile: string;
+    /** Last bonded agent from the preference file, if any. */
+    preferredAgentId?: string;
+    /** Owner session tokens live in the OS keychain (CORBOT-51CAC5E8). */
+    keychainOwnerSession?: boolean;
+};
+/** Resolve version, agent and credential source from what main() already loaded. */
+export declare function describeStartupIdentity(clientVersion: string, input: CredentialSourceInput): StartupIdentity;
+/** One stderr line, e.g. `aismemory 0.8.3: agent <id> via env AIS_API_KEY`. */
+export declare function formatStartupIdentityLine(identity: StartupIdentity): string;
+/** Recorded once by main(); read by whoami. null clears it (tests). */
+export declare function setStartupIdentity(next: StartupIdentity | null): void;
+export declare function getStartupIdentity(): StartupIdentity | null;
+/** A server name defined in more than one config scope. */
+export interface ServerNameConflict {
+    name: string;
+    /** Human-readable scope labels with their file paths, in client precedence order. */
+    scopes: string[];
+    /** The scope label the client actually runs: the first of `scopes`. */
+    winner: string;
+    /** Credential env variable NAMES the winning entry sets (values never read out). */
+    winnerCredentialEnv: string[];
+    /** Losing scopes that set credential env, as "<scope> sets <NAMES>". */
+    ignoredCredentialEnv: string[];
+}
+export declare function setServerNameConflicts(next: ServerNameConflict[]): void;
+export declare function getServerNameConflicts(): ServerNameConflict[];
+/**
+ * Find server names the launching client defines in more than one scope.
+ *
+ * The server cannot learn the name its client gave it, so the candidates are
+ * `aismemory` plus any name whose entry runs this package. Scopes read are
+ * Claude Code's: local (`~/.claude.json` projects[cwd]), project
+ * (`<cwd>/.mcp.json`) and user (`~/.claude.json` top level), in that
+ * precedence order. Missing or invalid files are skipped.
+ */
+export declare function findDuplicateServerNames(opts: {
+    home: string;
+    cwd: string;
+}): ServerNameConflict[];
+/** The stderr / doctor text for one conflict. Names scopes only, never env or headers. */
+export declare function formatDuplicateServerWarning(conflict: ServerNameConflict): string;

package/dist/startup-identity.js

@@ -0,0 +1,213 @@
+/**
+ * Startup identity report (CORBOT-5D16CF2A).
+ *
+ * Two failure shapes looked identical to a user: an older aismemory install
+ * answering instead of the current one (different bond-prompt text, different
+ * tool list), and two MCP config entries with the same server name, where the
+ * client keeps one and the one holding the credentials is silently dropped.
+ * At startup the server now writes one stderr line naming its version, the
+ * agent it will act as and where that credential comes from, and warns when
+ * the launching client's config defines this server's name more than once.
+ *
+ * Everything here is local and read-only: no network call, no write. Only
+ * env variable NAMES and file PATHS are ever reported — never a key, token,
+ * header or env value.
+ */
+import { readFileSync, realpathSync } from 'node:fs';
+import { join } from 'node:path';
+/** Resolve version, agent and credential source from what main() already loaded. */
+export function describeStartupIdentity(clientVersion, input) {
+    switch (input.kind) {
+        case 'workspace-key':
+            // Mirrors loadWorkspaceKeyConfig's choice of variable.
+            return {
+                clientVersion,
+                agentId: input.agentId,
+                credentialSource: `env ${input.env['AIS_WORKSPACE_KEY'] !== undefined ? 'AIS_WORKSPACE_KEY' : 'AIS_API_KEY'}`,
+            };
+        case 'agent-api-key':
+            // Mirrors loadAgentApiKeyConfig's choice of variable.
+            return {
+                clientVersion,
+                agentId: input.agentId,
+                credentialSource: `env ${input.env['AIS_API_KEY'] !== undefined ? 'AIS_API_KEY' : 'AIS_AGENT_API_KEY'}`,
+            };
+        case 'run-pass':
+            return { clientVersion, agentId: input.agentId, credentialSource: `run-pass file ${input.runPassFile}` };
+        case 'oauth':
+            if (input.keychainOwnerSession) {
+                return {
+                    clientVersion,
+                    agentId: input.sessionAgentId ?? input.preferredAgentId ?? input.diskAgentId ?? null,
+                    credentialSource: 'OS keychain owner sign-in',
+                };
+            }
+            // An enrolled device key owns the live session even when a disk bearer exists (F4).
+            if (input.enrolledKeyDir !== null) {
+                return {
+                    clientVersion,
+                    agentId: input.sessionAgentId ?? input.preferredAgentId ?? null,
+                    credentialSource: `device key file in ${input.enrolledKeyDir}`,
+                };
+            }
+            if (input.diskAgentId !== null) {
+                return {
+                    clientVersion,
+                    agentId: input.sessionAgentId ?? input.diskAgentId,
+                    credentialSource: `owner session file ${input.credentialsFile}`,
+                };
+            }
+            return { clientVersion, agentId: input.sessionAgentId ?? null, credentialSource: 'none' };
+    }
+}
+/** One stderr line, e.g. `aismemory 0.8.3: agent <id> via env AIS_API_KEY`. */
+export function formatStartupIdentityLine(identity) {
+    return `aismemory ${identity.clientVersion}: agent ${identity.agentId ?? 'none (unbonded)'} via ${identity.credentialSource}`;
+}
+let startupIdentity = null;
+/** Recorded once by main(); read by whoami. null clears it (tests). */
+export function setStartupIdentity(next) {
+    startupIdentity = next;
+}
+export function getStartupIdentity() {
+    return startupIdentity;
+}
+let serverNameConflicts = [];
+export function setServerNameConflicts(next) {
+    serverNameConflicts = next;
+}
+export function getServerNameConflicts() {
+    return serverNameConflicts;
+}
+/** The name this package documents in every install snippet. */
+const DEFAULT_SERVER_NAME = 'aismemory';
+/** Env variables that select an aismemory credential. Only their names are reported. */
+const CREDENTIAL_ENV_NAMES = [
+    'AIS_WORKSPACE_KEY',
+    'AIS_API_KEY',
+    'AIS_AGENT_API_KEY',
+    'AIS_RUN_PASS_FILE',
+    'AIS_CREDENTIALS_FILE',
+];
+/** Names of credential env variables a server entry sets, without reading their values. */
+function credentialEnvNames(entry) {
+    if (!isRecord(entry))
+        return [];
+    const env = entry['env'];
+    if (!isRecord(env))
+        return [];
+    return CREDENTIAL_ENV_NAMES.filter((name) => Object.hasOwn(env, name));
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Parse a JSON file; null when missing, unreadable or invalid. */
+function readJsonFile(path) {
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** The mcpServers map under `container`, or an empty map when absent or malformed. */
+function serversOf(container) {
+    if (!isRecord(container))
+        return {};
+    const servers = container['mcpServers'];
+    return isRecord(servers) ? servers : {};
+}
+/** Matches `aismemory`, `aismemory@0.8.0`, `/usr/local/bin/aismemory`. */
+const PACKAGE_TOKEN = /(^|[\\/])aismemory(@[^\\/\s]*)?$/;
+/** Matches a direct node launch of this package's entrypoint. */
+const PACKAGE_ENTRYPOINT = /(aismemory|agentmemory)[\\/]dist[\\/]index\.js$/;
+/** True when a server entry's command or args launch this package. */
+function runsThisPackage(entry) {
+    if (!isRecord(entry))
+        return false;
+    const parts = [];
+    if (typeof entry['command'] === 'string')
+        parts.push(entry['command']);
+    const args = entry['args'];
+    if (Array.isArray(args)) {
+        for (const arg of args)
+            if (typeof arg === 'string')
+                parts.push(arg);
+    }
+    return parts
+        .flatMap((part) => part.split(/\s+/))
+        .some((token) => PACKAGE_TOKEN.test(token) || PACKAGE_ENTRYPOINT.test(token));
+}
+/**
+ * Find server names the launching client defines in more than one scope.
+ *
+ * The server cannot learn the name its client gave it, so the candidates are
+ * `aismemory` plus any name whose entry runs this package. Scopes read are
+ * Claude Code's: local (`~/.claude.json` projects[cwd]), project
+ * (`<cwd>/.mcp.json`) and user (`~/.claude.json` top level), in that
+ * precedence order. Missing or invalid files are skipped.
+ */
+export function findDuplicateServerNames(opts) {
+    let cwd = opts.cwd;
+    try {
+        cwd = realpathSync(opts.cwd);
+    }
+    catch {
+        // Keep the supplied path for missing or unreadable launch directories.
+    }
+    const userFile = join(opts.home, '.claude.json');
+    const projectFile = join(cwd, '.mcp.json');
+    const userConfig = readJsonFile(userFile);
+    const projects = isRecord(userConfig) ? userConfig['projects'] : undefined;
+    const projectKey = isRecord(projects)
+        ? Object.hasOwn(projects, cwd) ? cwd : Object.hasOwn(projects, opts.cwd) ? opts.cwd : null
+        : null;
+    const projectScope = projectKey === null || !isRecord(projects) ? undefined : projects[projectKey];
+    const scopes = [
+        {
+            kind: 'local',
+            label: `local (${userFile} projects[${projectKey ?? cwd}])`,
+            servers: serversOf(projectScope),
+        },
+        { kind: 'project', label: `project (${projectFile})`, servers: serversOf(readJsonFile(projectFile)) },
+        { kind: 'user', label: `user (${userFile})`, servers: serversOf(userConfig) },
+    ];
+    const candidates = new Set([DEFAULT_SERVER_NAME]);
+    for (const scope of scopes) {
+        for (const [name, entry] of Object.entries(scope.servers)) {
+            if (runsThisPackage(entry))
+                candidates.add(name);
+        }
+    }
+    const conflicts = [];
+    for (const name of candidates) {
+        const defining = scopes.filter((scope) => Object.hasOwn(scope.servers, name) && isRecord(scope.servers[name]));
+        if (defining.length < 2)
+            continue;
+        const [winner, ...losers] = defining;
+        conflicts.push({
+            name,
+            scopes: defining.map((scope) => scope.label),
+            winner: winner.label,
+            winnerCredentialEnv: credentialEnvNames(winner.servers[name]),
+            ignoredCredentialEnv: losers
+                .map((scope) => ({ label: scope.label, names: credentialEnvNames(scope.servers[name]) }))
+                .filter((loser) => loser.names.length > 0)
+                .map((loser) => `${loser.label} sets ${loser.names.join(', ')}`),
+        });
+    }
+    return conflicts;
+}
+/** The stderr / doctor text for one conflict. Names scopes only, never env or headers. */
+export function formatDuplicateServerWarning(conflict) {
+    const winnerCredential = conflict.winnerCredentialEnv.length > 0
+        ? `the winner sets credential env ${conflict.winnerCredentialEnv.join(', ')}`
+        : 'the winner has no credential env';
+    const ignored = conflict.ignoredCredentialEnv.length > 0
+        ? ` Ignored: ${conflict.ignoredCredentialEnv.join('; ')}.`
+        : '';
+    return (`MCP server name "${conflict.name}" is defined in ${conflict.scopes.length} config scopes: ` +
+        `${conflict.scopes.join(', ')}. The ${conflict.winner} entry wins (precedence: local > project > user); ` +
+        `${winnerCredential}.${ignored} Remove or rename the duplicates.`);
+}
+//# sourceMappingURL=startup-identity.js.map

package/dist/startup-identity.js.map

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

package/dist/tool-args.d.ts

@@ -19,6 +19,7 @@ export declare const rememberArgsSchema: z.ZodObject<{
     }>>>;
     importance: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
     tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    supersedes: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const recallArgsSchema: z.ZodObject<{
     principalAgentId: z.ZodOptional<z.ZodString>;
@@ -33,6 +34,9 @@ export declare const recallArgsSchema: z.ZodObject<{
         task: "task";
     }>>;
     tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    orderBy: z.ZodOptional<z.ZodEnum<{
+        newest: "newest";
+    }>>;
 }, z.core.$strip>;
 export declare const handoffArgsSchema: z.ZodObject<{
     summary: z.ZodOptional<z.ZodString>;
@@ -56,6 +60,9 @@ export declare const emptyArgsSchema: z.ZodObject<{}, z.core.$strict>;
  */
 export declare const FULL_CONTEXT_MIN_MAX_TOKENS = 500;
 export declare const FULL_CONTEXT_MAX_MAX_TOKENS = 20000;
+/** Mirrors the server's context-window bounds (full-context.ts MIN/MAX_CONTEXT_WINDOW). */
+export declare const FULL_CONTEXT_MIN_WINDOW = 1000;
+export declare const FULL_CONTEXT_MAX_WINDOW = 10000000;
 export declare const fullContextArgsSchema: z.ZodObject<{
     principalAgentId: z.ZodOptional<z.ZodString>;
     memoriesLimit: z.ZodOptional<z.ZodNumber>;
@@ -65,6 +72,7 @@ export declare const fullContextArgsSchema: z.ZodObject<{
         bootstrap: "bootstrap";
     }>>;
     maxTokens: z.ZodOptional<z.ZodNumber>;
+    contextWindowSize: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>;
 export declare const INBOX_MAX_BODY_CHARS = 8000;
 export declare const INBOX_MAX_TASK_ID_CHARS = 128;
@@ -155,6 +163,8 @@ export declare function parseHandoffArgs(raw: unknown): HandoffArgs;
 export declare function parseAgentLoadArgs(raw: unknown): AgentLoadArgs;
 export declare function parseEmptyToolArgs(raw: unknown): Record<string, never>;
 export declare function parseFullContextArgs(raw: unknown): FullContextArgs;
+/** Query string (with leading `?`, or empty) for the full-context endpoint; shared by every dispatcher. */
+export declare function buildFullContextQuery(args: FullContextArgs): string;
 export declare function parseInboxSendArgs(raw: unknown): InboxSendArgs;
 export declare function parseInboxReadArgs(raw: unknown): InboxReadArgs;
 export declare function parseGoalCreateArgs(raw: unknown): GoalCreateArgs;

package/dist/tool-args.js

@@ -23,6 +23,14 @@ export const rememberArgsSchema = z.object({
     type: memoryTypeSchema.optional().default('context'),
     importance: z.number().min(0).max(1).optional().default(0.5),
     tags: tagsArgSchema.optional(),
+    /**
+     * Id of an older memory of this agent that this one replaces
+     * (CORBOT-FC8D0DCC). The server keeps it but leaves it out of recall.
+     */
+    supersedes: z
+        .string({ message: 'supersedes must be a memory id' })
+        .regex(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i, 'supersedes must be a memory id (UUID)')
+        .optional(),
 });
 /**
  * Optional delegated-read principal (CORBOT-3785D10D).
@@ -44,6 +52,11 @@ export const recallArgsSchema = z.object({
     type: memoryTypeSchema.optional(),
     /** Only memories carrying every one of these tags. */
     tags: tagsArgSchema.optional(),
+    /**
+     * Newest-first list instead of a ranked search (CORBOT-B1770E61). The only
+     * value AIS accepts is `newest`; it also needs `type` or `tags`.
+     */
+    orderBy: z.enum(['newest'], { message: "orderBy must be 'newest'" }).optional(),
 });
 export const handoffArgsSchema = z.object({
     summary: z
@@ -83,6 +96,9 @@ export const emptyArgsSchema = z.object({}).strict();
  */
 export const FULL_CONTEXT_MIN_MAX_TOKENS = 500;
 export const FULL_CONTEXT_MAX_MAX_TOKENS = 20_000;
+/** Mirrors the server's context-window bounds (full-context.ts MIN/MAX_CONTEXT_WINDOW). */
+export const FULL_CONTEXT_MIN_WINDOW = 1000;
+export const FULL_CONTEXT_MAX_WINDOW = 10_000_000;
 export const fullContextArgsSchema = z
     .object({
     principalAgentId: principalAgentIdSchema.optional(),
@@ -96,6 +112,13 @@ export const fullContextArgsSchema = z
         .min(FULL_CONTEXT_MIN_MAX_TOKENS)
         .max(FULL_CONTEXT_MAX_MAX_TOKENS)
         .optional(),
+    /** Caller's model context window in tokens; scales the skills budget. */
+    contextWindowSize: z
+        .number()
+        .int()
+        .min(FULL_CONTEXT_MIN_WINDOW)
+        .max(FULL_CONTEXT_MAX_WINDOW)
+        .optional(),
 })
     .strict();
 // ── Agent inbox (CORBOT-7115B8AE) ───────────────────────────────────────
@@ -241,6 +264,22 @@ export function parseEmptyToolArgs(raw) {
 export function parseFullContextArgs(raw) {
     return parseOrThrow(fullContextArgsSchema, raw);
 }
+/** Query string (with leading `?`, or empty) for the full-context endpoint; shared by every dispatcher. */
+export function buildFullContextQuery(args) {
+    const params = new URLSearchParams();
+    if (args.principalAgentId !== undefined)
+        params.set('principalAgentId', args.principalAgentId);
+    if (args.memoriesLimit !== undefined)
+        params.set('memoriesLimit', String(args.memoriesLimit));
+    if (args.view !== undefined)
+        params.set('view', args.view);
+    if (args.maxTokens !== undefined)
+        params.set('maxTokens', String(args.maxTokens));
+    if (args.contextWindowSize !== undefined)
+        params.set('contextWindowSize', String(args.contextWindowSize));
+    const qs = params.toString();
+    return qs ? `?${qs}` : '';
+}
 export function parseInboxSendArgs(raw) {
     return parseOrThrow(inboxSendArgsSchema, raw);
 }