@alpacakit/agents 0.1.0-beta.39 → 0.2.0-beta.2

package/dist/core/session.js

@@ -0,0 +1,29 @@
+/**
+ * Session-plane vocabulary: a Session is one long-lived host conversation
+ * (Claude `-p --input-format stream-json` process, Codex app-server thread)
+ * that the caller keeps open across turns. One turn is one `send()`; the
+ * host's own conversation id is the Session id. Outbound types follow
+ * absence rule 2: keys always present, `null` is meaningful absence.
+ */
+export const SESSION_EVENT_TYPE = {
+    turnStarted: "turn_started",
+    turnEnded: "turn_ended",
+    message: "message",
+    tool: "tool",
+    approvalRequested: "approval_requested",
+    exited: "exited",
+};
+export const TURN_OUTCOME = {
+    completed: "completed",
+    interrupted: "interrupted",
+    failed: "failed",
+};
+/** The neutral answer to a host approval request; hosts map it to their own words. */
+export const APPROVAL_DECISION = {
+    accept: "accept",
+    decline: "decline",
+};
+export const SESSION_OWNER_KIND = {
+    none: "none",
+    process: "process",
+};

package/dist/host/session-files.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Read-only helpers over the files a host writes about its conversations
+ * (Claude transcripts and session registry, Codex rollouts and writer
+ * locks). Nothing here decides paths: callers build them from
+ * `HostContext.location.homeDir`, never from `os.homedir()`.
+ */
+import { type UnknownRecord } from "../core/json.js";
+export type FirstAndLast<T> = {
+    first: T | null;
+    last: T | null;
+};
+/** Directory entry names; a missing directory reads as empty, anything else surfaces. */
+export declare function readDirectoryNames(directory: string): Promise<string[]>;
+export declare function fileExists(target: string): Promise<boolean>;
+/** Parse one JSON file; `null` when it is absent or not a JSON object. */
+export declare function readJsonFile(target: string): Promise<UnknownRecord | null>;
+/**
+ * Stream a JSONL file once and keep the first and last non-null picks.
+ * Lines that are not JSON objects are skipped (hosts append other kinds).
+ */
+export declare function scanJsonlFirstLast<T>(file: string, pick: (record: UnknownRecord) => T | null): Promise<FirstAndLast<T>>;
+//# sourceMappingURL=session-files.d.ts.map

package/dist/host/session-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-files.d.ts","sourceRoot":"","sources":["../../src/host/session-files.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,OAAO,EAAkB,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAGrE,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI;IAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IAAC,IAAI,EAAE,CAAC,GAAG,IAAI,CAAA;CAAE,CAAC;AAYlE,yFAAyF;AACzF,wBAAsB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAS7E;AAED,wBAAsB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAUjE;AAED,0EAA0E;AAC1E,wBAAsB,YAAY,CAChC,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAW/B;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,EACxC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,CAAC,GAAG,IAAI,GACxC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAwB1B"}

package/dist/host/session-files.js

@@ -0,0 +1,91 @@
+/**
+ * Read-only helpers over the files a host writes about its conversations
+ * (Claude transcripts and session registry, Codex rollouts and writer
+ * locks). Nothing here decides paths: callers build them from
+ * `HostContext.location.homeDir`, never from `os.homedir()`.
+ */
+import { createReadStream } from "node:fs";
+import { access, readdir, readFile } from "node:fs/promises";
+import { createInterface } from "node:readline";
+import { AGENT_ERROR_CODE, AgentError } from "../core/error.js";
+import { isErrnoCode } from "../core/fs.js";
+import { readJsonRecord } from "../core/json.js";
+import { TEXT_ENCODING } from "../core/values.js";
+function hostFileReadError(target, cause) {
+    return new AgentError({
+        code: AGENT_ERROR_CODE.failed,
+        classification: AgentError.agentFailure(AGENT_ERROR_CODE.failed),
+        message: `Could not read host session file: ${target}`,
+        data: { exitCode: null, stdoutTail: null, stderrTail: null },
+        cause,
+    });
+}
+/** Directory entry names; a missing directory reads as empty, anything else surfaces. */
+export async function readDirectoryNames(directory) {
+    try {
+        return await readdir(directory);
+    }
+    catch (error) {
+        if (isErrnoCode(error, "ENOENT") || isErrnoCode(error, "ENOTDIR")) {
+            return [];
+        }
+        throw hostFileReadError(directory, error);
+    }
+}
+export async function fileExists(target) {
+    try {
+        await access(target);
+        return true;
+    }
+    catch (error) {
+        if (isErrnoCode(error, "ENOENT") || isErrnoCode(error, "ENOTDIR")) {
+            return false;
+        }
+        throw hostFileReadError(target, error);
+    }
+}
+/** Parse one JSON file; `null` when it is absent or not a JSON object. */
+export async function readJsonFile(target) {
+    let text;
+    try {
+        text = await readFile(target, TEXT_ENCODING);
+    }
+    catch (error) {
+        if (isErrnoCode(error, "ENOENT") || isErrnoCode(error, "ENOTDIR")) {
+            return null;
+        }
+        throw hostFileReadError(target, error);
+    }
+    return readJsonRecord(text.trim());
+}
+/**
+ * Stream a JSONL file once and keep the first and last non-null picks.
+ * Lines that are not JSON objects are skipped (hosts append other kinds).
+ */
+export async function scanJsonlFirstLast(file, pick) {
+    const result = { first: null, last: null };
+    const stream = createReadStream(file, { encoding: TEXT_ENCODING });
+    const lines = createInterface({ input: stream, crlfDelay: Infinity });
+    try {
+        for await (const line of lines) {
+            const record = readJsonRecord(line.trim());
+            if (record === null) {
+                continue;
+            }
+            const picked = pick(record);
+            if (picked === null) {
+                continue;
+            }
+            result.first ??= picked;
+            result.last = picked;
+        }
+    }
+    catch (error) {
+        throw hostFileReadError(file, error);
+    }
+    finally {
+        lines.close();
+        stream.destroy();
+    }
+    return result;
+}

package/dist/index.d.ts

@@ -9,7 +9,9 @@
  */
 export { BUILTIN_AGENT_ID, type BuiltinAgentId, builtinAgentFactories, } from "./agents/builtin.js";
 export { claude, type ClaudeOptions, structuredQuotaMatcher, } from "./agents/claude.js";
+export { CLAUDE_PERMISSION_MODE, type ClaudePermissionMode, type ClaudeSessionPermissions, } from "./agents/claude-session.js";
 export { capacityTextMatcher, codex } from "./agents/codex.js";
+export { CODEX_APPROVAL_POLICY, CODEX_APPROVALS_REVIEWER, type CodexApprovalPolicy, type CodexApprovalsReviewer, type CodexSandboxMode, type CodexSandboxPolicy, type CodexSessionPermissions, } from "./agents/codex-session.js";
 export type { PiSessionEngineOptions } from "./agents/openai-compatible/pi/engine.js";
 export { PI_DEFAULT_CONTEXT_WINDOW, PI_DEFAULT_MAX_TOKENS, piSessionEngine, } from "./agents/openai-compatible/pi/engine.js";
 export type { JsonValue, OpenAiCompatibleConfig, OpenAiCompatibleConfigInput, OpenAiCompatibleEngine, } from "./agents/openai-compatible.js";
