@alfe.ai/claude-code-host 0.1.14 → 0.1.15

package/dist/index.cjs

@@ -1,11 +1,21 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_host_config = require("./host-config.cjs");
+exports.AUTH_PROBE_TIMEOUT_MS = require_host_config.AUTH_PROBE_TIMEOUT_MS;
 exports.BRIDGE_ENV_VAR = require_host_config.BRIDGE_ENV_VAR;
 exports.CLAUDE_PERMISSION_MODES = require_host_config.CLAUDE_PERMISSION_MODES;
+exports.CREDENTIAL_ENV_VAR = require_host_config.CREDENTIAL_ENV_VAR;
+exports.CREDENTIAL_INVALID_MESSAGE = require_host_config.CREDENTIAL_INVALID_MESSAGE;
+exports.CREDENTIAL_MISSING_MESSAGE = require_host_config.CREDENTIAL_MISSING_MESSAGE;
+exports.CREDENTIAL_UNAVAILABLE_MESSAGE = require_host_config.CREDENTIAL_UNAVAILABLE_MESSAGE;
 exports.ClaudeCodeHost = require_host_config.ClaudeCodeHost;
+exports.CredentialStatusReporter = require_host_config.CredentialStatusReporter;
 exports.DEFAULT_ALLOWED_TOOLS = require_host_config.DEFAULT_ALLOWED_TOOLS;
 exports.DEFAULT_PERMISSION_MODE = require_host_config.DEFAULT_PERMISSION_MODE;
+exports.LOCAL_LOGIN_FAILED_MESSAGE = require_host_config.LOCAL_LOGIN_FAILED_MESSAGE;
+exports.MANAGED_ALLOWED_TOOLS = require_host_config.MANAGED_ALLOWED_TOOLS;
+exports.MANAGED_DISALLOWED_TOOLS = require_host_config.MANAGED_DISALLOWED_TOOLS;
 exports.SCRUBBED_ANTHROPIC_ENV_VARS = require_host_config.SCRUBBED_ANTHROPIC_ENV_VARS;
+exports.STATUS_REPORT_INTERVAL_MS = require_host_config.STATUS_REPORT_INTERVAL_MS;
 exports.SessionDriver = require_host_config.SessionDriver;
 exports.TERMINATION_GRACE_MS = require_host_config.TERMINATION_GRACE_MS;
 exports.TURN_TIMEOUT_MS = require_host_config.TURN_TIMEOUT_MS;
@@ -13,13 +23,18 @@ exports.WARM_STREAMING_SUPPORTED = require_host_config.WARM_STREAMING_SUPPORTED;
 exports.addMessage = require_host_config.addMessage;
 exports.appendActivity = require_host_config.appendActivity;
 exports.buildChildEnv = require_host_config.buildChildEnv;
+exports.buildProbeArgs = require_host_config.buildProbeArgs;
 exports.collectTurnActivityRecords = require_host_config.collectTurnActivityRecords;
 exports.createMapperState = require_host_config.createMapperState;
 exports.createSession = require_host_config.createSession;
 exports.getSession = require_host_config.getSession;
+exports.isAuthFailureText = require_host_config.isAuthFailureText;
 exports.listSessions = require_host_config.listSessions;
+exports.loadCredentialWithRetry = require_host_config.loadCredentialWithRetry;
 exports.mapStreamEvent = require_host_config.mapStreamEvent;
 exports.mapStreamEvents = require_host_config.mapStreamEvents;
+exports.parseProbeOutput = require_host_config.parseProbeOutput;
 exports.resolveHostConfig = require_host_config.resolveHostConfig;
+exports.runAuthProbe = require_host_config.runAuthProbe;
 exports.saveSession = require_host_config.saveSession;
 exports.stripAgentPrefix = require_host_config.stripAgentPrefix;

package/dist/index.d.cts

@@ -849,6 +849,33 @@ interface AgentWorkspaceInfo {
   teamIds?: string[];
   projectIds?: string[];
 }