@@ -22,6 +24,8 @@ export { envResolver, requireSecret } from "./auth/secrets.js";
 export type { ChildProcessAbsenceProof, ChildProcessCompletion, ChildProcessIdentity, ChildProcessLifecycle, ChildProcessTerminationEvidence, ChildProcessTerminationPhase, ChildProcessTerminationResult, ChildProcessUnkillableReason, ControlledExec, ControlledExecOptions, ControlledExecProcess, ControlledProcessRecovery, } from "./core/controlled-process.js";
 export { CHILD_PROCESS_ABSENCE_PROOF, CHILD_PROCESS_TERMINATION_EVIDENCE_KIND, CHILD_PROCESS_TERMINATION_KIND, CHILD_PROCESS_TERMINATION_PHASE, CHILD_PROCESS_UNKILLABLE_REASON, } from "./core/controlled-process.js";
 export type { EnvPatch } from "./core/env.js";
+export type { ApprovalDecision, Session, SessionEvent, SessionFacts, SessionOwner, TurnOutcome, TurnResult, } from "./core/session.js";
+export { APPROVAL_DECISION, SESSION_EVENT_TYPE, SESSION_OWNER_KIND, TURN_OUTCOME, } from "./core/session.js";
 export { applyEnvPatch, EMPTY_ENV_PATCH, mergeEnvPatches, processEnv, } from "./core/env.js";
 export type { AgentErrorCode, AgentErrorData, AgentErrorOptions, AgentFailure, AgentFailureClass, AgentFailureCode, AgentInfrastructureFailureCode, AuthFailureReason, ControlledProcessLaunchFailureCode, ControlledProcessLaunchFailureData, ControlledProcessLaunchFailureRetryability, GuardViolation, Issue, NotAvailableCause, TimeoutKind, } from "./core/error.js";
 export { AGENT_ERROR_CODE, AGENT_FAILURE_CLASS, AGENT_INFRASTRUCTURE_FAILURE_CODE, AgentError, AUTH_FAILURE_REASON, agentFailure, CONTROLLED_PROCESS_LAUNCH_FAILURE_CODE, CONTROLLED_PROCESS_LAUNCH_FAILURE_RETRYABILITY, infrastructureFailure, isAgentError, NOT_AVAILABLE_CAUSE, TIMEOUT_KIND, } from "./core/error.js";
@@ -53,17 +57,18 @@ export type { ClassifiedFailure, FailureEvidence, FailureMatcher, } from "./kern
 export { authIf, capacityIf, classifyFailure, parseCooldownHint, quotaIf, sharedFailureMatchers, } from "./kernel/classify.js";
 export type { ArgContext, CliAgentBlueprint, CliResultCapture, OutputState, SandboxArgBuilders, } from "./kernel/cli-agent.js";
 export { defineCliAgent } from "./kernel/cli-agent.js";
-export type { AgentDefinition, AgentRun, RunContext, } from "./kernel/definition.js";
+export type { AgentDefinition, AgentRun, RunContext, SessionPermissionsOf, } from "./kernel/definition.js";
 export { defineAgent } from "./kernel/definition.js";
 export type { EnvTemplate, EnvTemplateResolution, } from "./kernel/env-template.js";
 export { referencedEnvNames, resolveEnvTemplate, } from "./kernel/env-template.js";
-export type { AgentAuth, AgentAvailabilityProbe, AgentDoctor, AgentLogin, AgentMcp, AgentSkills, } from "./kernel/facets.js";
+export type { AgentAuth, AgentAvailabilityProbe, AgentDoctor, AgentLogin, AgentMcp, AgentSessions, AgentSkills, SessionOpenOptions, SessionResumeOptions, } from "./kernel/facets.js";
 export type { Guard, GuardContext, GuardFactory } from "./kernel/guard.js";
 export { maxToolCalls, maxTurns, noProgress, repeatedOutput, } from "./kernel/guard.js";
 export type { ControlledChildProcessResource, Grant, Limits, ResolvedLimits, ResolvedRunOptions, ResolvedRunResources, ResolvedSandbox, RunOptions, RunResources, Sandbox, SandboxMode, } from "./kernel/options.js";
 export { GRANT_KIND, SANDBOX_MODE } from "./kernel/options.js";
 export type { Agent, AgentRuntime, AgentRuntimeOptions, } from "./kernel/runtime.js";
 export { createAgentRuntime, resolvePorts } from "./kernel/runtime.js";
+export type { ResolvedSessionOpenOptions, ResolvedSessionResumeOptions, SessionCapability, SessionContext, } from "./kernel/session.js";
 export { type RunAgentOptions, runAgent } from "./run-agent.js";
 export type { ExtractionStrategy, JsonParseOutcome, Markers, } from "./structured/extract.js";
 export { DEFAULT_MARKERS, defaultExtractionStrategies, extractBlock, parseJsonResilient, } from "./structured/extract.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,gBAAgB,EAChB,KAAK,cAAc,EACnB,qBAAqB,GACtB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,MAAM,EACN,KAAK,aAAa,EAClB,sBAAsB,GACvB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,mBAAmB,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC/D,YAAY,EAAE,sBAAsB,EAAE,MAAM,yCAAyC,CAAC;AACtF,OAAO,EACL,yBAAyB,EACzB,qBAAqB,EACrB,eAAe,GAChB,MAAM,yCAAyC,CAAC;AACjD,YAAY,EACV,SAAS,EACT,sBAAsB,EACtB,2BAA2B,EAC3B,sBAAsB,GACvB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,YAAY,EACV,eAAe,EACf,YAAY,EACZ,UAAU,EACV,WAAW,EACX,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,QAAQ,GACT,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACjE,YAAY,EACV,oBAAoB,EACpB,cAAc,EACd,YAAY,EACZ,sBAAsB,EACtB,gBAAgB,EAChB,WAAW,EACX,UAAU,EACV,qBAAqB,EACrB,eAAe,EACf,gBAAgB,EAChB,SAAS,GACV,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,kBAAkB,EAClB,WAAW,EACX,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAC/D,YAAY,EACV,wBAAwB,EACxB,sBAAsB,EACtB,oBAAoB,EACpB,qBAAqB,EACrB,+BAA+B,EAC/B,4BAA4B,EAC5B,6BAA6B,EAC7B,4BAA4B,EAC5B,cAAc,EACd,qBAAqB,EACrB,qBAAqB,EACrB,yBAAyB,GAC1B,MAAM,8BAA8B,CAAC;AACtC,OAAO,EACL,2BAA2B,EAC3B,uCAAuC,EACvC,8BAA8B,EAC9B,+BAA+B,EAC/B,+BAA+B,GAChC,MAAM,8BAA8B,CAAC;AACtC,YAAY,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EACL,aAAa,EACb,eAAe,EACf,eAAe,EACf,UAAU,GACX,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,YAAY,EACZ,iBAAiB,EACjB,gBAAgB,EAChB,8BAA8B,EAC9B,iBAAiB,EACjB,kCAAkC,EAClC,kCAAkC,EAClC,0CAA0C,EAC1C,cAAc,EACd,KAAK,EACL,iBAAiB,EACjB,WAAW,GACZ,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,iCAAiC,EACjC,UAAU,EACV,mBAAmB,EACnB,YAAY,EACZ,sCAAsC,EACtC,8CAA8C,EAC9C,qBAAqB,EACrB,YAAY,EACZ,mBAAmB,EACnB,YAAY,GACb,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AACtE,YAAY,EACV,KAAK,EACL,IAAI,EACJ,SAAS,EACT,QAAQ,EACR,WAAW,EACX,gBAAgB,EAChB,UAAU,EACV,sBAAsB,EACtB,2BAA2B,EAC3B,MAAM,EACN,QAAQ,EACR,KAAK,EACL,cAAc,EACd,eAAe,EACf,aAAa,GACd,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACpE,YAAY,EACV,UAAU,EACV,eAAe,EACf,aAAa,EACb,QAAQ,EACR,OAAO,EACP,SAAS,EACT,SAAS,EACT,YAAY,EACZ,SAAS,EACT,QAAQ,GACT,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,cAAc,EACd,WAAW,GACZ,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElE,YAAY,EACV,qBAAqB,EACrB,4BAA4B,GAC7B,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,2BAA2B,EAAE,MAAM,4BAA4B,CAAC;AAEzE,YAAY,EACV,aAAa,EACb,YAAY,EACZ,OAAO,EACP,aAAa,EACb,SAAS,EACT,gBAAgB,EAChB,kBAAkB,EAClB,KAAK,EACL,sBAAsB,EACtB,YAAY,EACZ,kBAAkB,EAClB,oBAAoB,EACpB,eAAe,EACf,yBAAyB,GAC1B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,oBAAoB,EACpB,YAAY,EACZ,WAAW,EACX,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,aAAa,EACb,UAAU,GACX,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,4BAA4B,EAC5B,cAAc,EACd,oBAAoB,EACpB,mBAAmB,EACnB,yBAAyB,GAC1B,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpE,YAAY,EACV,iBAAiB,EACjB,2BAA2B,EAC3B,gBAAgB,GACjB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,yBAAyB,EACzB,0BAA0B,EAC1B,wBAAwB,EACxB,2CAA2C,GAC5C,MAAM,wBAAwB,CAAC;AAChC,YAAY,EACV,gBAAgB,EAChB,WAAW,EACX,YAAY,EACZ,cAAc,EACd,cAAc,EACd,cAAc,EACd,eAAe,EACf,aAAa,EACb,QAAQ,EACR,aAAa,EACb,cAAc,EACd,YAAY,EACZ,iBAAiB,EACjB,WAAW,EACX,eAAe,EACf,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,8BAA8B,EAC9B,oBAAoB,EACpB,sBAAsB,EACtB,mBAAmB,EACnB,cAAc,EACd,SAAS,EACT,aAAa,EACb,iBAAiB,GAClB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACnE,YAAY,EACV,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAE9D,YAAY,EACV,iBAAiB,EACjB,eAAe,EACf,cAAc,GACf,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,MAAM,EACN,UAAU,EACV,eAAe,EACf,iBAAiB,EACjB,OAAO,EACP,qBAAqB,GACtB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,UAAU,EACV,iBAAiB,EACjB,gBAAgB,EAChB,WAAW,EACX,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,YAAY,EACV,eAAe,EACf,QAAQ,EACR,UAAU,GACX,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,YAAY,EACV,WAAW,EACX,qBAAqB,GACtB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EACV,SAAS,EACT,sBAAsB,EACtB,WAAW,EACX,UAAU,EACV,QAAQ,EACR,WAAW,GACZ,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC3E,OAAO,EACL,YAAY,EACZ,QAAQ,EACR,UAAU,EACV,cAAc,GACf,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,8BAA8B,EAC9B,KAAK,EACL,MAAM,EACN,cAAc,EACd,kBAAkB,EAClB,oBAAoB,EACpB,eAAe,EACf,UAAU,EACV,YAAY,EACZ,OAAO,EACP,WAAW,GACZ,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAC/D,YAAY,EACV,KAAK,EACL,YAAY,EACZ,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEvE,OAAO,EAAE,KAAK,eAAe,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAEhE,YAAY,EACV,kBAAkB,EAClB,gBAAgB,EAChB,OAAO,GACR,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,eAAe,EACf,2BAA2B,EAC3B,YAAY,EACZ,kBAAkB,GACnB,MAAM,yBAAyB,CAAC;AACjC,YAAY,EACV,uBAAuB,EACvB,cAAc,EACd,YAAY,EACZ,aAAa,EACb,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAC3E,YAAY,EACV,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,iCAAiC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,gBAAgB,EAChB,KAAK,cAAc,EACnB,qBAAqB,GACtB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,MAAM,EACN,KAAK,aAAa,EAClB,sBAAsB,GACvB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,sBAAsB,EACtB,KAAK,oBAAoB,EACzB,KAAK,wBAAwB,GAC9B,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,mBAAmB,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,GAC7B,MAAM,2BAA2B,CAAC;AACnC,YAAY,EAAE,sBAAsB,EAAE,MAAM,yCAAyC,CAAC;AACtF,OAAO,EACL,yBAAyB,EACzB,qBAAqB,EACrB,eAAe,GAChB,MAAM,yCAAyC,CAAC;AACjD,YAAY,EACV,SAAS,EACT,sBAAsB,EACtB,2BAA2B,EAC3B,sBAAsB,GACvB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,YAAY,EACV,eAAe,EACf,YAAY,EACZ,UAAU,EACV,WAAW,EACX,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,QAAQ,GACT,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACjE,YAAY,EACV,oBAAoB,EACpB,cAAc,EACd,YAAY,EACZ,sBAAsB,EACtB,gBAAgB,EAChB,WAAW,EACX,UAAU,EACV,qBAAqB,EACrB,eAAe,EACf,gBAAgB,EAChB,SAAS,GACV,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,kBAAkB,EAClB,WAAW,EACX,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAC/D,YAAY,EACV,wBAAwB,EACxB,sBAAsB,EACtB,oBAAoB,EACpB,qBAAqB,EACrB,+BAA+B,EAC/B,4BAA4B,EAC5B,6BAA6B,EAC7B,4BAA4B,EAC5B,cAAc,EACd,qBAAqB,EACrB,qBAAqB,EACrB,yBAAyB,GAC1B,MAAM,8BAA8B,CAAC;AACtC,OAAO,EACL,2BAA2B,EAC3B,uCAAuC,EACvC,8BAA8B,EAC9B,+BAA+B,EAC/B,+BAA+B,GAChC,MAAM,8BAA8B,CAAC;AACtC,YAAY,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,YAAY,EACV,gBAAgB,EAChB,OAAO,EACP,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,UAAU,GACX,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,YAAY,GACb,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,aAAa,EACb,eAAe,EACf,eAAe,EACf,UAAU,GACX,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,YAAY,EACZ,iBAAiB,EACjB,gBAAgB,EAChB,8BAA8B,EAC9B,iBAAiB,EACjB,kCAAkC,EAClC,kCAAkC,EAClC,0CAA0C,EAC1C,cAAc,EACd,KAAK,EACL,iBAAiB,EACjB,WAAW,GACZ,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,iCAAiC,EACjC,UAAU,EACV,mBAAmB,EACnB,YAAY,EACZ,sCAAsC,EACtC,8CAA8C,EAC9C,qBAAqB,EACrB,YAAY,EACZ,mBAAmB,EACnB,YAAY,GACb,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AACtE,YAAY,EACV,KAAK,EACL,IAAI,EACJ,SAAS,EACT,QAAQ,EACR,WAAW,EACX,gBAAgB,EAChB,UAAU,EACV,sBAAsB,EACtB,2BAA2B,EAC3B,MAAM,EACN,QAAQ,EACR,KAAK,EACL,cAAc,EACd,eAAe,EACf,aAAa,GACd,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACpE,YAAY,EACV,UAAU,EACV,eAAe,EACf,aAAa,EACb,QAAQ,EACR,OAAO,EACP,SAAS,EACT,SAAS,EACT,YAAY,EACZ,SAAS,EACT,QAAQ,GACT,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,cAAc,EACd,WAAW,GACZ,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElE,YAAY,EACV,qBAAqB,EACrB,4BAA4B,GAC7B,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,2BAA2B,EAAE,MAAM,4BAA4B,CAAC;AAEzE,YAAY,EACV,aAAa,EACb,YAAY,EACZ,OAAO,EACP,aAAa,EACb,SAAS,EACT,gBAAgB,EAChB,kBAAkB,EAClB,KAAK,EACL,sBAAsB,EACtB,YAAY,EACZ,kBAAkB,EAClB,oBAAoB,EACpB,eAAe,EACf,yBAAyB,GAC1B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,oBAAoB,EACpB,YAAY,EACZ,WAAW,EACX,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,aAAa,EACb,UAAU,GACX,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,4BAA4B,EAC5B,cAAc,EACd,oBAAoB,EACpB,mBAAmB,EACnB,yBAAyB,GAC1B,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpE,YAAY,EACV,iBAAiB,EACjB,2BAA2B,EAC3B,gBAAgB,GACjB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,yBAAyB,EACzB,0BAA0B,EAC1B,wBAAwB,EACxB,2CAA2C,GAC5C,MAAM,wBAAwB,CAAC;AAChC,YAAY,EACV,gBAAgB,EAChB,WAAW,EACX,YAAY,EACZ,cAAc,EACd,cAAc,EACd,cAAc,EACd,eAAe,EACf,aAAa,EACb,QAAQ,EACR,aAAa,EACb,cAAc,EACd,YAAY,EACZ,iBAAiB,EACjB,WAAW,EACX,eAAe,EACf,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,8BAA8B,EAC9B,oBAAoB,EACpB,sBAAsB,EACtB,mBAAmB,EACnB,cAAc,EACd,SAAS,EACT,aAAa,EACb,iBAAiB,GAClB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACnE,YAAY,EACV,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAE9D,YAAY,EACV,iBAAiB,EACjB,eAAe,EACf,cAAc,GACf,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,MAAM,EACN,UAAU,EACV,eAAe,EACf,iBAAiB,EACjB,OAAO,EACP,qBAAqB,GACtB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,UAAU,EACV,iBAAiB,EACjB,gBAAgB,EAChB,WAAW,EACX,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,YAAY,EACV,eAAe,EACf,QAAQ,EACR,UAAU,EACV,oBAAoB,GACrB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,YAAY,EACV,WAAW,EACX,qBAAqB,GACtB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EACV,SAAS,EACT,sBAAsB,EACtB,WAAW,EACX,UAAU,EACV,QAAQ,EACR,aAAa,EACb,WAAW,EACX,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC3E,OAAO,EACL,YAAY,EACZ,QAAQ,EACR,UAAU,EACV,cAAc,GACf,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,8BAA8B,EAC9B,KAAK,EACL,MAAM,EACN,cAAc,EACd,kBAAkB,EAClB,oBAAoB,EACpB,eAAe,EACf,UAAU,EACV,YAAY,EACZ,OAAO,EACP,WAAW,GACZ,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAC/D,YAAY,EACV,KAAK,EACL,YAAY,EACZ,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACvE,YAAY,EACV,0BAA0B,EAC1B,4BAA4B,EAC5B,iBAAiB,EACjB,cAAc,GACf,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,KAAK,eAAe,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAEhE,YAAY,EACV,kBAAkB,EAClB,gBAAgB,EAChB,OAAO,GACR,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,eAAe,EACf,2BAA2B,EAC3B,YAAY,EACZ,kBAAkB,GACnB,MAAM,yBAAyB,CAAC;AACjC,YAAY,EACV,uBAAuB,EACvB,cAAc,EACd,YAAY,EACZ,aAAa,EACb,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAC3E,YAAY,EACV,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,iCAAiC,CAAC"}