+/**
+ * The agent's own Claude credential (claude-code runtime), from
+ * GET /agent/claude-credential. `oauth_token` is a Claude subscription token
+ * (`claude setup-token`) for `CLAUDE_CODE_OAUTH_TOKEN`; `api_key` is an
+ * Anthropic API key for `ANTHROPIC_API_KEY`. `revision` changes on every
+ * dashboard write. Hold the value in memory only — never log or persist it.
+ */
+interface AgentClaudeCredential {
+  kind: "oauth_token" | "api_key";
+  value: string;
+  revision: string;
+  updatedAt: string;
+}
+/** Claude auth health a claude-code host reports for its agent. */
+type ClaudeCredentialHealth = "ok" | "missing" | "invalid";
+/** Body of PUT /agent/claude-credential/status. */
+interface ClaudeCredentialStatusReport {
+  status: ClaudeCredentialHealth;
+  /** Short (≤200 chars), fixed host-side explanation. Never `claude` output or a secret. */
+  detail?: string;
+  /**
+   * The credential revision the host checked (from `getClaudeCredential()`);
+   * omit when it found none. The server drops reports for a superseded
+   * revision and answers `{ accepted: false }`.
+   */
+  revision?: string;
+}
 declare class WorkspaceApi extends ApiBase {
   /**
    * GET /agent/workspace — workspace config for the authenticated agent
@@ -865,6 +892,22 @@ declare class WorkspaceApi extends ApiBase {
   }): Promise<{
     files: Record<string, string>;
   }>;
+  /**
+   * GET /agent/claude-credential — the authenticated claude-code agent's own
+   * Claude credential, or `null` when none is stored (a self-hosted host then
+   * falls back to the local `claude` login). Fetch on every runtime start: the
+   * daemon restarts the host whenever the credential changes.
+   */
+  getClaudeCredential(): Promise<AgentClaudeCredential | null>;
+  /**
+   * PUT /agent/claude-credential/status — report whether this claude-code agent
+   * can authenticate to Claude. `accepted: false` means the report described a
+   * credential that has since been replaced; nothing was written. Not retried
+   * automatically (a mutation): the host re-reports on its next signal.
+   */
+  reportClaudeCredentialStatus(report: ClaudeCredentialStatusReport): Promise<{
+    accepted: boolean;
+  }>;
 }
 //# sourceMappingURL=workspace.d.ts.map
 //#endregion