package/dist/index.js

@@ -9,13 +9,16 @@
  */
 export { BUILTIN_AGENT_ID, builtinAgentFactories, } from "./agents/builtin.js";
 export { claude, structuredQuotaMatcher, } from "./agents/claude.js";
+export { CLAUDE_PERMISSION_MODE, } from "./agents/claude-session.js";
 export { capacityTextMatcher, codex } from "./agents/codex.js";
+export { CODEX_APPROVAL_POLICY, CODEX_APPROVALS_REVIEWER, } from "./agents/codex-session.js";
 export { PI_DEFAULT_CONTEXT_WINDOW, PI_DEFAULT_MAX_TOKENS, piSessionEngine, } from "./agents/openai-compatible/pi/engine.js";
 export { openaiCompatible } from "./agents/openai-compatible.js";
 export { LOGIN_EVENT_TYPE, LOGIN_METHOD } from "./auth/login.js";
 export { AUTH_MATERIAL_KIND, AUTH_STATUS, createApiKeyProfile, createHomeDirProfile, envVarAuthMaterial, } from "./auth/material.js";
 export { envResolver, requireSecret } from "./auth/secrets.js";
 export { CHILD_PROCESS_ABSENCE_PROOF, CHILD_PROCESS_TERMINATION_EVIDENCE_KIND, CHILD_PROCESS_TERMINATION_KIND, CHILD_PROCESS_TERMINATION_PHASE, CHILD_PROCESS_UNKILLABLE_REASON, } from "./core/controlled-process.js";
+export { APPROVAL_DECISION, SESSION_EVENT_TYPE, SESSION_OWNER_KIND, TURN_OUTCOME, } from "./core/session.js";
 export { applyEnvPatch, EMPTY_ENV_PATCH, mergeEnvPatches, processEnv, } from "./core/env.js";
 export { AGENT_ERROR_CODE, AGENT_FAILURE_CLASS, AGENT_INFRASTRUCTURE_FAILURE_CODE, AgentError, AUTH_FAILURE_REASON, agentFailure, CONTROLLED_PROCESS_LAUNCH_FAILURE_CODE, CONTROLLED_PROCESS_LAUNCH_FAILURE_RETRYABILITY, infrastructureFailure, isAgentError, NOT_AVAILABLE_CAUSE, TIMEOUT_KIND, } from "./core/error.js";
 export { createControlledExec } from "./core/node-controlled-exec.js";

package/dist/internal/controlled-process/supervisor-runtime.js

@@ -368,7 +368,28 @@ async function runSupervisorSession(input) {
         await runCoordinatorOperation(async (current) => current.acknowledge());
         coordinatorAckMayHaveCommitted = true;
         await input.dependencies.writeShimAck(shimControl);
-        const [inputRelaySettlement, shimReadySettlement] = await Promise.allSettled([inputRelay, shimReady]);
+        // The relay deadline is the supervisor's own decision: when it elapses
+        // before the shim has failed, it cuts the shim's input, and the early
+        // EOF the shim then reports is a consequence (seen on slow CI while the
+        // shim was still starting). Every other relay failure is itself a
+        // consequence of the shim side (a worker exit closes the pipe), so the
+        // shim's report keeps precedence there.
+        let firstFailure = null;
+        const [inputRelaySettlement, shimReadySettlement] = await Promise.allSettled([
+            inputRelay.catch((error) => {
+                firstFailure ??= "relay";
+                throw error;
+            }),
+            shimReady.catch((error) => {
+                firstFailure ??= "shim";
+                throw error;
+            }),
+        ]);
+        if (inputRelaySettlement.status === "rejected" &&
+            firstFailure === "relay" &&
+            isInputTransferTimeout(inputRelaySettlement.reason)) {
+            throw inputRelaySettlement.reason;
+        }
         if (shimReadySettlement.status === "rejected") {
             throw shimReadySettlement.reason;
         }
@@ -944,3 +965,8 @@ async function selfSigkill() {
 function randomHex(bytes) {
     return randomBytes(bytes).toString("hex");
 }
+function isInputTransferTimeout(error) {
+    return (error instanceof ControlledProcessLaunchError &&
+        error.failure.code ===
+            CONTROLLED_PROCESS_LAUNCH_FAILURE_CODE.inputTransferTimeout);
+}

package/dist/kernel/definition.d.ts

@@ -11,6 +11,7 @@ import type { AgentEvent, AgentRunOutcome } from "../core/run.js";
 import type { AgentAvailabilityCapability } from "../host/availability.js";
 import type { DoctorCapability, McpCapability, SkillsCapability } from "../host/capabilities.js";
 import type { ResolvedRunOptions } from "./options.js";
+import type { SessionCapability } from "./session.js";
 /** Resolved (rule 2): the adapter's whole world. */
 export type RunContext = {
     /** The ONE stop channel — caller abort, timeout, and guard violations. */
@@ -25,7 +26,12 @@ export type RunContext = {
     logger: Logger;
 };
 export type AgentRun = AsyncGenerator<AgentEvent, AgentRunOutcome, void>;
-export interface AgentDefinition<Id extends string = string> {
+/**
+ * `SessionPermissions` is the host-specific permission shape a session is
+ * opened with (`ClaudeSessionPermissions`, `CodexSessionPermissions`); it
+ * stays a type parameter so the neutral `Sandbox` never learns host words.
+ */
+export interface AgentDefinition<Id extends string = string, SessionPermissions = unknown> {
     id: Id;
     run(options: ResolvedRunOptions, ctx: RunContext): AgentRun;
     availability?: AgentAvailabilityCapability;
@@ -34,10 +40,13 @@ export interface AgentDefinition<Id extends string = string> {
     doctor?: DoctorCapability;
     skills?: SkillsCapability;
     mcp?: McpCapability;
+    session?: SessionCapability<SessionPermissions>;
 }
+/** The session permission type a definition declares (`unknown` when it has no session facet). */
+export type SessionPermissionsOf<Definition> = Definition extends AgentDefinition<string, infer Permissions> ? Permissions : unknown;
 /**
  * Identity helper for hand-rolled agents: pins the `Id` literal and
  * type-checks the definition in place. No runtime behavior.
  */
-export declare function defineAgent<const Id extends string>(definition: AgentDefinition<Id>): AgentDefinition<Id>;
+export declare function defineAgent<const Id extends string, SessionPermissions = unknown>(definition: AgentDefinition<Id, SessionPermissions>): AgentDefinition<Id, SessionPermissions>;
 //# sourceMappingURL=definition.d.ts.map

package/dist/kernel/definition.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"definition.d.ts","sourceRoot":"","sources":["../../src/kernel/definition.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AACxE,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,yBAAyB,CAAC;AAC3E,OAAO,KAAK,EACV,gBAAgB,EAChB,aAAa,EACb,gBAAgB,EACjB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEvD,oDAAoD;AACpD,MAAM,MAAM,UAAU,GAAG;IACvB,0EAA0E;IAC1E,MAAM,EAAE,WAAW,CAAC;IACpB,yDAAyD;IACzD,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,IAAI,EAAE,IAAI,CAAC;IACX,IAAI,EAAE,UAAU,CAAC;IACjB,2EAA2E;IAC3E,KAAK,EAAE,KAAK,CAAC;IACb,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG,cAAc,CAAC,UAAU,EAAE,eAAe,EAAE,IAAI,CAAC,CAAC;AAEzE,MAAM,WAAW,eAAe,CAAC,EAAE,SAAS,MAAM,GAAG,MAAM;IACzD,EAAE,EAAE,EAAE,CAAC;IACP,GAAG,CAAC,OAAO,EAAE,kBAAkB,EAAE,GAAG,EAAE,UAAU,GAAG,QAAQ,CAAC;IAC5D,YAAY,CAAC,EAAE,2BAA2B,CAAC;IAC3C,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,GAAG,CAAC,EAAE,aAAa,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EACjD,UAAU,EAAE,eAAe,CAAC,EAAE,CAAC,GAC9B,eAAe,CAAC,EAAE,CAAC,CAErB"}
+{"version":3,"file":"definition.d.ts","sourceRoot":"","sources":["../../src/kernel/definition.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AACxE,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,yBAAyB,CAAC;AAC3E,OAAO,KAAK,EACV,gBAAgB,EAChB,aAAa,EACb,gBAAgB,EACjB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEtD,oDAAoD;AACpD,MAAM,MAAM,UAAU,GAAG;IACvB,0EAA0E;IAC1E,MAAM,EAAE,WAAW,CAAC;IACpB,yDAAyD;IACzD,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,IAAI,EAAE,IAAI,CAAC;IACX,IAAI,EAAE,UAAU,CAAC;IACjB,2EAA2E;IAC3E,KAAK,EAAE,KAAK,CAAC;IACb,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG,cAAc,CAAC,UAAU,EAAE,eAAe,EAAE,IAAI,CAAC,CAAC;AAEzE;;;;GAIG;AACH,MAAM,WAAW,eAAe,CAC9B,EAAE,SAAS,MAAM,GAAG,MAAM,EAC1B,kBAAkB,GAAG,OAAO;IAE5B,EAAE,EAAE,EAAE,CAAC;IACP,GAAG,CAAC,OAAO,EAAE,kBAAkB,EAAE,GAAG,EAAE,UAAU,GAAG,QAAQ,CAAC;IAC5D,YAAY,CAAC,EAAE,2BAA2B,CAAC;IAC3C,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,GAAG,CAAC,EAAE,aAAa,CAAC;IACpB,OAAO,CAAC,EAAE,iBAAiB,CAAC,kBAAkB,CAAC,CAAC;CACjD;AAED,kGAAkG;AAClG,MAAM,MAAM,oBAAoB,CAAC,UAAU,IACzC,UAAU,SAAS,eAAe,CAAC,MAAM,EAAE,MAAM,WAAW,CAAC,GACzD,WAAW,GACX,OAAO,CAAC;AAEd;;;GAGG;AACH,wBAAgB,WAAW,CACzB,KAAK,CAAC,EAAE,SAAS,MAAM,EACvB,kBAAkB,GAAG,OAAO,EAE5B,UAAU,EAAE,eAAe,CAAC,EAAE,EAAE,kBAAkB,CAAC,GAClD,eAAe,CAAC,EAAE,EAAE,kBAAkB,CAAC,CAEzC"}

package/dist/kernel/facets.d.ts

@@ -6,11 +6,13 @@
  */
 import { type LoginCapability, type LoginHandle, type LoginMethod, type LoginRequest } from "../auth/login.js";
 import type { AuthCapability, AuthMaterial, AuthMaterialDescriptor, AuthMaterialKind, AuthStatus } from "../auth/material.js";
-import type { EnvPatch } from "../core/env.js";
+import { type EnvPatch } from "../core/env.js";
 import type { Clock, Exec, HttpClient, Logger, SecretResolvers } from "../core/ports.js";
 import type { AgentAvailability, AgentAvailabilityCapability } from "../host/availability.js";
 import type { DoctorCapability, DoctorReport, InstalledSkill, InstallOptions, InstallOutcome, McpCapability, McpScope, McpServerSpec, McpServerState, SkillSource, SkillsCapability } from "../host/capabilities.js";
+import type { Session, SessionFacts } from "../core/session.js";
 import type { HostLocation } from "../host/context.js";
+import type { SessionCapability } from "./session.js";
 export type AgentAuth = {
     supports(kind: AuthMaterialKind): boolean;
     /** Supported material kinds in canonical order (empty if none). */
@@ -45,6 +47,40 @@ export type AgentMcp = {
         scope: McpScope;
     }): Promise<void>;
 };
+/** Call-site input (rule 1): `env` patches the runtime's base environment. */
+export type SessionOpenOptions<Permissions> = {
+    workspace: string;
+    permissions: Permissions;
+    env?: EnvPatch;
+};
+export type SessionResumeOptions<Permissions> = SessionOpenOptions<Permissions> & {
+    /**
+     * Codex only (Claude has no archive): when `true`, an archived thread is
+     * `thread/unarchive`d before `thread/resume`, which also moves it back into
+     * the ChatGPT app's active list. Default `false`: resuming an archived
+     * thread fails with the server's "is archived" message; check
+     * `inspect(id).archived` first.
+     */
+    unarchive?: boolean;
+};
+export type AgentSessions<Permissions> = {
+    /**
+     * Start a new conversation in `workspace`. Codex note: `thread/start`
+     * with a writable sandbox (`workspace-write`, `danger-full-access`) makes
+     * Codex append a `trust_level` entry for the workspace to
+     * `~/.codex/config.toml`; `read-only` does not (T53/T57, codex 0.153.4).
+     */
+    open(options: SessionOpenOptions<Permissions>): Promise<Session>;
+    /**
+     * Take over an existing conversation by the host's id. Permissions are
+     * always passed explicitly — hosts do not reliably restore the original
+     * ones (Codex `thread/resume` without `sandbox` ran as danger-full-access).
+     * An archived Codex thread is unarchived only when `unarchive: true`.
+     */
+    resume(id: string, options: SessionResumeOptions<Permissions>): Promise<Session>;
+    /** Read the host's own files about a conversation; `null` when it has none. */
+    inspect(id: string, location: HostLocation): Promise<SessionFacts<Permissions> | null>;
+};
 export type FacetBinding = {
     agentId: string;
     env: Record<string, string>;
@@ -59,5 +95,6 @@ export declare function bindAvailability(capability: AgentAvailabilityCapability
 export declare function bindLogin(capability: LoginCapability, binding: FacetBinding): AgentLogin;
 export declare function bindDoctor(capability: DoctorCapability, binding: FacetBinding): AgentDoctor;
 export declare function bindSkills(capability: SkillsCapability, binding: FacetBinding): AgentSkills;
+export declare function bindSessions<Permissions>(capability: SessionCapability<Permissions>, binding: FacetBinding): AgentSessions<Permissions>;
 export declare function bindMcp(capability: McpCapability, binding: FacetBinding): AgentMcp;
 //# sourceMappingURL=facets.d.ts.map

package/dist/kernel/facets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"facets.d.ts","sourceRoot":"","sources":["../../src/kernel/facets.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,WAAW,EAEhB,KAAK,WAAW,EAChB,KAAK,YAAY,EAClB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EACV,cAAc,EACd,YAAY,EACZ,sBAAsB,EACtB,gBAAgB,EAChB,UAAU,EAGX,MAAM,qBAAqB,CAAC;AAM7B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C,OAAO,KAAK,EACV,KAAK,EACL,IAAI,EACJ,UAAU,EACV,MAAM,EACN,eAAe,EAChB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EACV,iBAAiB,EACjB,2BAA2B,EAC5B,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EACV,gBAAgB,EAChB,YAAY,EACZ,cAAc,EACd,cAAc,EACd,cAAc,EACd,aAAa,EACb,QAAQ,EACR,aAAa,EACb,cAAc,EACd,WAAW,EACX,gBAAgB,EACjB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAe,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAMpE,MAAM,MAAM,SAAS,GAAG;IACtB,QAAQ,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC;IAC1C,mEAAmE;IACnE,KAAK,IAAI,gBAAgB,EAAE,CAAC;IAC5B,4DAA4D;IAC5D,QAAQ,IAAI,sBAAsB,EAAE,CAAC;IACrC,KAAK,CAAC,QAAQ,EAAE,YAAY,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IACjD,KAAK,CAAC,QAAQ,EAAE,YAAY,EAAE,QAAQ,EAAE,YAAY,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CAC5E,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,KAAK,CAAC,QAAQ,EAAE,YAAY,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAC3D,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,CAAC,QAAQ,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CACtD,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,oEAAoE;IACpE,OAAO,IAAI,WAAW,EAAE,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC;IACvC,KAAK,CAAC,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,YAAY,GAAG,WAAW,CAAC;CACnE,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,CAAC,QAAQ,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IACxD,OAAO,CACL,QAAQ,EAAE,YAAY,EACtB,MAAM,EAAE,WAAW,EACnB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,cAAc,CAAC,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG;IACrB,IAAI,CAAC,QAAQ,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IACxD,GAAG,CACD,QAAQ,EAAE,YAAY,EACtB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE;QAAE,KAAK,EAAE,QAAQ,CAAA;KAAE,GAC3B,OAAO,CAAC,cAAc,CAAC,CAAC;IAC3B,MAAM,CACJ,QAAQ,EAAE,YAAY,EACtB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE;QAAE,KAAK,EAAE,QAAQ,CAAA;KAAE,GAC3B,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,IAAI,EAAE,IAAI,CAAC;IACX,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,EAAE,KAAK,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,eAAe,CAAC;CAC1B,CAAC;AA6BF,wBAAgB,QAAQ,CACtB,UAAU,EAAE,cAAc,EAC1B,OAAO,EAAE,YAAY,GACpB,SAAS,CAiCX;AAED,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,2BAA2B,EACvC,OAAO,EAAE,YAAY,GACpB,sBAAsB,CAIxB;AAED,wBAAgB,SAAS,CACvB,UAAU,EAAE,eAAe,EAC3B,OAAO,EAAE,YAAY,GACpB,UAAU,CAuBZ;AAED,wBAAgB,UAAU,CACxB,UAAU,EAAE,gBAAgB,EAC5B,OAAO,EAAE,YAAY,GACpB,WAAW,CAIb;AAQD,wBAAgB,UAAU,CACxB,UAAU,EAAE,gBAAgB,EAC5B,OAAO,EAAE,YAAY,GACpB,WAAW,CAab;AASD,wBAAgB,OAAO,CACrB,UAAU,EAAE,aAAa,EACzB,OAAO,EAAE,YAAY,GACpB,QAAQ,CA+BV"}
+{"version":3,"file":"facets.d.ts","sourceRoot":"","sources":["../../src/kernel/facets.ts"],"names":[],"mappings":"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"}

package/dist/kernel/facets.js

@@ -6,6 +6,7 @@
  */
 import { LOGIN_METHOD, } from "../auth/login.js";
 import { AUTH_MATERIAL_KIND, AUTH_STATUS, authMaterialRequiresSecret, } from "../auth/material.js";
+import { applyEnvPatch, EMPTY_ENV_PATCH } from "../core/env.js";
 import { AGENT_ERROR_CODE, AgentError } from "../core/error.js";
 import { resolveHostLocation } from "../host/context.js";
 import { validateSpecSecrets } from "../host/validate-spec.js";
@@ -83,6 +84,25 @@ export function bindSkills(capability, binding) {
         },
     };
 }
+export function bindSessions(capability, binding) {
+    const context = (options) => ({
+        env: applyEnvPatch(binding.env, options.env ?? EMPTY_ENV_PATCH),
+        exec: binding.exec,
+        clock: binding.clock,
+        logger: {
+            log: (level, message, data) => binding.logger.log(level, `[session ${binding.agentId}] ${message}`, data),
+        },
+    });
+    const resolved = (options) => ({
+        workspace: options.workspace,
+        permissions: options.permissions,
+    });
+    return {
+        open: (options) => capability.open(resolved(options), context(options)),
+        resume: (id, options) => capability.resume(id, { ...resolved(options), unarchive: options.unarchive ?? false }, context(options)),
+        inspect: (id, location) => capability.inspect(id, hostContext(binding, location)),
+    };
+}
 export function bindMcp(capability, binding) {
     return {
         list: (location) => capability.list(hostContext(binding, location)),

package/dist/kernel/runtime.d.ts

@@ -7,10 +7,10 @@
 import { type Ports } from "../core/ports.js";
 import type { RunHandle } from "../core/run.js";
 import { type StructuredHandle, type StructuredRunOptions } from "../structured/run-structured.js";
-import type { AgentDefinition } from "./definition.js";
-import { type AgentAuth, type AgentAvailabilityProbe, type AgentDoctor, type AgentLogin, type AgentMcp, type AgentSkills } from "./facets.js";
+import type { AgentDefinition, SessionPermissionsOf } from "./definition.js";
+import { type AgentAuth, type AgentAvailabilityProbe, type AgentDoctor, type AgentLogin, type AgentMcp, type AgentSessions, type AgentSkills } from "./facets.js";
 import { type RunOptions } from "./options.js";
-export interface Agent<Id extends string = string> {
+export interface Agent<Id extends string = string, SessionPermissions = unknown> {
     readonly id: Id;
     run<T>(options: StructuredRunOptions<T>): StructuredHandle<T>;
     run(options: RunOptions): RunHandle;
@@ -21,9 +21,13 @@ export interface Agent<Id extends string = string> {
     skills: AgentSkills | null;
     mcp: AgentMcp | null;
     doctor: AgentDoctor | null;
+    /** Long-lived conversations; `null` when the definition has no session facet. */
+    session: AgentSessions<SessionPermissions> | null;
 }
-export interface AgentRuntime<Id extends string = string> {
-    agent<I extends Id>(id: I): Agent<I>;
+export interface AgentRuntime<Id extends string = string, Defs extends readonly AgentDefinition[] = readonly AgentDefinition<Id>[]> {
+    agent<I extends Id>(id: I): Agent<I, SessionPermissionsOf<Extract<Defs[number], {
+        id: I;
+    }>>>;
     agents(): Agent<Id>[];
     /** The resolved ports — composition layers (fleet) reuse these. */
     readonly ports: Ports;
@@ -45,5 +49,5 @@ export type AgentRuntimeOptions<Defs extends readonly AgentDefinition[]> = {
  * resolver, so registering "keychain" never silently drops "env".
  */
 export declare function resolvePorts(ports?: Partial<Ports>): Ports;
-export declare function createAgentRuntime<const Defs extends readonly AgentDefinition[]>(options: AgentRuntimeOptions<Defs>): AgentRuntime<Defs[number]["id"]>;
+export declare function createAgentRuntime<const Defs extends readonly AgentDefinition[]>(options: AgentRuntimeOptions<Defs>): AgentRuntime<Defs[number]["id"], Defs>;
 //# sourceMappingURL=runtime.d.ts.map

package/dist/kernel/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/kernel/runtime.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,EAA6B,KAAK,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAGL,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EAE1B,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EACL,KAAK,SAAS,EACd,KAAK,sBAAsB,EAC3B,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,QAAQ,EACb,KAAK,WAAW,EAQjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,KAAK,UAAU,EAAqB,MAAM,cAAc,CAAC;AAGlE,MAAM,WAAW,KAAK,CAAC,EAAE,SAAS,MAAM,GAAG,MAAM;IAC/C,QAAQ,CAAC,EAAE,EAAE,EAAE,CAAC;IAChB,GAAG,CAAC,CAAC,EAAE,OAAO,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAC;IAC9D,GAAG,CAAC,OAAO,EAAE,UAAU,GAAG,SAAS,CAAC;IACpC,GAAG,CAAC,CAAC,EACH,OAAO,EAAE,UAAU,GAAG,oBAAoB,CAAC,CAAC,CAAC,GAC5C,SAAS,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAC;IACnC,YAAY,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAC5C,IAAI,EAAE,SAAS,GAAG,IAAI,CAAC;IACvB,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IACzB,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IAC3B,GAAG,EAAE,QAAQ,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;CAC5B;AAED,MAAM,WAAW,YAAY,CAAC,EAAE,SAAS,MAAM,GAAG,MAAM;IACtD,KAAK,CAAC,CAAC,SAAS,EAAE,EAAE,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACrC,MAAM,IAAI,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC;IACtB,mEAAmE;IACnE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;CACvB;AAED,MAAM,MAAM,mBAAmB,CAAC,IAAI,SAAS,SAAS,eAAe,EAAE,IAAI;IACzE,MAAM,EAAE,IAAI,CAAC;IACb,KAAK,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IACvB;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,KAAK,CAS1D;AAyED,wBAAgB,kBAAkB,CAChC,KAAK,CAAC,IAAI,SAAS,SAAS,eAAe,EAAE,EAC7C,OAAO,EAAE,mBAAmB,CAAC,IAAI,CAAC,GAAG,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAoCtE"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/kernel/runtime.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,EAA6B,KAAK,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAGL,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EAE1B,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC7E,OAAO,EACL,KAAK,SAAS,EACd,KAAK,sBAAsB,EAC3B,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,QAAQ,EACb,KAAK,aAAa,EAClB,KAAK,WAAW,EASjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,KAAK,UAAU,EAAqB,MAAM,cAAc,CAAC;AAGlE,MAAM,WAAW,KAAK,CACpB,EAAE,SAAS,MAAM,GAAG,MAAM,EAC1B,kBAAkB,GAAG,OAAO;IAE5B,QAAQ,CAAC,EAAE,EAAE,EAAE,CAAC;IAChB,GAAG,CAAC,CAAC,EAAE,OAAO,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAC;IAC9D,GAAG,CAAC,OAAO,EAAE,UAAU,GAAG,SAAS,CAAC;IACpC,GAAG,CAAC,CAAC,EACH,OAAO,EAAE,UAAU,GAAG,oBAAoB,CAAC,CAAC,CAAC,GAC5C,SAAS,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAC;IACnC,YAAY,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAC5C,IAAI,EAAE,SAAS,GAAG,IAAI,CAAC;IACvB,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IACzB,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IAC3B,GAAG,EAAE,QAAQ,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IAC3B,iFAAiF;IACjF,OAAO,EAAE,aAAa,CAAC,kBAAkB,CAAC,GAAG,IAAI,CAAC;CACnD;AAED,MAAM,WAAW,YAAY,CAC3B,EAAE,SAAS,MAAM,GAAG,MAAM,EAC1B,IAAI,SAAS,SAAS,eAAe,EAAE,GAAG,SAAS,eAAe,CAAC,EAAE,CAAC,EAAE;IAExE,KAAK,CAAC,CAAC,SAAS,EAAE,EAChB,EAAE,EAAE,CAAC,GACJ,KAAK,CAAC,CAAC,EAAE,oBAAoB,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE;QAAE,EAAE,EAAE,CAAC,CAAA;KAAE,CAAC,CAAC,CAAC,CAAC;IACpE,MAAM,IAAI,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC;IACtB,mEAAmE;IACnE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;CACvB;AAED,MAAM,MAAM,mBAAmB,CAAC,IAAI,SAAS,SAAS,eAAe,EAAE,IAAI;IACzE,MAAM,EAAE,IAAI,CAAC;IACb,KAAK,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IACvB;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,KAAK,CAS1D;AA6ED,wBAAgB,kBAAkB,CAChC,KAAK,CAAC,IAAI,SAAS,SAAS,eAAe,EAAE,EAC7C,OAAO,EAAE,mBAAmB,CAAC,IAAI,CAAC,GAAG,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,CAwC5E"}

package/dist/kernel/runtime.js

@@ -10,7 +10,7 @@ import { AGENT_ERROR_CODE, AgentError } from "../core/error.js";
 import { fetchHttp, nodeExec, systemClock } from "../core/node-ports.js";
 import { noopLogger, noopTelemetry } from "../core/ports.js";
 import { isStructuredRunOptions, resolveStructuredRunOptions, startStructuredRun, } from "../structured/run-structured.js";
-import { bindAuth, bindAvailability, bindDoctor, bindLogin, bindMcp, bindSkills, } from "./facets.js";
+import { bindAuth, bindAvailability, bindDoctor, bindLogin, bindMcp, bindSessions, bindSkills, } from "./facets.js";
 import { resolveRunOptions } from "./options.js";
 import { startRun } from "./run.js";
 /**
@@ -77,6 +77,9 @@ function bindAgent(definition, ports, baseEnv) {
         doctor: definition.doctor === undefined
             ? null
             : bindDoctor(definition.doctor, binding),
+        session: definition.session === undefined
+            ? null
+            : bindSessions(definition.session, binding),
     };
 }
 export function createAgentRuntime(options) {

package/dist/kernel/session.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Session driver pieces shared by the built-in hosts: the definition-side
+ * capability contract, the long-lived interactive child (spawn, NDJSON
+ * lines, EOF-first close), and the turn/event state
+ * every Session keeps. Protocol knowledge (what to write, how to read a
+ * line) stays in the adapter modules.
+ */
+import { AGENT_ERROR_CODE, AgentError } from "../core/error.js";
+import type { Clock, Exec, ExecExit, Logger } from "../core/ports.js";
+import { type Session, type SessionEvent, type SessionFacts, type TurnOutcome, type TurnResult } from "../core/session.js";
+import type { HostContext } from "../host/context.js";
+/** Resolved (rule 2): what a session adapter gets to open or resume. */
+export type SessionContext = {
+    /** Fully layered: baseEnv → options.env. */
+    env: Record<string, string>;
+    exec: Exec;
+    clock: Clock;
+    /** Pre-scoped to the session by the kernel. */
+    logger: Logger;
+};
+export type ResolvedSessionOpenOptions<Permissions> = {
+    workspace: string;
+    permissions: Permissions;
+};
+export type ResolvedSessionResumeOptions<Permissions> = ResolvedSessionOpenOptions<Permissions> & {
+    /** Codex only: unarchive an archived thread before resuming it. */
+    unarchive: boolean;
+};
+/** Definition-side session capability; absent = `Agent.session` is `null`. */
+export type SessionCapability<Permissions> = {
+    open(options: ResolvedSessionOpenOptions<Permissions>, ctx: SessionContext): Promise<Session>;
+    resume(id: string, options: ResolvedSessionResumeOptions<Permissions>, ctx: SessionContext): Promise<Session>;
+    inspect(id: string, ctx: HostContext): Promise<SessionFacts<Permissions> | null>;
+};
+export declare function assertHostSessionId(id: string, agentId: string): void;
+export declare function sessionStateError(agentId: string, reason: string): AgentError<typeof AGENT_ERROR_CODE.invalidInput>;
+export declare function sessionExitedError(agentId: string, exit: ExecExit | null, stderrTail: string): AgentError<typeof AGENT_ERROR_CODE.failed>;
+/**
+ * One interactive child held for the life of a Session: stdout is read as
+ * NDJSON lines, stdin stays open for incremental writes, and `close()`
+ * ends stdin first (both hosts exit on EOF) before escalating to signals.
+ */
+export declare class SessionProcess {
+    private readonly process;
+    private readonly clock;
+    private exitValue;
+    private stderrTail;
+    private constructor();
+    static spawn(input: {
+        command: string;
+        args: readonly string[];
+        cwd: string;
+        ctx: SessionContext;
+        agentId: string;
+    }): Promise<SessionProcess>;
+    get exit(): Promise<ExecExit>;
+    get exited(): ExecExit | null;
+    get stderr(): string;
+    writeLine(line: string): void;
+    /** Non-empty stdout lines in order; stderr is kept as a tail for errors. */
+    lines(): AsyncGenerator<string, void, void>;
+    close(): Promise<ExecExit>;
+}
+/**
+ * Turn bookkeeping and the event stream. Exactly one turn runs at a time:
+ * `send` needs idle, `steer`/`interrupt` need active — both are typed
+ * `invalid_input`, never a silent queue.
+ */
+export declare class SessionState {
+    private readonly agentId;
+    private readonly broadcast;
+    private active;
+    /** A turn whose start the host has not acknowledged yet (Codex `turn/start` in flight). */
+    private starting;
+    private ended;
+    constructor(agentId: string);
+    get events(): AsyncIterable<SessionEvent>;
+    get activeTurnId(): string | null;
+    get isEnded(): boolean;
+    get isStarting(): boolean;
+    emit(event: SessionEvent): void;
+    /** Record a message for the turn's fallback text and publish it. */
+    message(text: string): void;
+    requireOpen(): void;
+    requireIdle(): void;
+    /** Reserve the idle slot while the host is asked to start the turn. */
+    markStarting(): void;
+    /** The host refused to start the turn; the slot is idle again. */
+    clearStarting(): void;
+    requireActive(): string;
+    beginTurn(turnId: string): Promise<TurnResult>;
+    /** `text === null` falls back to the turn's collected messages. */
+    endTurn(outcome: TurnOutcome, text: string | null): void;
+    /** The process is gone: fail the running turn, publish `exited`, end the stream. */
+    end(exit: ExecExit, stderrTail: string): void;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/kernel/session.d.ts.map

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