@@ -2224,6 +2267,64 @@ declare class ChatServiceClient {
  * Resolution priority: explicit overrides → config file → env vars.
  */
 //#endregion
+//#region src/child-env.d.ts
+/**
+ * Child-process environment construction for spawned `claude` CLI processes.
+ *
+ * THREE non-negotiable invariants:
+ *
+ * 1. **Scrub inherited Claude auth.** `ANTHROPIC_API_KEY` / `ANTHROPIC_BASE_URL`
+ *    / `ANTHROPIC_AUTH_TOKEN` / `CLAUDE_CODE_OAUTH_TOKEN` are removed from BOTH
+ *    the parent env and any caller `extra`. A self-hosted Mac very often has
+ *    these set for other tooling; if one reaches `claude` it silently switches
+ *    accounts or billing plane (or routes through a proxy). The break is
+ *    silent: the turn "works" but bills the wrong account.
+ *
+ * 2. **Inject the agent's own credential, last.** When the agents service holds
+ *    a Claude credential for this agent, it is set AFTER the scrub as exactly
+ *    one variable: `CLAUDE_CODE_OAUTH_TOKEN` (subscription token from
+ *    `claude setup-token`) or `ANTHROPIC_API_KEY` (Anthropic API key). Nothing
+ *    else can override it. With no credential, no auth variable is set and
+ *    `claude` uses the machine's own login (self-hosted fallback). The value
+ *    lives only in the host's memory and this env — never on disk, never logged.
+ *
+ * 3. **Set `ALFE_CLAUDE_BRIDGE=1`.** The Phase-1 CLI hooks
+ *    (`alfe claude hook ...` in `packages/cli/src/commands/claude.ts`) check
+ *    `process.env.ALFE_CLAUDE_BRIDGE` FIRST and no-op when set, so the host —
+ *    not the interactive-session hooks — owns memory recall/capture for bridged
+ *    turns. Omitting this double-captures every message. The env var NAME is a
+ *    cross-phase contract; do not rename without updating the CLI.
+ */
+/** Claude auth env vars that MUST NOT be inherited by a `claude` child. */
+declare const SCRUBBED_ANTHROPIC_ENV_VARS: readonly ["ANTHROPIC_API_KEY", "ANTHROPIC_BASE_URL", "ANTHROPIC_AUTH_TOKEN", "CLAUDE_CODE_OAUTH_TOKEN"];
+/**
+ * Provider-selection and endpoint overrides that would route `claude` away from
+ * the Anthropic API. Dropped whenever an agent credential is injected, so an
+ * inherited `CLAUDE_CODE_USE_BEDROCK=1` (say) can't send the turn to Bedrock
+ * and ignore the stored credential. Without a credential they are left alone:
+ * the machine's own `claude` setup is the fallback, whatever provider it uses.
+ */
+
+/** Cross-phase contract marker (see header + packages/cli/src/commands/claude.ts). */
+declare const BRIDGE_ENV_VAR = "ALFE_CLAUDE_BRIDGE";
+/** The agent's Claude credential, as fetched from `GET /agent/claude-credential`. */
+interface ChildCredential {
+  kind: 'oauth_token' | 'api_key';
+  value: string;
+}
+/** The single env var each credential kind is exported as. */
+declare const CREDENTIAL_ENV_VAR: Record<ChildCredential['kind'], string>;
+/**
+ * Build the env handed to a spawned `claude` child. Pure — takes the base env
+ * explicitly so it unit-tests without touching `process.env`.
+ *
+ * Order: merge `base` + `extra` → drop every scrubbed var (plus provider
+ * overrides when a credential is injected) → set the bridge
+ * marker → set the agent credential (if any). Neither `base` nor `extra` can
+ * smuggle an auth variable in or override the injected credential.
+ */
+declare function buildChildEnv(base: NodeJS.ProcessEnv, extra?: Record<string, string>, credential?: ChildCredential | null): NodeJS.ProcessEnv;
+//#endregion
 //#region src/stream-mapper.d.ts
 /**
  * Claude Code `--output-format stream-json` → Alfe chat-activity mapper.
@@ -2314,6 +2415,12 @@ interface EndEmission {
   durationMs?: number;
   /** Error reason (present when `isError`). Goes under `payload.message` (C3). */
   errorMessage?: string;
+  /**
+   * True when Claude refused the credential (assistant `error:
+   * "authentication_failed"`, a 401/403 `api_error_status`, or a known auth
+   * message). Present only on error turns.
+   */
+  authFailed?: true;
 }
 type MapperEmission = ActivityEmission | TextEmission | EndEmission;
 interface PendingTool {
@@ -2333,6 +2440,8 @@ interface MapperState {
   pendingTools: Map<string, PendingTool>;
   /** Whether the terminal `result` event has been seen. */
   ended: boolean;
+  /** Set by an assistant `error: "authentication_failed"` frame. */
+  authFailed: boolean;
 }
 declare function createMapperState(): MapperState;
 /**
@@ -2382,6 +2491,26 @@ declare const WARM_STREAMING_SUPPORTED = false;
  * shell. Callers that want a wider set pass `allowedTools` explicitly.
  */
 declare const DEFAULT_ALLOWED_TOOLS: readonly ["Read", "Grep", "Glob", "LS", "Edit", "Write", "WebFetch", "WebSearch", "Task", "TodoWrite"];
+/**
+ * Managed VMs (`ALFE_MANAGED=1|true`) add `Bash` to the allow-list. The VM is
+ * the agent's own machine (no user data beside the agent's workspace), and
+ * shell access is what makes a managed coding agent useful. Still
+ * `--permission-mode dontAsk` (never bypass), and the managed VM runs as root:
+ * claude refuses only `--dangerously-skip-permissions` under root, not
+ * `dontAsk`. `Edit`/`Write` are already in the default set; `MultiEdit` is not
+ * a tool in the pinned claude (2.1.x), so it is not listed.
+ */
+declare const MANAGED_ALLOWED_TOOLS: readonly ["Read", "Grep", "Glob", "LS", "Edit", "Write", "WebFetch", "WebSearch", "Task", "TodoWrite", "Bash"];
+/**
+ * Deny rules layered on the managed allow-list (`--disallowedTools`, which
+ * wins over `--allowedTools`). They keep the agent from re-running Google
+ * Workspace CLI auth and from reading its token directory with the Read tool.
+ * They are NOT a security boundary: with Bash allowed, `cat`, `cp`, `env` and
+ * friends can still read anything the root user can. Verified on claude
+ * 2.1.284: a `Bash(<prefix>:*)` rule denies the matching command under
+ * `dontAsk` while other Bash commands run.
+ */
+declare const MANAGED_DISALLOWED_TOOLS: readonly ["Bash(gws auth)", "Bash(gws auth:*)", "Read(~/.config/gws-*/**)"];
 declare const CLAUDE_PERMISSION_MODES: readonly ["acceptEdits", "auto", "manual", "dontAsk", "plan"];
 type ClaudePermissionMode = (typeof CLAUDE_PERMISSION_MODES)[number];
 /**
@@ -2404,6 +2533,8 @@ interface DriverTurnResult {
   errorMessage?: string;
   /** True if the turn was aborted via `abort()` (SIGINT). */
   aborted: boolean;
+  /** Present (true) when the turn failed because Claude refused the credential. */
+  authFailed?: true;
 }
 interface RunTurnParams {
   /** The user prompt for this turn. */
@@ -2449,12 +2580,21 @@ declare class SessionDriver {
   private abortCurrent;
   private readonly bin;
   private readonly baseEnv;
+  private readonly credential;
+  private readonly managed;
   private readonly log;
   /** Injected spawn — tests replace this with a fake child. */
   private readonly spawnImpl;
   constructor(opts?: {
     claudeBin?: string;
     baseEnv?: NodeJS.ProcessEnv;
+    /**
+     * The agent's Claude credential, injected into the child env after the
+     * scrub. Null/absent → the machine's own `claude` login.
+     */
+    credential?: ChildCredential | null;
+    /** Managed VM: Bash allowed + deny rules (see MANAGED_ALLOWED_TOOLS). */
+    managed?: boolean;
     logger?: Logger;
     /** Test seam: inject a fake `spawn`. */
     __spawn?: typeof spawn;
@@ -2475,6 +2615,89 @@ declare class SessionDriver {
   private runPerTurn;
 }
 //#endregion
+//#region src/credential.d.ts
+interface HostCredential extends ChildCredential {
+  /** Non-secret revision; travels with status reports as the fence. */
+  revision: string;
+}
+interface LoadCredentialOptions {
+  /** Aborted on host stop; the loop then resolves `null`. */
+  signal: AbortSignal;
+  log: Logger;
+  baseDelayMs?: number;
+  maxDelayMs?: number;
+  /** Jitter source in [0,1]; the delay is `cap * (0.5 + random/2)`. */
+  random?: () => number;
+  sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
+}
+/**
+ * Fetch until it answers. `{ credential: null }` = nothing stored (a real
+ * answer); `null` = aborted before any answer.
+ */
+declare function loadCredentialWithRetry(fetchCredential: () => Promise<HostCredential | null>, opts: LoadCredentialOptions): Promise<{
+  credential: HostCredential | null;
+} | null>;
+declare function isAuthFailureText(text: string): boolean;
+/** HTTP statuses on a `result` event that mean "credential refused". */
+
+type ProbeOutcome = {
+  result: 'ok';
+} | {
+  result: 'invalid';
+} | {
+  result: 'unknown';
+  reason: string;
+};
+declare const AUTH_PROBE_TIMEOUT_MS = 60000;
+/** argv for the probe. No tools, no session file, no MCP, no settings files. */
+declare function buildProbeArgs(): string[];
+declare function parseProbeOutput(stdout: string, stderr: string, exitCode: number | null): ProbeOutcome;
+interface AuthProbeOptions {
+  credential: ChildCredential | null;
+  baseEnv: NodeJS.ProcessEnv;
+  /** Any existing directory; the probe reads and writes nothing there. */
+  cwd: string;
+  claudeBin?: string;
+  timeoutMs?: number;
+  spawnImpl?: typeof spawn;
+  /** Host stop: the child is SIGKILLed and the probe settles `unknown`. */
+  signal?: AbortSignal;
+}
+/**
+ * One minimal real turn against Anthropic with the agent's credential (or,
+ * when none is stored, the machine's own login). Never throws.
+ */
+declare function runAuthProbe(opts: AuthProbeOptions): Promise<ProbeOutcome>;
+interface CredentialStatusReport {
+  status: 'ok' | 'missing' | 'invalid';
+  /** Fixed, host-authored text only. Never `claude` output. */
+  detail?: string;
+  revision?: string;
+}
+/** An unchanged status is re-sent at most this often (a liveness signal). */
+declare const STATUS_REPORT_INTERVAL_MS: number;
+/**
+ * Sends health reports on change, or when the same report is older than
+ * {@link STATUS_REPORT_INTERVAL_MS}. Sends are serialized; a failed send is
+ * not remembered, so the next signal retries. Never throws.
+ */
+declare class CredentialStatusReporter {
+  private readonly send;
+  private lastKey;
+  private lastSentAt;
+  private chain;
+  private readonly now;
+  private readonly log;
+  constructor(send: (report: CredentialStatusReport) => Promise<{
+    accepted: boolean;
+  }>, opts: {
+    log: Logger;
+    now?: () => number;
+  });
+  report(report: CredentialStatusReport): Promise<void>;
+  private deliver;
+}
+//#endregion
 //#region src/host.d.ts
 interface ClaudeCodeHostConfig {
   /** Chat service WS URL (e.g. wss://chat.dev.alfe.ai/ws). */
@@ -2496,8 +2719,20 @@ interface ClaudeCodeHostConfig {
    * NEVER provider-qualified (`anthropic/…`) — that's an OpenClaw-only shape.
    */
   model?: string;
+  /**
+   * Managed VM (`ALFE_MANAGED=1|true`, set by the daemon). Enables Bash, and a
+   * missing Claude credential is a hard "missing" state (no local login to
+   * fall back to). Self-hosted when false/absent.
+   */
+  managed?: boolean;
   logger?: Logger;
 }
+declare const CREDENTIAL_INVALID_MESSAGE = "This agent's Claude credential is invalid or expired. Update it in agent settings.";
+declare const LOCAL_LOGIN_FAILED_MESSAGE = "Claude Code is not signed in on this machine. Run `claude` and log in, or add a Claude credential in agent settings.";
+declare const CREDENTIAL_MISSING_MESSAGE = "This agent has no Claude credential. Add a Claude subscription token or an Anthropic API key in agent settings.";
+declare const CREDENTIAL_UNAVAILABLE_MESSAGE = "This agent's Claude credential couldn't be loaded yet. Try again in a moment.";
+/** How long a turn waits for the start-up credential fetch before failing. */
+
 declare class ClaudeCodeHost {
   private readonly chat;
   /**
@@ -2521,14 +2756,69 @@ declare class ClaudeCodeHost {
   private claudeSessionSave;
   private stopping;
   private stopPromise;
+  /**
+   * Resolves once the first fetch has answered. Null until `start()` (the
+   * direct handleRequest test seam runs on the local login, no wait).
+   */
+  private credentialReady;
+  private resolveCredentialReady;
+  /** Turns wait for the first fetch only until this time (start + wait). */
+  private credentialDeadline;
+  private credentialLoaded;
+  /** Turns waiting for the credential, before queue admission (chat.abort). */
+  private readonly waitingTurns;
+  private readonly loaderRestartMs;
+  /** In memory only. Never logged, never persisted. */
+  private credential;
+  private readonly credentialAbort;
+  private readonly reporter;
+  private readonly probe;
+  private readonly credentialWaitMs;
+  private readonly credentialRetry;
   constructor(cfg: ClaudeCodeHostConfig, deps?: {
-    /** Per-turn driver factory (test seam). Called once per turn. */
-    makeDriver?: () => SessionDriver;
+    /**
+     * Per-turn driver factory (test seam). Called once per turn with the
+     * agent's credential (null → the machine's own `claude` login).
+     */
+    makeDriver?: (credential: ChildCredential | null) => SessionDriver;
     chat?: ChatServiceClient;
     api?: AgentApiClient;
+    /** Start-up auth check (test seam; default: a minimal `claude -p`). */
+    probe?: (credential: ChildCredential | null, signal: AbortSignal) => Promise<ProbeOutcome>;
+    credentialWaitMs?: number;
+    /** Delay before restarting a credential loader that threw (default 5 s). */
+    loaderRestartMs?: number;
+    credentialRetry?: {
+      baseDelayMs?: number;
+      maxDelayMs?: number;
+    };
   });
   /** Start the chat WS. Non-blocking — the client reconnects internally. */
   start(): Promise<void>;
+  /**
+   * Run the fetch + check, restarting it after an unexpected throw so a bug
+   * can never leave the host without a credential until the next restart.
+   */
+  private runCredentialLoader;
+  private loadCredential;
+  private childCredential;
+  /** Start-up health check: one minimal real call, reported to the cloud. */
+  private checkCredential;
+  /** Report the credential (or the local login) as working or refused. */
+  private reportAuth;
+  /**
+   * Wait for the first credential answer BEFORE queue admission, so a waiting
+   * turn holds no slot. Bounded by the start-up deadline: once it has passed,
+   * later turns stop waiting until the load completes. Cancelled by
+   * `chat.abort` or host stop through `cancellation`.
+   */
+  private awaitCredential;
+  /**
+   * Instant credential gate inside the turn (no waiting: `handleAgent` already
+   * waited). Returns a user-facing failure message, or null when the turn may
+   * run. A host driven without `start()` runs on the local login.
+   */
+  private credentialGateMessage;
   /** Stop admission, abort owned children, and give active turns time to settle. */
   stop(): Promise<void>;
   /**
@@ -2539,6 +2829,27 @@ declare class ClaudeCodeHost {
   private handleAgent;
   private deliverAgentOutcome;
   private runAgentTurn;
+  /**
+   * Send every message the memory service has not accepted yet. Indices are
+   * the messages' positions in the session file, so they advance across turns
+   * and survive host restarts; the per-conversation `ingestEpoch` tells the
+   * service when that index space restarted. Ingest under the BARE session
+   * id: the same key the session-store filename and the memory backfill use,
+   * so there is one memory lineage.
+   *
+   * Cursor rules:
+   * - success: advance through the batch. If the server trimmed the batch
+   *   (`messageCount` < sent) it kept the NEWEST messages and its watermark
+   *   moved past the dropped head, so a resend would be filtered anyway;
+   *   advance and warn. The byte bounds keep this path unreachable normally.
+   * - non-retryable 4xx (400/413/422): skip only the oldest message, so one
+   *   poison message cannot wedge the conversation.
+   * - anything else (429, 5xx, network): leave the cursor; the next turn
+   *   resends.
+   */
+  private ingestPendingMemory;
+  /** Regenerate CLAUDE.md from the workspace persona files. Never fatal. */
+  private syncPersona;
   /**
    * Run a turn; on a `--resume` failure (stale/missing claude session id) start
    * fresh and prepend the last-N stored messages so the model keeps context.
@@ -2559,45 +2870,6 @@ declare class ClaudeCodeHost {
 /** Strip the `agent:{agentId}:` prefix from a full server session key. */
 declare function stripAgentPrefix(sessionKey: string): string;
 //#endregion
-//#region src/child-env.d.ts
-/**
- * Child-process environment construction for spawned `claude` CLI processes.
- *
- * TWO non-negotiable invariants (Phase 2 plan, audit B2 + the hard
- * constraints):
- *
- * 1. **Scrub `ANTHROPIC_API_KEY` / `ANTHROPIC_BASE_URL` /
- *    `ANTHROPIC_AUTH_TOKEN`.** A self-hosted Mac very often has these set (for
- *    other tooling). If ANY of them reaches `claude`, the CLI silently switches
- *    from the user's Claude subscription (OAuth) to API-key/proxy auth — which
- *    is exactly what this whole runtime exists to avoid (no Agent SDK, no
- *    proxy, subscription only). The break is SILENT: the turn "works" but bills
- *    the wrong plane. So we strip them unconditionally from the child env.
- *
- * 2. **Set `ALFE_CLAUDE_BRIDGE=1`.** The Phase-1 CLI hooks
- *    (`alfe claude hook ...` in `packages/cli/src/commands/claude.ts`) check
- *    `process.env.ALFE_CLAUDE_BRIDGE` FIRST and no-op when set, so the host —
- *    not the interactive-session hooks — owns memory recall/capture for bridged
- *    turns. Omitting this double-captures every message. The env var NAME is a
- *    cross-phase contract; do not rename without updating the CLI.
- */
-/** Anthropic env vars that force API-key / proxy auth and MUST be scrubbed. */
-declare const SCRUBBED_ANTHROPIC_ENV_VARS: readonly ["ANTHROPIC_API_KEY", "ANTHROPIC_BASE_URL", "ANTHROPIC_AUTH_TOKEN"];
-/** Cross-phase contract marker (see header + packages/cli/src/commands/claude.ts). */
-declare const BRIDGE_ENV_VAR = "ALFE_CLAUDE_BRIDGE";
-/**
- * Build the env handed to a spawned `claude` child. Pure — takes the base env
- * explicitly so it unit-tests without touching `process.env`.
- *
- * - Every scrubbed Anthropic var is DELETED (not blanked) so `claude`'s
- *   env-detection treats it as absent.
- * - `ALFE_CLAUDE_BRIDGE=1` is set.
- * - Any caller-supplied `extra` entries are layered last (e.g. a per-turn
- *   marker) but can NEVER re-introduce a scrubbed var — the scrub runs after
- *   the merge as the final gate.
- */
-declare function buildChildEnv(base: NodeJS.ProcessEnv, extra?: Record<string, string>): NodeJS.ProcessEnv;
-//#endregion
 //#region src/session/session-store.d.ts
 type StoredMessageComponent = {
   type: 'link_button';
@@ -2677,7 +2949,25 @@ interface SessionData {
    * pre-persistence files.
    */
   activity?: ChatActivityRecord[];
+  /**
+   * Alfe memory ingest cursor. Message indices are POSITIONS in `messages`
+   * (append-only, never trimmed), so they are stable across host restarts and
+   * match the index space the memory backfill uses for these files.
+   * `ingestEpoch` is stamped once per conversation lineage (when this file is
+   * created) and tells the memory service the index space restarted, e.g.
+   * after the 30-day cleanup deleted the file and the conversation resumed.
+   * Absent on files written before the cursor existed.
+   */
+  memory?: SessionMemoryCursor;
+}
+interface SessionMemoryCursor {
+  /** Per-conversation-lineage epoch sent as `ingestEpoch`. */
+  ingestEpoch: number;
+  /** Highest message index the memory service has accepted (-1 = none). */
+  lastIngestedIndex: number;
 }
+/** One message as sent to `memoryIngest`. */
+
 interface SessionSummary {
   sessionId: string;
   agentId: string;
@@ -2692,7 +2982,20 @@ interface SessionSummary {
 declare function getSession(sessionId: string): Promise<SessionData | null>;
 declare function saveSession(session: SessionData): Promise<void>;
 declare function createSession(sessionId: string, agentId: string, channel: string, tenantId?: string, userId?: string): Promise<SessionData>;
-declare function addMessage(sessionId: string, role: 'user' | 'assistant', content: string, senderId?: string, senderName?: string, components?: StoredMessageComponent[], attachments?: StoredAttachment[]): Promise<void>;
+/**
+ * Append a message. Returns its index (position in `messages`), the stable
+ * memory-ingest index, or -1 when the session does not exist.
+ */
+declare function addMessage(sessionId: string, role: 'user' | 'assistant', content: string, senderId?: string, senderName?: string, components?: StoredMessageComponent[], attachments?: StoredAttachment[]): Promise<number>;
+/**
+ * Memory ingest bounds, in serialised UTF-8 bytes. The ingest endpoint
+ * forwards the whole body as ONE SQS message and trims the OLDEST messages
+ * past 250,000 bytes (`services/memory/api-agents/ingest/fit-batch.ts`); a
+ * trimmed head is lost for good because the consumer's watermark jumps past
+ * it. Staying well under that limit means the server never trims. Bytes, not
+ * characters: one CJK character is three UTF-8 bytes.
+ */
+
 /**
  * Append a turn's terminalized activity records. Called ONCE per turn (from the
  * dispatch `finally`) — never per-delta.
@@ -2712,4 +3015,4 @@ declare function listSessions(filters?: {
  */
 declare function resolveHostConfig(): ClaudeCodeHostConfig;
 //#endregion
-export { type ActivityEmission, BRIDGE_ENV_VAR, CLAUDE_PERMISSION_MODES, type ChatActivityRecord, type ChatMessage, ClaudeCodeHost, type ClaudeCodeHostConfig, type ClaudePermissionMode, DEFAULT_ALLOWED_TOOLS, DEFAULT_PERMISSION_MODE, type DriverTurnResult, type EndEmission, type MapperEmission, type MapperState, type RunTurnParams, SCRUBBED_ANTHROPIC_ENV_VARS, type SessionData, SessionDriver, type SessionSummary, TERMINATION_GRACE_MS, TURN_TIMEOUT_MS, type TextEmission, type ThinkingActivity, type ToolActivity, WARM_STREAMING_SUPPORTED, addMessage, appendActivity, buildChildEnv, collectTurnActivityRecords, createMapperState, createSession, getSession, listSessions, mapStreamEvent, mapStreamEvents, resolveHostConfig, saveSession, stripAgentPrefix };
+export { AUTH_PROBE_TIMEOUT_MS, type ActivityEmission, BRIDGE_ENV_VAR, CLAUDE_PERMISSION_MODES, CREDENTIAL_ENV_VAR, CREDENTIAL_INVALID_MESSAGE, CREDENTIAL_MISSING_MESSAGE, CREDENTIAL_UNAVAILABLE_MESSAGE, type ChatActivityRecord, type ChatMessage, type ChildCredential, ClaudeCodeHost, type ClaudeCodeHostConfig, type ClaudePermissionMode, type CredentialStatusReport, CredentialStatusReporter, DEFAULT_ALLOWED_TOOLS, DEFAULT_PERMISSION_MODE, type DriverTurnResult, type EndEmission, type HostCredential, LOCAL_LOGIN_FAILED_MESSAGE, MANAGED_ALLOWED_TOOLS, MANAGED_DISALLOWED_TOOLS, type MapperEmission, type MapperState, type ProbeOutcome, type RunTurnParams, SCRUBBED_ANTHROPIC_ENV_VARS, STATUS_REPORT_INTERVAL_MS, type SessionData, SessionDriver, type SessionSummary, TERMINATION_GRACE_MS, TURN_TIMEOUT_MS, type TextEmission, type ThinkingActivity, type ToolActivity, WARM_STREAMING_SUPPORTED, addMessage, appendActivity, buildChildEnv, buildProbeArgs, collectTurnActivityRecords, createMapperState, createSession, getSession, isAuthFailureText, listSessions, loadCredentialWithRetry, mapStreamEvent, mapStreamEvents, parseProbeOutput, resolveHostConfig, runAuthProbe, saveSession, stripAgentPrefix };