apex-code 0.0.1-alpha.0 → 0.0.1-alpha.2

package/dist/core/sandbox/policy.d.ts

@@ -0,0 +1,32 @@
+export interface SandboxPolicy {
+    readonly workspace: string;
+    readonly allowedHosts: readonly string[];
+}
+export type SandboxPolicyResult = {
+    readonly kind: "valid";
+    readonly policy: SandboxPolicy;
+} | {
+    readonly kind: "invalid";
+    readonly reason: string;
+};
+export type SandboxStatus = {
+    readonly kind: "enforced";
+} | {
+    readonly kind: "unavailable";
+    readonly reason: string;
+};
+export declare class SandboxUnavailableError extends Error {
+    constructor(reason: string);
+}
+/**
+ * Validate the single writable boundary before any platform backend runs. We accept
+ * no relative, missing, or non-directory workspace because a backend must never
+ * silently broaden an ambiguous path into host authority.
+ */
+export declare function createSandboxPolicy(options: {
+    workspace: string;
+    allowedHosts?: readonly string[];
+}): SandboxPolicyResult;
+/** Throws rather than returning an executable fallback when OS enforcement is absent. */
+export declare function requireSandboxEnforcement(status: SandboxStatus): void;
+//# sourceMappingURL=policy.d.ts.map

package/dist/core/sandbox/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../../src/core/sandbox/policy.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC;AAED,MAAM,MAAM,mBAAmB,GAC5B;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;CAAE,GAC1D;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD,MAAM,MAAM,aAAa,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtH,qBAAa,uBAAwB,SAAQ,KAAK;IACjD,YAAY,MAAM,EAAE,MAAM,EAGzB;CACD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACjC,GAAG,mBAAmB,CAiBtB;AAED,yFAAyF;AACzF,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAGrE","sourcesContent":["import { existsSync, realpathSync, statSync } from \"node:fs\";\nimport { isAbsolute } from \"node:path\";\n\nexport interface SandboxPolicy {\n\treadonly workspace: string;\n\treadonly allowedHosts: readonly string[];\n}\n\nexport type SandboxPolicyResult =\n\t| { readonly kind: \"valid\"; readonly policy: SandboxPolicy }\n\t| { readonly kind: \"invalid\"; readonly reason: string };\n\nexport type SandboxStatus = { readonly kind: \"enforced\" } | { readonly kind: \"unavailable\"; readonly reason: string };\n\nexport class SandboxUnavailableError extends Error {\n\tconstructor(reason: string) {\n\t\tsuper(`OS sandbox is not enforcing this agent session: ${reason}`);\n\t\tthis.name = \"SandboxUnavailableError\";\n\t}\n}\n\n/**\n * Validate the single writable boundary before any platform backend runs. We accept\n * no relative, missing, or non-directory workspace because a backend must never\n * silently broaden an ambiguous path into host authority.\n */\nexport function createSandboxPolicy(options: {\n\tworkspace: string;\n\tallowedHosts?: readonly string[];\n}): SandboxPolicyResult {\n\tif (!isAbsolute(options.workspace)) {\n\t\treturn { kind: \"invalid\", reason: \"Sandbox workspace must be an absolute path.\" };\n\t}\n\tif (!existsSync(options.workspace)) {\n\t\treturn { kind: \"invalid\", reason: `Sandbox workspace does not exist: ${options.workspace}` };\n\t}\n\tif (!statSync(options.workspace).isDirectory()) {\n\t\treturn { kind: \"invalid\", reason: `Sandbox workspace is not a directory: ${options.workspace}` };\n\t}\n\treturn {\n\t\tkind: \"valid\",\n\t\tpolicy: {\n\t\t\tworkspace: realpathSync(options.workspace),\n\t\t\tallowedHosts: options.allowedHosts ?? [],\n\t\t},\n\t};\n}\n\n/** Throws rather than returning an executable fallback when OS enforcement is absent. */\nexport function requireSandboxEnforcement(status: SandboxStatus): void {\n\tif (status.kind === \"enforced\") return;\n\tthrow new SandboxUnavailableError(status.reason);\n}\n"]}

package/dist/core/sandbox/policy.js

@@ -0,0 +1,38 @@
+import { existsSync, realpathSync, statSync } from "node:fs";
+import { isAbsolute } from "node:path";
+export class SandboxUnavailableError extends Error {
+    constructor(reason) {
+        super(`OS sandbox is not enforcing this agent session: ${reason}`);
+        this.name = "SandboxUnavailableError";
+    }
+}
+/**
+ * Validate the single writable boundary before any platform backend runs. We accept
+ * no relative, missing, or non-directory workspace because a backend must never
+ * silently broaden an ambiguous path into host authority.
+ */
+export function createSandboxPolicy(options) {
+    if (!isAbsolute(options.workspace)) {
+        return { kind: "invalid", reason: "Sandbox workspace must be an absolute path." };
+    }
+    if (!existsSync(options.workspace)) {
+        return { kind: "invalid", reason: `Sandbox workspace does not exist: ${options.workspace}` };
+    }
+    if (!statSync(options.workspace).isDirectory()) {
+        return { kind: "invalid", reason: `Sandbox workspace is not a directory: ${options.workspace}` };
+    }
+    return {
+        kind: "valid",
+        policy: {
+            workspace: realpathSync(options.workspace),
+            allowedHosts: options.allowedHosts ?? [],
+        },
+    };
+}
+/** Throws rather than returning an executable fallback when OS enforcement is absent. */
+export function requireSandboxEnforcement(status) {
+    if (status.kind === "enforced")
+        return;
+    throw new SandboxUnavailableError(status.reason);
+}
+//# sourceMappingURL=policy.js.map

package/dist/core/sandbox/policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.js","sourceRoot":"","sources":["../../../src/core/sandbox/policy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC7D,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAavC,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IACjD,YAAY,MAAc,EAAE;QAC3B,KAAK,CAAC,mDAAmD,MAAM,EAAE,CAAC,CAAC;QACnE,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IAAA,CACtC;CACD;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAGnC,EAAuB;IACvB,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QACpC,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,6CAA6C,EAAE,CAAC;IACnF,CAAC;IACD,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QACpC,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,qCAAqC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC;IAC9F,CAAC;IACD,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;QAChD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,yCAAyC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC;IAClG,CAAC;IACD,OAAO;QACN,IAAI,EAAE,OAAO;QACb,MAAM,EAAE;YACP,SAAS,EAAE,YAAY,CAAC,OAAO,CAAC,SAAS,CAAC;YAC1C,YAAY,EAAE,OAAO,CAAC,YAAY,IAAI,EAAE;SACxC;KACD,CAAC;AAAA,CACF;AAED,yFAAyF;AACzF,MAAM,UAAU,yBAAyB,CAAC,MAAqB,EAAQ;IACtE,IAAI,MAAM,CAAC,IAAI,KAAK,UAAU;QAAE,OAAO;IACvC,MAAM,IAAI,uBAAuB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AAAA,CACjD","sourcesContent":["import { existsSync, realpathSync, statSync } from \"node:fs\";\nimport { isAbsolute } from \"node:path\";\n\nexport interface SandboxPolicy {\n\treadonly workspace: string;\n\treadonly allowedHosts: readonly string[];\n}\n\nexport type SandboxPolicyResult =\n\t| { readonly kind: \"valid\"; readonly policy: SandboxPolicy }\n\t| { readonly kind: \"invalid\"; readonly reason: string };\n\nexport type SandboxStatus = { readonly kind: \"enforced\" } | { readonly kind: \"unavailable\"; readonly reason: string };\n\nexport class SandboxUnavailableError extends Error {\n\tconstructor(reason: string) {\n\t\tsuper(`OS sandbox is not enforcing this agent session: ${reason}`);\n\t\tthis.name = \"SandboxUnavailableError\";\n\t}\n}\n\n/**\n * Validate the single writable boundary before any platform backend runs. We accept\n * no relative, missing, or non-directory workspace because a backend must never\n * silently broaden an ambiguous path into host authority.\n */\nexport function createSandboxPolicy(options: {\n\tworkspace: string;\n\tallowedHosts?: readonly string[];\n}): SandboxPolicyResult {\n\tif (!isAbsolute(options.workspace)) {\n\t\treturn { kind: \"invalid\", reason: \"Sandbox workspace must be an absolute path.\" };\n\t}\n\tif (!existsSync(options.workspace)) {\n\t\treturn { kind: \"invalid\", reason: `Sandbox workspace does not exist: ${options.workspace}` };\n\t}\n\tif (!statSync(options.workspace).isDirectory()) {\n\t\treturn { kind: \"invalid\", reason: `Sandbox workspace is not a directory: ${options.workspace}` };\n\t}\n\treturn {\n\t\tkind: \"valid\",\n\t\tpolicy: {\n\t\t\tworkspace: realpathSync(options.workspace),\n\t\t\tallowedHosts: options.allowedHosts ?? [],\n\t\t},\n\t};\n}\n\n/** Throws rather than returning an executable fallback when OS enforcement is absent. */\nexport function requireSandboxEnforcement(status: SandboxStatus): void {\n\tif (status.kind === \"enforced\") return;\n\tthrow new SandboxUnavailableError(status.reason);\n}\n"]}

package/dist/core/sandbox/supervisor.d.ts

@@ -0,0 +1,31 @@
+import { type SandboxPolicy, type SandboxStatus } from "./policy.ts";
+export interface SandboxLaunch {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly policy: SandboxPolicy;
+    readonly environment?: NodeJS.ProcessEnv;
+    /** Application/runtime directories needed by the child but never writable by it. */
+    readonly readOnlyPaths?: readonly string[];
+    /** Individual read-only files, such as a host-owned credential file. */
+    readonly readOnlyFiles?: readonly string[];
+}
+/** A platform adapter. Its sole job is to launch a normal Apex child inside an OS boundary. */
+export interface SandboxBackend {
+    readonly status: SandboxStatus;
+    launch(launch: SandboxLaunch): Promise<number>;
+    close(): Promise<void>;
+}
+export interface SandboxSupervisor {
+    readonly status: SandboxStatus;
+    launch(options: Omit<SandboxLaunch, "policy">): Promise<number>;
+    close(): Promise<void>;
+}
+/**
+ * Owns fail-closed policy propagation and lifecycle; OS details remain behind the
+ * backend so all testable security semantics are Apex-owned.
+ */
+export declare function createSandboxSupervisor(options: {
+    backend: SandboxBackend;
+    policy: SandboxPolicy;
+}): SandboxSupervisor;
+//# sourceMappingURL=supervisor.d.ts.map

package/dist/core/sandbox/supervisor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor.d.ts","sourceRoot":"","sources":["../../../src/core/sandbox/supervisor.ts"],"names":[],"mappings":"AAAA,OAAO,EAA6B,KAAK,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAEhG,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACzC,oFAAoF;IACpF,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,wEAAwE;IACxE,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3C;AAED,+FAA+F;AAC/F,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,MAAM,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,aAAa,EAAE,QAAQ,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAChE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE;IAChD,OAAO,EAAE,cAAc,CAAC;IACxB,MAAM,EAAE,aAAa,CAAC;CACtB,GAAG,iBAAiB,CAWpB","sourcesContent":["import { requireSandboxEnforcement, type SandboxPolicy, type SandboxStatus } from \"./policy.ts\";\n\nexport interface SandboxLaunch {\n\treadonly command: string;\n\treadonly args: readonly string[];\n\treadonly policy: SandboxPolicy;\n\treadonly environment?: NodeJS.ProcessEnv;\n\t/** Application/runtime directories needed by the child but never writable by it. */\n\treadonly readOnlyPaths?: readonly string[];\n\t/** Individual read-only files, such as a host-owned credential file. */\n\treadonly readOnlyFiles?: readonly string[];\n}\n\n/** A platform adapter. Its sole job is to launch a normal Apex child inside an OS boundary. */\nexport interface SandboxBackend {\n\treadonly status: SandboxStatus;\n\tlaunch(launch: SandboxLaunch): Promise<number>;\n\tclose(): Promise<void>;\n}\n\nexport interface SandboxSupervisor {\n\treadonly status: SandboxStatus;\n\tlaunch(options: Omit<SandboxLaunch, \"policy\">): Promise<number>;\n\tclose(): Promise<void>;\n}\n\n/**\n * Owns fail-closed policy propagation and lifecycle; OS details remain behind the\n * backend so all testable security semantics are Apex-owned.\n */\nexport function createSandboxSupervisor(options: {\n\tbackend: SandboxBackend;\n\tpolicy: SandboxPolicy;\n}): SandboxSupervisor {\n\treturn {\n\t\tstatus: options.backend.status,\n\t\tasync launch(launch) {\n\t\t\trequireSandboxEnforcement(options.backend.status);\n\t\t\treturn options.backend.launch({ ...launch, policy: options.policy });\n\t\t},\n\t\tasync close() {\n\t\t\tawait options.backend.close();\n\t\t},\n\t};\n}\n"]}

package/dist/core/sandbox/supervisor.js

@@ -0,0 +1,18 @@
+import { requireSandboxEnforcement } from "./policy.js";
+/**
+ * Owns fail-closed policy propagation and lifecycle; OS details remain behind the
+ * backend so all testable security semantics are Apex-owned.
+ */
+export function createSandboxSupervisor(options) {
+    return {
+        status: options.backend.status,
+        async launch(launch) {
+            requireSandboxEnforcement(options.backend.status);
+            return options.backend.launch({ ...launch, policy: options.policy });
+        },
+        async close() {
+            await options.backend.close();
+        },
+    };
+}
+//# sourceMappingURL=supervisor.js.map

package/dist/core/sandbox/supervisor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor.js","sourceRoot":"","sources":["../../../src/core/sandbox/supervisor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAA0C,MAAM,aAAa,CAAC;AA0BhG;;;GAGG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAGvC,EAAqB;IACrB,OAAO;QACN,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,MAAM;QAC9B,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE;YACpB,yBAAyB,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YAClD,OAAO,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;QAAA,CACrE;QACD,KAAK,CAAC,KAAK,GAAG;YACb,MAAM,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QAAA,CAC9B;KACD,CAAC;AAAA,CACF","sourcesContent":["import { requireSandboxEnforcement, type SandboxPolicy, type SandboxStatus } from \"./policy.ts\";\n\nexport interface SandboxLaunch {\n\treadonly command: string;\n\treadonly args: readonly string[];\n\treadonly policy: SandboxPolicy;\n\treadonly environment?: NodeJS.ProcessEnv;\n\t/** Application/runtime directories needed by the child but never writable by it. */\n\treadonly readOnlyPaths?: readonly string[];\n\t/** Individual read-only files, such as a host-owned credential file. */\n\treadonly readOnlyFiles?: readonly string[];\n}\n\n/** A platform adapter. Its sole job is to launch a normal Apex child inside an OS boundary. */\nexport interface SandboxBackend {\n\treadonly status: SandboxStatus;\n\tlaunch(launch: SandboxLaunch): Promise<number>;\n\tclose(): Promise<void>;\n}\n\nexport interface SandboxSupervisor {\n\treadonly status: SandboxStatus;\n\tlaunch(options: Omit<SandboxLaunch, \"policy\">): Promise<number>;\n\tclose(): Promise<void>;\n}\n\n/**\n * Owns fail-closed policy propagation and lifecycle; OS details remain behind the\n * backend so all testable security semantics are Apex-owned.\n */\nexport function createSandboxSupervisor(options: {\n\tbackend: SandboxBackend;\n\tpolicy: SandboxPolicy;\n}): SandboxSupervisor {\n\treturn {\n\t\tstatus: options.backend.status,\n\t\tasync launch(launch) {\n\t\t\trequireSandboxEnforcement(options.backend.status);\n\t\t\treturn options.backend.launch({ ...launch, policy: options.policy });\n\t\t},\n\t\tasync close() {\n\t\t\tawait options.backend.close();\n\t\t},\n\t};\n}\n"]}

package/dist/core/sandbox/violations.d.ts

@@ -0,0 +1,23 @@
+export type SandboxViolationKind = "filesystem" | "network" | "unknown";
+export interface SandboxViolation {
+    readonly kind: SandboxViolationKind;
+    readonly command: string;
+    readonly detail: string;
+    readonly timestamp: Date;
+}
+/**
+ * Apex-owned bounded violation tail. It intentionally does not depend on a platform
+ * runtime's monitor, because Linux does not provide that monitor consistently.
+ */
+export declare class SandboxViolationStore {
+    private readonly capacity;
+    private readonly violations;
+    private _totalCount;
+    constructor(options?: {
+        capacity?: number;
+    });
+    get totalCount(): number;
+    add(violation: SandboxViolation): void;
+    list(): readonly SandboxViolation[];
+}
+//# sourceMappingURL=violations.d.ts.map

package/dist/core/sandbox/violations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"violations.d.ts","sourceRoot":"","sources":["../../../src/core/sandbox/violations.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,oBAAoB,GAAG,YAAY,GAAG,SAAS,GAAG,SAAS,CAAC;AAExE,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;CACzB;AAED;;;GAGG;AACH,qBAAa,qBAAqB;IACjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA0B;IACrD,OAAO,CAAC,WAAW,CAAK;IAExB,YAAY,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,EAM1C;IAED,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,GAAG,CAAC,SAAS,EAAE,gBAAgB,GAAG,IAAI,CAMrC;IAED,IAAI,IAAI,SAAS,gBAAgB,EAAE,CAElC;CACD","sourcesContent":["export type SandboxViolationKind = \"filesystem\" | \"network\" | \"unknown\";\n\nexport interface SandboxViolation {\n\treadonly kind: SandboxViolationKind;\n\treadonly command: string;\n\treadonly detail: string;\n\treadonly timestamp: Date;\n}\n\n/**\n * Apex-owned bounded violation tail. It intentionally does not depend on a platform\n * runtime's monitor, because Linux does not provide that monitor consistently.\n */\nexport class SandboxViolationStore {\n\tprivate readonly capacity: number;\n\tprivate readonly violations: SandboxViolation[] = [];\n\tprivate _totalCount = 0;\n\n\tconstructor(options?: { capacity?: number }) {\n\t\tconst capacity = options?.capacity ?? 100;\n\t\tif (!Number.isSafeInteger(capacity) || capacity < 1) {\n\t\t\tthrow new Error(\"Sandbox violation capacity must be a positive safe integer.\");\n\t\t}\n\t\tthis.capacity = capacity;\n\t}\n\n\tget totalCount(): number {\n\t\treturn this._totalCount;\n\t}\n\n\tadd(violation: SandboxViolation): void {\n\t\tthis._totalCount += 1;\n\t\tthis.violations.push(violation);\n\t\tif (this.violations.length > this.capacity) {\n\t\t\tthis.violations.splice(0, this.violations.length - this.capacity);\n\t\t}\n\t}\n\n\tlist(): readonly SandboxViolation[] {\n\t\treturn [...this.violations];\n\t}\n}\n"]}

package/dist/core/sandbox/violations.js

@@ -0,0 +1,30 @@
+/**
+ * Apex-owned bounded violation tail. It intentionally does not depend on a platform
+ * runtime's monitor, because Linux does not provide that monitor consistently.
+ */
+export class SandboxViolationStore {
+    capacity;
+    violations = [];
+    _totalCount = 0;
+    constructor(options) {
+        const capacity = options?.capacity ?? 100;
+        if (!Number.isSafeInteger(capacity) || capacity < 1) {
+            throw new Error("Sandbox violation capacity must be a positive safe integer.");
+        }
+        this.capacity = capacity;
+    }
+    get totalCount() {
+        return this._totalCount;
+    }
+    add(violation) {
+        this._totalCount += 1;
+        this.violations.push(violation);
+        if (this.violations.length > this.capacity) {
+            this.violations.splice(0, this.violations.length - this.capacity);
+        }
+    }
+    list() {
+        return [...this.violations];
+    }
+}
+//# sourceMappingURL=violations.js.map

package/dist/core/sandbox/violations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"violations.js","sourceRoot":"","sources":["../../../src/core/sandbox/violations.ts"],"names":[],"mappings":"AASA;;;GAGG;AACH,MAAM,OAAO,qBAAqB;IAChB,QAAQ,CAAS;IACjB,UAAU,GAAuB,EAAE,CAAC;IAC7C,WAAW,GAAG,CAAC,CAAC;IAExB,YAAY,OAA+B,EAAE;QAC5C,MAAM,QAAQ,GAAG,OAAO,EAAE,QAAQ,IAAI,GAAG,CAAC;QAC1C,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,QAAQ,CAAC,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;YACrD,MAAM,IAAI,KAAK,CAAC,6DAA6D,CAAC,CAAC;QAChF,CAAC;QACD,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAAA,CACzB;IAED,IAAI,UAAU,GAAW;QACxB,OAAO,IAAI,CAAC,WAAW,CAAC;IAAA,CACxB;IAED,GAAG,CAAC,SAA2B,EAAQ;QACtC,IAAI,CAAC,WAAW,IAAI,CAAC,CAAC;QACtB,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAChC,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC5C,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,UAAU,CAAC,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC;QACnE,CAAC;IAAA,CACD;IAED,IAAI,GAAgC;QACnC,OAAO,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC;IAAA,CAC5B;CACD","sourcesContent":["export type SandboxViolationKind = \"filesystem\" | \"network\" | \"unknown\";\n\nexport interface SandboxViolation {\n\treadonly kind: SandboxViolationKind;\n\treadonly command: string;\n\treadonly detail: string;\n\treadonly timestamp: Date;\n}\n\n/**\n * Apex-owned bounded violation tail. It intentionally does not depend on a platform\n * runtime's monitor, because Linux does not provide that monitor consistently.\n */\nexport class SandboxViolationStore {\n\tprivate readonly capacity: number;\n\tprivate readonly violations: SandboxViolation[] = [];\n\tprivate _totalCount = 0;\n\n\tconstructor(options?: { capacity?: number }) {\n\t\tconst capacity = options?.capacity ?? 100;\n\t\tif (!Number.isSafeInteger(capacity) || capacity < 1) {\n\t\t\tthrow new Error(\"Sandbox violation capacity must be a positive safe integer.\");\n\t\t}\n\t\tthis.capacity = capacity;\n\t}\n\n\tget totalCount(): number {\n\t\treturn this._totalCount;\n\t}\n\n\tadd(violation: SandboxViolation): void {\n\t\tthis._totalCount += 1;\n\t\tthis.violations.push(violation);\n\t\tif (this.violations.length > this.capacity) {\n\t\t\tthis.violations.splice(0, this.violations.length - this.capacity);\n\t\t}\n\t}\n\n\tlist(): readonly SandboxViolation[] {\n\t\treturn [...this.violations];\n\t}\n}\n"]}

package/dist/core/sdk.d.ts

@@ -1,11 +1,13 @@
 import { type Model } from "@earendil-works/pi-ai/compat";
 import { type ThinkingLevel } from "apex-code-agent-core";
-import { AgentSession } from "./agent-session.ts";
+import { AgentSession, type AgentSessionConfig } from "./agent-session.ts";
+import type { AgentDefinitionResolver } from "./delegation/runtime.ts";
 import type { LoadExtensionsResult, SessionStartEvent, ToolDefinition } from "./extensions/index.ts";
 import { ModelRuntime } from "./model-runtime.ts";
 import type { ResourceLoader } from "./resource-loader.ts";
 import { SessionManager } from "./session-manager.ts";
 import { SettingsManager } from "./settings-manager.ts";
+import type { EvidenceSink } from "./tools/contract.ts";
 import { createBashTool, createCodingTools, createEditTool, createFindTool, createGrepTool, createLsTool, createReadOnlyTools, createReadTool, createWriteTool, withFileMutationQueue } from "./tools/index.ts";
 export interface CreateAgentSessionOptions {
     /** Working directory for project-local discovery. Default: process.cwd() */
@@ -51,6 +53,23 @@ export interface CreateAgentSessionOptions {
     settingsManager?: SettingsManager;
     /** Session start event metadata for extension runtime startup. */
     sessionStartEvent?: SessionStartEvent;
+    /** Authorization configuration for every registered tool call. */
+    permissionGate?: AgentSessionConfig["permissionGate"];
+    /** Optional destination for source-level evidence; defaults to the durable session sink. */
+    evidenceSink?: EvidenceSink;
+    /**
+     * Delegation entry point (roadmap Phase 5, ADR 0008). When set, `delegate`
+     * executes real child sessions through `resolveAgent`, with the child's
+     * authority derived from this session's live active tools and permission
+     * store -- never reconstructed. When omitted, `delegate` stays inert (no agent
+     * types resolve). Agent discovery is injected here as a caller-supplied
+     * resolver rather than built in, until Phase 5 task 5.5 lands real
+     * markdown/frontmatter discovery. Requires `permissionGate` to be set too: a
+     * child's authority has nothing to derive from otherwise.
+     */
+    delegation?: {
+        resolveAgent?: AgentDefinitionResolver;
+    };
 }
 /** Result from createAgentSession */
 export interface CreateAgentSessionResult {
@@ -67,40 +86,5 @@ export type { PromptTemplate } from "./prompt-templates.ts";
 export type { Skill } from "./skills.ts";
 export type { Tool } from "./tools/index.ts";
 export { withFileMutationQueue, createCodingTools, createReadOnlyTools, createReadTool, createBashTool, createEditTool, createWriteTool, createGrepTool, createFindTool, createLsTool, };
-/**
- * Create an AgentSession with the specified options.
- *
- * @example
- * ```typescript
- * // Minimal - uses defaults
- * const { session } = await createAgentSession();
- *
- * // With explicit model
- * import { getModel } from '@earendil-works/pi-ai';
- * const { session } = await createAgentSession({
- *   model: getModel('anthropic', 'claude-opus-4-5'),
- *   thinkingLevel: 'high',
- * });
- *
- * // Continue previous session
- * const { session, modelFallbackMessage } = await createAgentSession({
- *   continueSession: true,
- * });
- *
- * // Full control
- * const loader = new DefaultResourceLoader({
- *   cwd: process.cwd(),
- *   agentDir: getAgentDir(),
- *   settingsManager: SettingsManager.create(),
- * });
- * await loader.reload();
- * const { session } = await createAgentSession({
- *   model: myModel,
- *   tools: ["read", "bash"],
- *   resourceLoader: loader,
- *   sessionManager: SessionManager.inMemory(),
- * });
- * ```
- */
 export declare function createAgentSession(options?: CreateAgentSessionOptions): Promise<CreateAgentSessionResult>;
 //# sourceMappingURL=sdk.d.ts.map

package/dist/core/sdk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sdk.d.ts","sourceRoot":"","sources":["../../src/core/sdk.ts"],"names":[],"mappings":"AACA,OAAO,EAAoC,KAAK,KAAK,EAAgB,MAAM,8BAA8B,CAAC;AAC1G,OAAO,EAAgD,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAGxG,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGlD,OAAO,KAAK,EAAmB,oBAAoB,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAGtH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,OAAO,EAAwB,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC5E,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAExD,OAAO,EACN,cAAc,EACd,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,cAAc,EACd,YAAY,EACZ,mBAAmB,EACnB,cAAc,EACd,eAAe,EAEf,qBAAqB,EACrB,MAAM,kBAAkB,CAAC;AAO1B,MAAM,WAAW,yBAAyB;IACzC,4EAA4E;IAC5E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,oGAAoG;IACpG,YAAY,CAAC,EAAE,YAAY,CAAC;IAE5B,iEAAiE;IACjE,KAAK,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;IACnB,4FAA4F;IAC5F,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,gEAAgE;IAChE,YAAY,CAAC,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;QAAC,aAAa,CAAC,EAAE,aAAa,CAAA;KAAE,CAAC,CAAC;IAE3E;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;IAC5B;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,gGAAgG;IAChG,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,gEAAgE;IAChE,WAAW,CAAC,EAAE,cAAc,EAAE,CAAC;IAE/B,oEAAoE;IACpE,cAAc,CAAC,EAAE,cAAc,CAAC;IAEhC,2DAA2D;IAC3D,cAAc,CAAC,EAAE,cAAc,CAAC;IAEhC,uEAAuE;IACvE,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,kEAAkE;IAClE,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;CACtC;AAED,qCAAqC;AACrC,MAAM,WAAW,wBAAwB;IACxC,0BAA0B;IAC1B,OAAO,EAAE,YAAY,CAAC;IACtB,mEAAmE;IACnE,gBAAgB,EAAE,oBAAoB,CAAC;IACvC,wEAAwE;IACxE,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAID,cAAc,4BAA4B,CAAC;AAC3C,YAAY,EACX,YAAY,EACZ,uBAAuB,EACvB,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,cAAc,GACd,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,YAAY,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACzC,YAAY,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAE7C,OAAO,EACN,qBAAqB,EAErB,iBAAiB,EACjB,mBAAmB,EACnB,cAAc,EACd,cAAc,EACd,cAAc,EACd,eAAe,EACf,cAAc,EACd,cAAc,EACd,YAAY,GACZ,CAAC;AAQF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,GAAE,yBAA8B,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAqOnH","sourcesContent":["import { join } from \"node:path\";\nimport { clampThinkingLevel, type Message, type Model, streamSimple } from \"@earendil-works/pi-ai/compat\";\nimport { Agent, type AgentMessage, setDefaultStreamFn, type ThinkingLevel } from \"apex-code-agent-core\";\nimport { getAgentDir } from \"../config.ts\";\nimport { resolvePath } from \"../utils/paths.ts\";\nimport { AgentSession } from \"./agent-session.ts\";\nimport { formatNoModelsAvailableMessage } from \"./auth-guidance.ts\";\nimport { DEFAULT_THINKING_LEVEL } from \"./defaults.ts\";\nimport type { ExtensionRunner, LoadExtensionsResult, SessionStartEvent, ToolDefinition } from \"./extensions/index.ts\";\nimport { convertToLlm } from \"./messages.ts\";\nimport { findInitialModel } from \"./model-resolver.ts\";\nimport { ModelRuntime } from \"./model-runtime.ts\";\nimport { mergeProviderAttributionHeaders } from \"./provider-attribution.ts\";\nimport type { ResourceLoader } from \"./resource-loader.ts\";\nimport { DefaultResourceLoader } from \"./resource-loader.ts\";\nimport { getDefaultSessionDir, SessionManager } from \"./session-manager.ts\";\nimport { SettingsManager } from \"./settings-manager.ts\";\nimport { time } from \"./timings.ts\";\nimport {\n\tcreateBashTool,\n\tcreateCodingTools,\n\tcreateEditTool,\n\tcreateFindTool,\n\tcreateGrepTool,\n\tcreateLsTool,\n\tcreateReadOnlyTools,\n\tcreateReadTool,\n\tcreateWriteTool,\n\ttype ToolName,\n\twithFileMutationQueue,\n} from \"./tools/index.ts\";\n\n// Preserve the pre-0.81 fallback for extensions that construct Agent instances\n// or invoke low-level agent loops without supplying streamFn. Agent core remains\n// provider-agnostic and does not import pi-ai/compat itself.\nsetDefaultStreamFn(streamSimple);\n\nexport interface CreateAgentSessionOptions {\n\t/** Working directory for project-local discovery. Default: process.cwd() */\n\tcwd?: string;\n\t/** Global config directory. Default: ~/.apex-code/agent */\n\tagentDir?: string;\n\n\t/** Canonical model/auth runtime. Defaults to a runtime using agentDir/auth.json and models.json. */\n\tmodelRuntime?: ModelRuntime;\n\n\t/** Model to use. Default: from settings, else first available */\n\tmodel?: Model<any>;\n\t/** Thinking level. Default: from settings, else 'medium' (clamped to model capabilities) */\n\tthinkingLevel?: ThinkingLevel;\n\t/** Models available for cycling (Ctrl+P in interactive mode) */\n\tscopedModels?: Array<{ model: Model<any>; thinkingLevel?: ThinkingLevel }>;\n\n\t/**\n\t * Optional default tool suppression mode when no explicit allowlist is provided.\n\t *\n\t * - \"all\": start with no tools enabled\n\t * - \"builtin\": disable the default built-in tools (read, bash, edit, write)\n\t *   but keep extension/custom tools enabled\n\t */\n\tnoTools?: \"all\" | \"builtin\";\n\t/**\n\t * Optional allowlist of tool names.\n\t *\n\t * When omitted, pi enables the default built-in tools (read, bash, edit, write)\n\t * and leaves extension/custom tools enabled unless `noTools` changes that default.\n\t * When provided, only the listed tool names are enabled.\n\t */\n\ttools?: string[];\n\t/** Optional denylist of tool names to disable. Applies after `tools` when both are provided. */\n\texcludeTools?: string[];\n\t/** Custom tools to register (in addition to built-in tools). */\n\tcustomTools?: ToolDefinition[];\n\n\t/** Resource loader. When omitted, DefaultResourceLoader is used. */\n\tresourceLoader?: ResourceLoader;\n\n\t/** Session manager. Default: SessionManager.create(cwd) */\n\tsessionManager?: SessionManager;\n\n\t/** Settings manager. Default: SettingsManager.create(cwd, agentDir) */\n\tsettingsManager?: SettingsManager;\n\t/** Session start event metadata for extension runtime startup. */\n\tsessionStartEvent?: SessionStartEvent;\n}\n\n/** Result from createAgentSession */\nexport interface CreateAgentSessionResult {\n\t/** The created session */\n\tsession: AgentSession;\n\t/** Extensions result (for UI context setup in interactive mode) */\n\textensionsResult: LoadExtensionsResult;\n\t/** Warning if session was restored with a different model than saved */\n\tmodelFallbackMessage?: string;\n}\n\n// Re-exports\n\nexport * from \"./agent-session-runtime.ts\";\nexport type {\n\tExtensionAPI,\n\tExtensionCommandContext,\n\tExtensionContext,\n\tExtensionFactory,\n\tInlineExtension,\n\tSlashCommandInfo,\n\tSlashCommandSource,\n\tToolDefinition,\n} from \"./extensions/index.ts\";\nexport type { PromptTemplate } from \"./prompt-templates.ts\";\nexport type { Skill } from \"./skills.ts\";\nexport type { Tool } from \"./tools/index.ts\";\n\nexport {\n\twithFileMutationQueue,\n\t// Tool factories (for custom cwd)\n\tcreateCodingTools,\n\tcreateReadOnlyTools,\n\tcreateReadTool,\n\tcreateBashTool,\n\tcreateEditTool,\n\tcreateWriteTool,\n\tcreateGrepTool,\n\tcreateFindTool,\n\tcreateLsTool,\n};\n\n// Helper Functions\n\nfunction getDefaultAgentDir(): string {\n\treturn getAgentDir();\n}\n\n/**\n * Create an AgentSession with the specified options.\n *\n * @example\n * ```typescript\n * // Minimal - uses defaults\n * const { session } = await createAgentSession();\n *\n * // With explicit model\n * import { getModel } from '@earendil-works/pi-ai';\n * const { session } = await createAgentSession({\n *   model: getModel('anthropic', 'claude-opus-4-5'),\n *   thinkingLevel: 'high',\n * });\n *\n * // Continue previous session\n * const { session, modelFallbackMessage } = await createAgentSession({\n *   continueSession: true,\n * });\n *\n * // Full control\n * const loader = new DefaultResourceLoader({\n *   cwd: process.cwd(),\n *   agentDir: getAgentDir(),\n *   settingsManager: SettingsManager.create(),\n * });\n * await loader.reload();\n * const { session } = await createAgentSession({\n *   model: myModel,\n *   tools: [\"read\", \"bash\"],\n *   resourceLoader: loader,\n *   sessionManager: SessionManager.inMemory(),\n * });\n * ```\n */\nexport async function createAgentSession(options: CreateAgentSessionOptions = {}): Promise<CreateAgentSessionResult> {\n\tconst cwd = resolvePath(options.cwd ?? options.sessionManager?.getCwd() ?? process.cwd());\n\tconst agentDir = options.agentDir ? resolvePath(options.agentDir) : getDefaultAgentDir();\n\tlet resourceLoader = options.resourceLoader;\n\n\tconst authPath = options.agentDir ? join(agentDir, \"auth.json\") : undefined;\n\tconst modelsPath = options.agentDir ? join(agentDir, \"models.json\") : undefined;\n\tconst modelRuntime = options.modelRuntime ?? (await ModelRuntime.create({ authPath, modelsPath }));\n\n\tconst settingsManager = options.settingsManager ?? SettingsManager.create(cwd, agentDir);\n\tconst sessionManager = options.sessionManager ?? SessionManager.create(cwd, getDefaultSessionDir(cwd, agentDir));\n\n\tif (!resourceLoader) {\n\t\tresourceLoader = new DefaultResourceLoader({ cwd, agentDir, settingsManager });\n\t\tawait resourceLoader.reload();\n\t\ttime(\"resourceLoader.reload\");\n\t}\n\n\t// Check if session has existing data to restore\n\tconst existingSession = sessionManager.buildSessionContext();\n\tconst hasExistingSession = existingSession.messages.length > 0;\n\tconst hasThinkingEntry = sessionManager.getBranch().some((entry) => entry.type === \"thinking_level_change\");\n\n\tlet model = options.model;\n\tlet modelFallbackMessage: string | undefined;\n\n\t// If session has data, try to restore model from it\n\tif (!model && hasExistingSession && existingSession.model) {\n\t\tconst restoredModel = modelRuntime.getModel(existingSession.model.provider, existingSession.model.modelId);\n\t\tif (restoredModel && modelRuntime.hasConfiguredAuth(restoredModel.provider)) {\n\t\t\tmodel = restoredModel;\n\t\t}\n\t\tif (!model) {\n\t\t\tmodelFallbackMessage = `Could not restore model ${existingSession.model.provider}/${existingSession.model.modelId}`;\n\t\t}\n\t}\n\n\t// If still no model, use findInitialModel (checks settings default, then provider defaults)\n\tif (!model) {\n\t\tconst result = await findInitialModel({\n\t\t\tscopedModels: [],\n\t\t\tisContinuing: hasExistingSession,\n\t\t\tdefaultProvider: settingsManager.getDefaultProvider(),\n\t\t\tdefaultModelId: settingsManager.getDefaultModel(),\n\t\t\tdefaultThinkingLevel: settingsManager.getDefaultThinkingLevel(),\n\t\t\tmodelRuntime,\n\t\t});\n\t\tmodel = result.model;\n\t\tif (!model) {\n\t\t\tmodelFallbackMessage = formatNoModelsAvailableMessage();\n\t\t} else if (modelFallbackMessage) {\n\t\t\tmodelFallbackMessage += `. Using ${model.provider}/${model.id}`;\n\t\t}\n\t}\n\n\tlet thinkingLevel = options.thinkingLevel;\n\n\t// If session has data, restore thinking level from it\n\tif (thinkingLevel === undefined && hasExistingSession) {\n\t\tthinkingLevel = hasThinkingEntry\n\t\t\t? (existingSession.thinkingLevel as ThinkingLevel)\n\t\t\t: (settingsManager.getDefaultThinkingLevel() ?? DEFAULT_THINKING_LEVEL);\n\t}\n\n\t// Fall back to settings default\n\tif (thinkingLevel === undefined) {\n\t\tthinkingLevel = settingsManager.getDefaultThinkingLevel() ?? DEFAULT_THINKING_LEVEL;\n\t}\n\n\t// Clamp to model capabilities\n\tif (!model) {\n\t\tthinkingLevel = \"off\";\n\t} else {\n\t\tthinkingLevel = clampThinkingLevel(model, thinkingLevel) as ThinkingLevel;\n\t}\n\n\tconst defaultActiveToolNames: ToolName[] = [\"read\", \"bash\", \"edit\", \"write\"];\n\tconst allowedToolNames = options.tools ?? (options.noTools === \"all\" ? [] : undefined);\n\tconst excludedToolNames = options.excludeTools;\n\tconst excludedToolNameSet = excludedToolNames ? new Set(excludedToolNames) : undefined;\n\tconst initialActiveToolNames: string[] = (\n\t\toptions.tools ? [...options.tools] : options.noTools ? [] : defaultActiveToolNames\n\t).filter((name) => !excludedToolNameSet?.has(name));\n\n\tlet agent: Agent;\n\n\t// Create convertToLlm wrapper that filters images if blockImages is enabled (defense-in-depth)\n\tconst convertToLlmWithBlockImages = (messages: AgentMessage[]): Message[] => {\n\t\tconst converted = convertToLlm(messages);\n\t\t// Check setting dynamically so mid-session changes take effect\n\t\tif (!settingsManager.getBlockImages()) {\n\t\t\treturn converted;\n\t\t}\n\t\t// Filter out ImageContent from all messages, replacing with text placeholder\n\t\treturn converted.map((msg) => {\n\t\t\tif (msg.role === \"user\" || msg.role === \"toolResult\") {\n\t\t\t\tconst content = msg.content;\n\t\t\t\tif (Array.isArray(content)) {\n\t\t\t\t\tconst hasImages = content.some((c) => c.type === \"image\");\n\t\t\t\t\tif (hasImages) {\n\t\t\t\t\t\tconst filteredContent = content\n\t\t\t\t\t\t\t.map((c) =>\n\t\t\t\t\t\t\t\tc.type === \"image\" ? { type: \"text\" as const, text: \"Image reading is disabled.\" } : c,\n\t\t\t\t\t\t\t)\n\t\t\t\t\t\t\t.filter(\n\t\t\t\t\t\t\t\t(c, i, arr) =>\n\t\t\t\t\t\t\t\t\t// Dedupe consecutive \"Image reading is disabled.\" texts\n\t\t\t\t\t\t\t\t\t!(\n\t\t\t\t\t\t\t\t\t\tc.type === \"text\" &&\n\t\t\t\t\t\t\t\t\t\tc.text === \"Image reading is disabled.\" &&\n\t\t\t\t\t\t\t\t\t\ti > 0 &&\n\t\t\t\t\t\t\t\t\t\tarr[i - 1].type === \"text\" &&\n\t\t\t\t\t\t\t\t\t\t(arr[i - 1] as { type: \"text\"; text: string }).text === \"Image reading is disabled.\"\n\t\t\t\t\t\t\t\t\t),\n\t\t\t\t\t\t\t);\n\t\t\t\t\t\treturn { ...msg, content: filteredContent };\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn msg;\n\t\t});\n\t};\n\n\tconst extensionRunnerRef: { current?: ExtensionRunner } = {};\n\n\tagent = new Agent({\n\t\tinitialState: {\n\t\t\tsystemPrompt: \"\",\n\t\t\tmodel,\n\t\t\tthinkingLevel,\n\t\t\ttools: [],\n\t\t},\n\t\tconvertToLlm: convertToLlmWithBlockImages,\n\t\tstreamFn: async (model, context, options) => {\n\t\t\tconst providerRetrySettings = settingsManager.getProviderRetrySettings();\n\t\t\tconst httpIdleTimeoutMs = settingsManager.getHttpIdleTimeoutMs();\n\t\t\t// SDKs treat timeout=0 as 0ms (immediate timeout), not \"no timeout\".\n\t\t\t// Use max int32 to effectively disable the timeout.\n\t\t\tconst effectiveTimeoutMs = httpIdleTimeoutMs === 0 ? 2147483647 : httpIdleTimeoutMs;\n\t\t\tconst timeoutMs = options?.timeoutMs ?? providerRetrySettings.timeoutMs ?? effectiveTimeoutMs;\n\t\t\tconst websocketConnectTimeoutMs =\n\t\t\t\toptions?.websocketConnectTimeoutMs ?? settingsManager.getWebSocketConnectTimeoutMs();\n\t\t\tconst headerRunner = extensionRunnerRef.current;\n\t\t\treturn modelRuntime.streamSimple(model, context, {\n\t\t\t\t...options,\n\t\t\t\ttimeoutMs,\n\t\t\t\twebsocketConnectTimeoutMs,\n\t\t\t\tmaxRetries: options?.maxRetries ?? providerRetrySettings.maxRetries,\n\t\t\t\tmaxRetryDelayMs: options?.maxRetryDelayMs ?? providerRetrySettings.maxRetryDelayMs,\n\t\t\t\ttransformHeaders: async (requestHeaders) => {\n\t\t\t\t\tconst headers = mergeProviderAttributionHeaders(\n\t\t\t\t\t\tmodel,\n\t\t\t\t\t\tsettingsManager,\n\t\t\t\t\t\toptions?.sessionId,\n\t\t\t\t\t\trequestHeaders,\n\t\t\t\t\t);\n\t\t\t\t\treturn headerRunner?.hasHandlers(\"before_provider_headers\")\n\t\t\t\t\t\t? headerRunner.emitBeforeProviderHeaders(headers ?? {})\n\t\t\t\t\t\t: (headers ?? {});\n\t\t\t\t},\n\t\t\t});\n\t\t},\n\t\tonPayload: async (payload, _model) => {\n\t\t\tconst runner = extensionRunnerRef.current;\n\t\t\tif (!runner?.hasHandlers(\"before_provider_request\")) {\n\t\t\t\treturn payload;\n\t\t\t}\n\t\t\treturn runner.emitBeforeProviderRequest(payload);\n\t\t},\n\t\tonResponse: async (response, _model) => {\n\t\t\tconst runner = extensionRunnerRef.current;\n\t\t\tif (!runner?.hasHandlers(\"after_provider_response\")) {\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tawait runner.emit({\n\t\t\t\ttype: \"after_provider_response\",\n\t\t\t\tstatus: response.status,\n\t\t\t\theaders: response.headers,\n\t\t\t});\n\t\t},\n\t\tsessionId: sessionManager.getSessionId(),\n\t\ttransformContext: async (messages) => {\n\t\t\tconst runner = extensionRunnerRef.current;\n\t\t\tif (!runner) return messages;\n\t\t\treturn runner.emitContext(messages);\n\t\t},\n\t\tsteeringMode: settingsManager.getSteeringMode(),\n\t\tfollowUpMode: settingsManager.getFollowUpMode(),\n\t\ttransport: settingsManager.getTransport(),\n\t\tthinkingBudgets: settingsManager.getThinkingBudgets(),\n\t\tmaxRetryDelayMs: settingsManager.getProviderRetrySettings().maxRetryDelayMs,\n\t});\n\n\t// Restore messages if session has existing data\n\tif (hasExistingSession) {\n\t\tagent.state.messages = existingSession.messages;\n\t\tif (!hasThinkingEntry) {\n\t\t\tsessionManager.appendThinkingLevelChange(thinkingLevel);\n\t\t}\n\t} else {\n\t\t// Save initial model and thinking level for new sessions so they can be restored on resume\n\t\tif (model) {\n\t\t\tsessionManager.appendModelChange(model.provider, model.id);\n\t\t}\n\t\tsessionManager.appendThinkingLevelChange(thinkingLevel);\n\t}\n\n\tconst session = new AgentSession({\n\t\tagent,\n\t\tsessionManager,\n\t\tsettingsManager,\n\t\tcwd,\n\t\tscopedModels: options.scopedModels,\n\t\tresourceLoader,\n\t\tcustomTools: options.customTools,\n\t\tmodelRuntime,\n\t\tinitialActiveToolNames,\n\t\tallowedToolNames,\n\t\texcludedToolNames,\n\t\textensionRunnerRef,\n\t\tsessionStartEvent: options.sessionStartEvent,\n\t});\n\tconst extensionsResult = resourceLoader.getExtensions();\n\n\treturn {\n\t\tsession,\n\t\textensionsResult,\n\t\tmodelFallbackMessage,\n\t};\n}\n"]}
+{"version":3,"file":"sdk.d.ts","sourceRoot":"","sources":["../../src/core/sdk.ts"],"names":[],"mappings":"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","sourcesContent":["import { join } from \"node:path\";\nimport { clampThinkingLevel, type Message, type Model, streamSimple } from \"@earendil-works/pi-ai/compat\";\nimport { Agent, type AgentMessage, setDefaultStreamFn, type ThinkingLevel } from \"apex-code-agent-core\";\nimport { getAgentDir } from \"../config.ts\";\nimport { resolvePath } from \"../utils/paths.ts\";\nimport { AgentSession, type AgentSessionConfig } from \"./agent-session.ts\";\nimport { formatNoModelsAvailableMessage } from \"./auth-guidance.ts\";\nimport { DEFAULT_THINKING_LEVEL } from \"./defaults.ts\";\nimport { createAgentDefinitionResolver } from \"./delegation/agents.ts\";\nimport type { AgentDefinitionResolver, DelegationRuntimeOptions } from \"./delegation/runtime.ts\";\nimport type { ExtensionRunner, LoadExtensionsResult, SessionStartEvent, ToolDefinition } from \"./extensions/index.ts\";\nimport { convertToLlm } from \"./messages.ts\";\nimport { findInitialModel } from \"./model-resolver.ts\";\nimport { ModelRuntime } from \"./model-runtime.ts\";\nimport { DerivedPermissionRuleStore } from \"./permissions/store.ts\";\nimport { mergeProviderAttributionHeaders } from \"./provider-attribution.ts\";\nimport type { ResourceLoader } from \"./resource-loader.ts\";\nimport { DefaultResourceLoader } from \"./resource-loader.ts\";\nimport { getDefaultSessionDir, SessionManager } from \"./session-manager.ts\";\nimport { SettingsManager } from \"./settings-manager.ts\";\nimport { time } from \"./timings.ts\";\nimport type { ApexToolDefinition, Capability, EvidenceSink } from \"./tools/contract.ts\";\nimport {\n\tcreateAllToolDefinitions,\n\tcreateBashTool,\n\tcreateCodingTools,\n\tcreateDelegateToolDefinition,\n\tcreateEditTool,\n\tcreateFindTool,\n\tcreateGrepTool,\n\tcreateLsTool,\n\tcreateReadOnlyTools,\n\tcreateReadTool,\n\tcreateWriteTool,\n\ttype ToolName,\n\twithFileMutationQueue,\n} from \"./tools/index.ts\";\n\n// Preserve the pre-0.81 fallback for extensions that construct Agent instances\n// or invoke low-level agent loops without supplying streamFn. Agent core remains\n// provider-agnostic and does not import pi-ai/compat itself.\nsetDefaultStreamFn(streamSimple);\n\nexport interface CreateAgentSessionOptions {\n\t/** Working directory for project-local discovery. Default: process.cwd() */\n\tcwd?: string;\n\t/** Global config directory. Default: ~/.apex-code/agent */\n\tagentDir?: string;\n\n\t/** Canonical model/auth runtime. Defaults to a runtime using agentDir/auth.json and models.json. */\n\tmodelRuntime?: ModelRuntime;\n\n\t/** Model to use. Default: from settings, else first available */\n\tmodel?: Model<any>;\n\t/** Thinking level. Default: from settings, else 'medium' (clamped to model capabilities) */\n\tthinkingLevel?: ThinkingLevel;\n\t/** Models available for cycling (Ctrl+P in interactive mode) */\n\tscopedModels?: Array<{ model: Model<any>; thinkingLevel?: ThinkingLevel }>;\n\n\t/**\n\t * Optional default tool suppression mode when no explicit allowlist is provided.\n\t *\n\t * - \"all\": start with no tools enabled\n\t * - \"builtin\": disable the default built-in tools (read, bash, edit, write)\n\t *   but keep extension/custom tools enabled\n\t */\n\tnoTools?: \"all\" | \"builtin\";\n\t/**\n\t * Optional allowlist of tool names.\n\t *\n\t * When omitted, pi enables the default built-in tools (read, bash, edit, write)\n\t * and leaves extension/custom tools enabled unless `noTools` changes that default.\n\t * When provided, only the listed tool names are enabled.\n\t */\n\ttools?: string[];\n\t/** Optional denylist of tool names to disable. Applies after `tools` when both are provided. */\n\texcludeTools?: string[];\n\t/** Custom tools to register (in addition to built-in tools). */\n\tcustomTools?: ToolDefinition[];\n\n\t/** Resource loader. When omitted, DefaultResourceLoader is used. */\n\tresourceLoader?: ResourceLoader;\n\n\t/** Session manager. Default: SessionManager.create(cwd) */\n\tsessionManager?: SessionManager;\n\n\t/** Settings manager. Default: SettingsManager.create(cwd, agentDir) */\n\tsettingsManager?: SettingsManager;\n\t/** Session start event metadata for extension runtime startup. */\n\tsessionStartEvent?: SessionStartEvent;\n\t/** Authorization configuration for every registered tool call. */\n\tpermissionGate?: AgentSessionConfig[\"permissionGate\"];\n\t/** Optional destination for source-level evidence; defaults to the durable session sink. */\n\tevidenceSink?: EvidenceSink;\n\t/**\n\t * Delegation entry point (roadmap Phase 5, ADR 0008). When set, `delegate`\n\t * executes real child sessions through `resolveAgent`, with the child's\n\t * authority derived from this session's live active tools and permission\n\t * store -- never reconstructed. When omitted, `delegate` stays inert (no agent\n\t * types resolve). Agent discovery is injected here as a caller-supplied\n\t * resolver rather than built in, until Phase 5 task 5.5 lands real\n\t * markdown/frontmatter discovery. Requires `permissionGate` to be set too: a\n\t * child's authority has nothing to derive from otherwise.\n\t */\n\tdelegation?: { resolveAgent?: AgentDefinitionResolver };\n}\n\n/** Result from createAgentSession */\nexport interface CreateAgentSessionResult {\n\t/** The created session */\n\tsession: AgentSession;\n\t/** Extensions result (for UI context setup in interactive mode) */\n\textensionsResult: LoadExtensionsResult;\n\t/** Warning if session was restored with a different model than saved */\n\tmodelFallbackMessage?: string;\n}\n\n// Re-exports\n\nexport * from \"./agent-session-runtime.ts\";\nexport type {\n\tExtensionAPI,\n\tExtensionCommandContext,\n\tExtensionContext,\n\tExtensionFactory,\n\tInlineExtension,\n\tSlashCommandInfo,\n\tSlashCommandSource,\n\tToolDefinition,\n} from \"./extensions/index.ts\";\nexport type { PromptTemplate } from \"./prompt-templates.ts\";\nexport type { Skill } from \"./skills.ts\";\nexport type { Tool } from \"./tools/index.ts\";\n\nexport {\n\twithFileMutationQueue,\n\t// Tool factories (for custom cwd)\n\tcreateCodingTools,\n\tcreateReadOnlyTools,\n\tcreateReadTool,\n\tcreateBashTool,\n\tcreateEditTool,\n\tcreateWriteTool,\n\tcreateGrepTool,\n\tcreateFindTool,\n\tcreateLsTool,\n};\n\n// Helper Functions\n\nfunction getDefaultAgentDir(): string {\n\treturn getAgentDir();\n}\n\n/**\n * Create an AgentSession with the specified options.\n *\n * @example\n * ```typescript\n * // Minimal - uses defaults\n * const { session } = await createAgentSession();\n *\n * // With explicit model\n * import { getModel } from '@earendil-works/pi-ai';\n * const { session } = await createAgentSession({\n *   model: getModel('anthropic', 'claude-opus-4-5'),\n *   thinkingLevel: 'high',\n * });\n *\n * // Continue previous session\n * const { session, modelFallbackMessage } = await createAgentSession({\n *   continueSession: true,\n * });\n *\n * // Full control\n * const loader = new DefaultResourceLoader({\n *   cwd: process.cwd(),\n *   agentDir: getAgentDir(),\n *   settingsManager: SettingsManager.create(),\n * });\n * await loader.reload();\n * const { session } = await createAgentSession({\n *   model: myModel,\n *   tools: [\"read\", \"bash\"],\n *   resourceLoader: loader,\n *   sessionManager: SessionManager.inMemory(),\n * });\n * ```\n */\n/** The most recent assistant text in a completed session -- what a delegated child returns to its parent as its result. */\nfunction extractFinalAssistantText(session: AgentSession): string {\n\tconst messages = session.agent.state.messages;\n\tfor (let i = messages.length - 1; i >= 0; i--) {\n\t\tconst message = messages[i];\n\t\tif (message.role !== \"assistant\") continue;\n\t\tconst text = message.content\n\t\t\t.filter(\n\t\t\t\t(content): content is Extract<AgentMessage, { role: \"assistant\" }>[\"content\"][number] & { type: \"text\" } =>\n\t\t\t\t\tcontent.type === \"text\",\n\t\t\t)\n\t\t\t.map((content) => content.text)\n\t\t\t.join(\"\\n\");\n\t\tif (text) return text;\n\t}\n\treturn \"\";\n}\n\nexport async function createAgentSession(options: CreateAgentSessionOptions = {}): Promise<CreateAgentSessionResult> {\n\tconst cwd = resolvePath(options.cwd ?? options.sessionManager?.getCwd() ?? process.cwd());\n\tconst agentDir = options.agentDir ? resolvePath(options.agentDir) : getDefaultAgentDir();\n\tlet resourceLoader = options.resourceLoader;\n\n\tconst authPath = options.agentDir ? join(agentDir, \"auth.json\") : undefined;\n\tconst modelsPath = options.agentDir ? join(agentDir, \"models.json\") : undefined;\n\tconst modelRuntime = options.modelRuntime ?? (await ModelRuntime.create({ authPath, modelsPath }));\n\n\tconst settingsManager = options.settingsManager ?? SettingsManager.create(cwd, agentDir);\n\tconst sessionManager = options.sessionManager ?? SessionManager.create(cwd, getDefaultSessionDir(cwd, agentDir));\n\n\tif (!resourceLoader) {\n\t\tresourceLoader = new DefaultResourceLoader({ cwd, agentDir, settingsManager });\n\t\tawait resourceLoader.reload();\n\t\ttime(\"resourceLoader.reload\");\n\t}\n\n\t// Check if session has existing data to restore\n\tconst existingSession = sessionManager.buildSessionContext();\n\tconst hasExistingSession = existingSession.messages.length > 0;\n\tconst hasThinkingEntry = sessionManager.getBranch().some((entry) => entry.type === \"thinking_level_change\");\n\n\tlet model = options.model;\n\tlet modelFallbackMessage: string | undefined;\n\n\t// If session has data, try to restore model from it\n\tif (!model && hasExistingSession && existingSession.model) {\n\t\tconst restoredModel = modelRuntime.getModel(existingSession.model.provider, existingSession.model.modelId);\n\t\tif (restoredModel && modelRuntime.hasConfiguredAuth(restoredModel.provider)) {\n\t\t\tmodel = restoredModel;\n\t\t}\n\t\tif (!model) {\n\t\t\tmodelFallbackMessage = `Could not restore model ${existingSession.model.provider}/${existingSession.model.modelId}`;\n\t\t}\n\t}\n\n\t// If still no model, use findInitialModel (checks settings default, then provider defaults)\n\tif (!model) {\n\t\tconst result = await findInitialModel({\n\t\t\tscopedModels: [],\n\t\t\tisContinuing: hasExistingSession,\n\t\t\tdefaultProvider: settingsManager.getDefaultProvider(),\n\t\t\tdefaultModelId: settingsManager.getDefaultModel(),\n\t\t\tdefaultThinkingLevel: settingsManager.getDefaultThinkingLevel(),\n\t\t\tmodelRuntime,\n\t\t});\n\t\tmodel = result.model;\n\t\tif (!model) {\n\t\t\tmodelFallbackMessage = formatNoModelsAvailableMessage();\n\t\t} else if (modelFallbackMessage) {\n\t\t\tmodelFallbackMessage += `. Using ${model.provider}/${model.id}`;\n\t\t}\n\t}\n\n\tlet thinkingLevel = options.thinkingLevel;\n\n\t// If session has data, restore thinking level from it\n\tif (thinkingLevel === undefined && hasExistingSession) {\n\t\tthinkingLevel = hasThinkingEntry\n\t\t\t? (existingSession.thinkingLevel as ThinkingLevel)\n\t\t\t: (settingsManager.getDefaultThinkingLevel() ?? DEFAULT_THINKING_LEVEL);\n\t}\n\n\t// Fall back to settings default\n\tif (thinkingLevel === undefined) {\n\t\tthinkingLevel = settingsManager.getDefaultThinkingLevel() ?? DEFAULT_THINKING_LEVEL;\n\t}\n\n\t// Clamp to model capabilities\n\tif (!model) {\n\t\tthinkingLevel = \"off\";\n\t} else {\n\t\tthinkingLevel = clampThinkingLevel(model, thinkingLevel) as ThinkingLevel;\n\t}\n\n\tconst defaultActiveToolNames: ToolName[] = [\"read\", \"bash\", \"edit\", \"write\"];\n\tconst allowedToolNames = options.tools ?? (options.noTools === \"all\" ? [] : undefined);\n\tconst excludedToolNames = options.excludeTools;\n\tconst excludedToolNameSet = excludedToolNames ? new Set(excludedToolNames) : undefined;\n\tconst initialActiveToolNames: string[] = (\n\t\toptions.tools ? [...options.tools] : options.noTools ? [] : defaultActiveToolNames\n\t).filter((name) => !excludedToolNameSet?.has(name));\n\n\tlet agent: Agent;\n\n\t// Create convertToLlm wrapper that filters images if blockImages is enabled (defense-in-depth)\n\tconst convertToLlmWithBlockImages = (messages: AgentMessage[]): Message[] => {\n\t\tconst converted = convertToLlm(messages);\n\t\t// Check setting dynamically so mid-session changes take effect\n\t\tif (!settingsManager.getBlockImages()) {\n\t\t\treturn converted;\n\t\t}\n\t\t// Filter out ImageContent from all messages, replacing with text placeholder\n\t\treturn converted.map((msg) => {\n\t\t\tif (msg.role === \"user\" || msg.role === \"toolResult\") {\n\t\t\t\tconst content = msg.content;\n\t\t\t\tif (Array.isArray(content)) {\n\t\t\t\t\tconst hasImages = content.some((c) => c.type === \"image\");\n\t\t\t\t\tif (hasImages) {\n\t\t\t\t\t\tconst filteredContent = content\n\t\t\t\t\t\t\t.map((c) =>\n\t\t\t\t\t\t\t\tc.type === \"image\" ? { type: \"text\" as const, text: \"Image reading is disabled.\" } : c,\n\t\t\t\t\t\t\t)\n\t\t\t\t\t\t\t.filter(\n\t\t\t\t\t\t\t\t(c, i, arr) =>\n\t\t\t\t\t\t\t\t\t// Dedupe consecutive \"Image reading is disabled.\" texts\n\t\t\t\t\t\t\t\t\t!(\n\t\t\t\t\t\t\t\t\t\tc.type === \"text\" &&\n\t\t\t\t\t\t\t\t\t\tc.text === \"Image reading is disabled.\" &&\n\t\t\t\t\t\t\t\t\t\ti > 0 &&\n\t\t\t\t\t\t\t\t\t\tarr[i - 1].type === \"text\" &&\n\t\t\t\t\t\t\t\t\t\t(arr[i - 1] as { type: \"text\"; text: string }).text === \"Image reading is disabled.\"\n\t\t\t\t\t\t\t\t\t),\n\t\t\t\t\t\t\t);\n\t\t\t\t\t\treturn { ...msg, content: filteredContent };\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn msg;\n\t\t});\n\t};\n\n\tconst extensionRunnerRef: { current?: ExtensionRunner } = {};\n\n\tagent = new Agent({\n\t\tinitialState: {\n\t\t\tsystemPrompt: \"\",\n\t\t\tmodel,\n\t\t\tthinkingLevel,\n\t\t\ttools: [],\n\t\t},\n\t\tconvertToLlm: convertToLlmWithBlockImages,\n\t\tstreamFn: async (model, context, options) => {\n\t\t\tconst providerRetrySettings = settingsManager.getProviderRetrySettings();\n\t\t\tconst httpIdleTimeoutMs = settingsManager.getHttpIdleTimeoutMs();\n\t\t\t// SDKs treat timeout=0 as 0ms (immediate timeout), not \"no timeout\".\n\t\t\t// Use max int32 to effectively disable the timeout.\n\t\t\tconst effectiveTimeoutMs = httpIdleTimeoutMs === 0 ? 2147483647 : httpIdleTimeoutMs;\n\t\t\tconst timeoutMs = options?.timeoutMs ?? providerRetrySettings.timeoutMs ?? effectiveTimeoutMs;\n\t\t\tconst websocketConnectTimeoutMs =\n\t\t\t\toptions?.websocketConnectTimeoutMs ?? settingsManager.getWebSocketConnectTimeoutMs();\n\t\t\tconst headerRunner = extensionRunnerRef.current;\n\t\t\treturn modelRuntime.streamSimple(model, context, {\n\t\t\t\t...options,\n\t\t\t\ttimeoutMs,\n\t\t\t\twebsocketConnectTimeoutMs,\n\t\t\t\tmaxRetries: options?.maxRetries ?? providerRetrySettings.maxRetries,\n\t\t\t\tmaxRetryDelayMs: options?.maxRetryDelayMs ?? providerRetrySettings.maxRetryDelayMs,\n\t\t\t\ttransformHeaders: async (requestHeaders) => {\n\t\t\t\t\tconst headers = mergeProviderAttributionHeaders(\n\t\t\t\t\t\tmodel,\n\t\t\t\t\t\tsettingsManager,\n\t\t\t\t\t\toptions?.sessionId,\n\t\t\t\t\t\trequestHeaders,\n\t\t\t\t\t);\n\t\t\t\t\treturn headerRunner?.hasHandlers(\"before_provider_headers\")\n\t\t\t\t\t\t? headerRunner.emitBeforeProviderHeaders(headers ?? {})\n\t\t\t\t\t\t: (headers ?? {});\n\t\t\t\t},\n\t\t\t});\n\t\t},\n\t\tonPayload: async (payload, _model) => {\n\t\t\tconst runner = extensionRunnerRef.current;\n\t\t\tif (!runner?.hasHandlers(\"before_provider_request\")) {\n\t\t\t\treturn payload;\n\t\t\t}\n\t\t\treturn runner.emitBeforeProviderRequest(payload);\n\t\t},\n\t\tonResponse: async (response, _model) => {\n\t\t\tconst runner = extensionRunnerRef.current;\n\t\t\tif (!runner?.hasHandlers(\"after_provider_response\")) {\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tawait runner.emit({\n\t\t\t\ttype: \"after_provider_response\",\n\t\t\t\tstatus: response.status,\n\t\t\t\theaders: response.headers,\n\t\t\t});\n\t\t},\n\t\tsessionId: sessionManager.getSessionId(),\n\t\ttransformContext: async (messages) => {\n\t\t\tconst runner = extensionRunnerRef.current;\n\t\t\tif (!runner) return messages;\n\t\t\treturn runner.emitContext(messages);\n\t\t},\n\t\tsteeringMode: settingsManager.getSteeringMode(),\n\t\tfollowUpMode: settingsManager.getFollowUpMode(),\n\t\ttransport: settingsManager.getTransport(),\n\t\tthinkingBudgets: settingsManager.getThinkingBudgets(),\n\t\tmaxRetryDelayMs: settingsManager.getProviderRetrySettings().maxRetryDelayMs,\n\t});\n\n\t// Restore messages if session has existing data\n\tif (hasExistingSession) {\n\t\tagent.state.messages = existingSession.messages;\n\t\tif (!hasThinkingEntry) {\n\t\t\tsessionManager.appendThinkingLevelChange(thinkingLevel);\n\t\t}\n\t} else {\n\t\t// Save initial model and thinking level for new sessions so they can be restored on resume\n\t\tif (model) {\n\t\t\tsessionManager.appendModelChange(model.provider, model.id);\n\t\t}\n\t\tsessionManager.appendThinkingLevelChange(thinkingLevel);\n\t}\n\n\t// Forward ref, mirroring extensionRunnerRef above: the delegation runtime's\n\t// closures are needed to build `customTools` before `session` exists, but they\n\t// must read the *live* session (active tools can change after construction),\n\t// not a snapshot frozen at this point.\n\tconst parentSessionRef: { current?: AgentSession } = {};\n\tconst customTools: ToolDefinition[] = options.customTools ? [...options.customTools] : [];\n\t// A configured permission gate supplies the authority a child must derive, so\n\t// discovery is enabled by default in real sessions. Callers that need fixture\n\t// definitions may still provide an explicit resolver.\n\tconst delegation = options.delegation ?? (options.permissionGate ? {} : undefined);\n\tif (delegation) {\n\t\tconst parentPermissionGate = options.permissionGate;\n\t\tconst resolveAgent =\n\t\t\tdelegation.resolveAgent ??\n\t\t\tcreateAgentDefinitionResolver({\n\t\t\t\tcwd,\n\t\t\t\tagentDir,\n\t\t\t\tisProjectTrusted: () => settingsManager.isProjectTrusted(),\n\t\t\t});\n\t\tconst delegationRuntime: DelegationRuntimeOptions = {\n\t\t\tresolveAgent,\n\t\t\tgetParentCapabilities: () => {\n\t\t\t\tconst capabilities = new Set<Capability>();\n\t\t\t\tfor (const name of parentSessionRef.current?.getActiveToolNames() ?? []) {\n\t\t\t\t\tconst contract = (\n\t\t\t\t\t\tparentSessionRef.current?.getToolDefinition(name) as Partial<ApexToolDefinition> | undefined\n\t\t\t\t\t)?.contract;\n\t\t\t\t\tif (contract) for (const capability of contract.capabilities) capabilities.add(capability);\n\t\t\t\t}\n\t\t\t\treturn capabilities;\n\t\t\t},\n\t\t\tgetToolCapabilities: (toolName) => {\n\t\t\t\t// Prefer the parent's own live registry first (it also covers\n\t\t\t\t// extension/custom tools an agent definition might name), but fall back\n\t\t\t\t// to the canonical built-in registry: \"what capability does tool X\n\t\t\t\t// need\" is a property of the tool itself, independent of whether the\n\t\t\t\t// parent's own session restricted it out of its active/allowed set via\n\t\t\t\t// `tools`/`excludeTools` -- that restriction affects the parent's own\n\t\t\t\t// *authority* (getParentCapabilities, above), not what a named tool is.\n\t\t\t\tconst fromParent = (\n\t\t\t\t\tparentSessionRef.current?.getToolDefinition(toolName) as Partial<ApexToolDefinition> | undefined\n\t\t\t\t)?.contract?.capabilities;\n\t\t\t\tif (fromParent) return fromParent;\n\t\t\t\treturn (createAllToolDefinitions(cwd)[toolName as ToolName] as ApexToolDefinition | undefined)?.contract\n\t\t\t\t\t?.capabilities;\n\t\t\t},\n\t\t\t// Read fresh each call, not captured once: depth is a live property of\n\t\t\t// the (possibly delegated) session this createAgentSession call is\n\t\t\t// building, via the same sessionManager this closure already captures.\n\t\t\tgetDelegationDepth: () => sessionManager.getDelegationDepth(),\n\t\t\tmaxDelegationDepth: settingsManager.getDelegationMaxDepth(),\n\t\t\tgetParentSessionDir: () => sessionManager.getSessionDir(),\n\t\t\tbuildChildSession: async ({ definition, toolNames, depth, sessionId, artifactDir }) => {\n\t\t\t\tif (!parentPermissionGate) {\n\t\t\t\t\tthrow new Error(\"delegate requires a permission gate configured on the parent session (ADR 0008).\");\n\t\t\t\t}\n\t\t\t\tconst childModel =\n\t\t\t\t\t(definition.model && modelRuntime.getAvailableSnapshot().find((m) => m.id === definition.model)) ||\n\t\t\t\t\tmodel;\n\t\t\t\tif (!childModel) {\n\t\t\t\t\tthrow new Error(`Cannot delegate to \"${definition.name}\": no model is available for the child session.`);\n\t\t\t\t}\n\t\t\t\tconst childSessionManager = artifactDir\n\t\t\t\t\t? SessionManager.create(cwd, artifactDir, {\n\t\t\t\t\t\t\tid: sessionId,\n\t\t\t\t\t\t\tparentSession: sessionManager.getSessionId(),\n\t\t\t\t\t\t\tdelegationDepth: depth,\n\t\t\t\t\t\t})\n\t\t\t\t\t: SessionManager.inMemory(cwd, {\n\t\t\t\t\t\t\tparentSession: sessionManager.getSessionId(),\n\t\t\t\t\t\t\tdelegationDepth: depth,\n\t\t\t\t\t\t});\n\t\t\t\tconst derivedStore = new DerivedPermissionRuleStore({ parent: parentPermissionGate.store });\n\t\t\t\tconst { session: childSession } = await createAgentSession({\n\t\t\t\t\tcwd,\n\t\t\t\t\tagentDir,\n\t\t\t\t\tmodel: childModel,\n\t\t\t\t\tmodelRuntime,\n\t\t\t\t\tsettingsManager,\n\t\t\t\t\tsessionManager: childSessionManager,\n\t\t\t\t\tresourceLoader,\n\t\t\t\t\ttools: toolNames,\n\t\t\t\t\t// No responder: a child's `ask` fails closed rather than prompting the\n\t\t\t\t\t// human for a call the human did not make (ADR 0008, \"Who answers a\n\t\t\t\t\t// child's ask\").\n\t\t\t\t\tpermissionGate: { store: derivedStore, getMode: parentPermissionGate.getMode },\n\t\t\t\t\t// Forwarded so a child that itself holds `delegate` can delegate again\n\t\t\t\t\t// (bounded by the depth guard above, read fresh from its own session\n\t\t\t\t\t// header on its next createAgentSession call) -- otherwise recursion\n\t\t\t\t\t// would be silently capped at one level regardless of maxDelegationDepth.\n\t\t\t\t\tdelegation,\n\t\t\t\t});\n\t\t\t\tawait childSession.bindExtensions({});\n\t\t\t\treturn {\n\t\t\t\t\tasync run(task: string) {\n\t\t\t\t\t\tconst prompt = definition.systemPrompt\n\t\t\t\t\t\t\t? `${definition.systemPrompt}\\n\\nTask: ${task}`\n\t\t\t\t\t\t\t: `Task: ${task}`;\n\t\t\t\t\t\tawait childSession.prompt(prompt);\n\t\t\t\t\t\treturn { output: extractFinalAssistantText(childSession) };\n\t\t\t\t\t},\n\t\t\t\t\tdispose() {\n\t\t\t\t\t\tchildSession.dispose();\n\t\t\t\t\t},\n\t\t\t\t};\n\t\t\t},\n\t\t};\n\t\tcustomTools.push(createDelegateToolDefinition(delegationRuntime) as ToolDefinition<any, any>);\n\t}\n\n\tconst session = new AgentSession({\n\t\tagent,\n\t\tsessionManager,\n\t\tsettingsManager,\n\t\tcwd,\n\t\tscopedModels: options.scopedModels,\n\t\tresourceLoader,\n\t\tcustomTools,\n\t\tmodelRuntime,\n\t\tinitialActiveToolNames,\n\t\tallowedToolNames,\n\t\texcludedToolNames,\n\t\textensionRunnerRef,\n\t\tsessionStartEvent: options.sessionStartEvent,\n\t\tpermissionGate: options.permissionGate,\n\t\tevidenceSink: options.evidenceSink,\n\t});\n\tparentSessionRef.current = session;\n\tconst extensionsResult = resourceLoader.getExtensions();\n\n\treturn {\n\t\tsession,\n\t\textensionsResult,\n\t\tmodelFallbackMessage,\n\t};\n}\n"]}

package/dist/core/sdk.js

@@ -6,15 +6,17 @@ import { resolvePath } from "../utils/paths.js";
 import { AgentSession } from "./agent-session.js";
 import { formatNoModelsAvailableMessage } from "./auth-guidance.js";
 import { DEFAULT_THINKING_LEVEL } from "./defaults.js";
+import { createAgentDefinitionResolver } from "./delegation/agents.js";
 import { convertToLlm } from "./messages.js";
 import { findInitialModel } from "./model-resolver.js";
 import { ModelRuntime } from "./model-runtime.js";
+import { DerivedPermissionRuleStore } from "./permissions/store.js";
 import { mergeProviderAttributionHeaders } from "./provider-attribution.js";
 import { DefaultResourceLoader } from "./resource-loader.js";
 import { getDefaultSessionDir, SessionManager } from "./session-manager.js";
 import { SettingsManager } from "./settings-manager.js";
 import { time } from "./timings.js";
-import { createBashTool, createCodingTools, createEditTool, createFindTool, createGrepTool, createLsTool, createReadOnlyTools, createReadTool, createWriteTool, withFileMutationQueue, } from "./tools/index.js";
+import { createAllToolDefinitions, createBashTool, createCodingTools, createDelegateToolDefinition, createEditTool, createFindTool, createGrepTool, createLsTool, createReadOnlyTools, createReadTool, createWriteTool, withFileMutationQueue, } from "./tools/index.js";
 // Preserve the pre-0.81 fallback for extensions that construct Agent instances
 // or invoke low-level agent loops without supplying streamFn. Agent core remains
 // provider-agnostic and does not import pi-ai/compat itself.
@@ -63,6 +65,22 @@ function getDefaultAgentDir() {
  * });
  * ```
  */
+/** The most recent assistant text in a completed session -- what a delegated child returns to its parent as its result. */
+function extractFinalAssistantText(session) {
+    const messages = session.agent.state.messages;
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const message = messages[i];
+        if (message.role !== "assistant")
+            continue;
+        const text = message.content
+            .filter((content) => content.type === "text")
+            .map((content) => content.text)
+            .join("\n");
+        if (text)
+            return text;
+    }
+    return "";
+}
 export async function createAgentSession(options = {}) {
     const cwd = resolvePath(options.cwd ?? options.sessionManager?.getCwd() ?? process.cwd());
     const agentDir = options.agentDir ? resolvePath(options.agentDir) : getDefaultAgentDir();
@@ -242,6 +260,112 @@ export async function createAgentSession(options = {}) {
         }
         sessionManager.appendThinkingLevelChange(thinkingLevel);
     }
+    // Forward ref, mirroring extensionRunnerRef above: the delegation runtime's
+    // closures are needed to build `customTools` before `session` exists, but they
+    // must read the *live* session (active tools can change after construction),
+    // not a snapshot frozen at this point.
+    const parentSessionRef = {};
+    const customTools = options.customTools ? [...options.customTools] : [];
+    // A configured permission gate supplies the authority a child must derive, so
+    // discovery is enabled by default in real sessions. Callers that need fixture
+    // definitions may still provide an explicit resolver.
+    const delegation = options.delegation ?? (options.permissionGate ? {} : undefined);
+    if (delegation) {
+        const parentPermissionGate = options.permissionGate;
+        const resolveAgent = delegation.resolveAgent ??
+            createAgentDefinitionResolver({
+                cwd,
+                agentDir,
+                isProjectTrusted: () => settingsManager.isProjectTrusted(),
+            });
+        const delegationRuntime = {
+            resolveAgent,
+            getParentCapabilities: () => {
+                const capabilities = new Set();
+                for (const name of parentSessionRef.current?.getActiveToolNames() ?? []) {
+                    const contract = parentSessionRef.current?.getToolDefinition(name)?.contract;
+                    if (contract)
+                        for (const capability of contract.capabilities)
+                            capabilities.add(capability);
+                }
+                return capabilities;
+            },
+            getToolCapabilities: (toolName) => {
+                // Prefer the parent's own live registry first (it also covers
+                // extension/custom tools an agent definition might name), but fall back
+                // to the canonical built-in registry: "what capability does tool X
+                // need" is a property of the tool itself, independent of whether the
+                // parent's own session restricted it out of its active/allowed set via
+                // `tools`/`excludeTools` -- that restriction affects the parent's own
+                // *authority* (getParentCapabilities, above), not what a named tool is.
+                const fromParent = parentSessionRef.current?.getToolDefinition(toolName)?.contract?.capabilities;
+                if (fromParent)
+                    return fromParent;
+                return createAllToolDefinitions(cwd)[toolName]?.contract
+                    ?.capabilities;
+            },
+            // Read fresh each call, not captured once: depth is a live property of
+            // the (possibly delegated) session this createAgentSession call is
+            // building, via the same sessionManager this closure already captures.
+            getDelegationDepth: () => sessionManager.getDelegationDepth(),
+            maxDelegationDepth: settingsManager.getDelegationMaxDepth(),
+            getParentSessionDir: () => sessionManager.getSessionDir(),
+            buildChildSession: async ({ definition, toolNames, depth, sessionId, artifactDir }) => {
+                if (!parentPermissionGate) {
+                    throw new Error("delegate requires a permission gate configured on the parent session (ADR 0008).");
+                }
+                const childModel = (definition.model && modelRuntime.getAvailableSnapshot().find((m) => m.id === definition.model)) ||
+                    model;
+                if (!childModel) {
+                    throw new Error(`Cannot delegate to "${definition.name}": no model is available for the child session.`);
+                }
+                const childSessionManager = artifactDir
+                    ? SessionManager.create(cwd, artifactDir, {
+                        id: sessionId,
+                        parentSession: sessionManager.getSessionId(),
+                        delegationDepth: depth,
+                    })
+                    : SessionManager.inMemory(cwd, {
+                        parentSession: sessionManager.getSessionId(),
+                        delegationDepth: depth,
+                    });
+                const derivedStore = new DerivedPermissionRuleStore({ parent: parentPermissionGate.store });
+                const { session: childSession } = await createAgentSession({
+                    cwd,
+                    agentDir,
+                    model: childModel,
+                    modelRuntime,
+                    settingsManager,
+                    sessionManager: childSessionManager,
+                    resourceLoader,
+                    tools: toolNames,
+                    // No responder: a child's `ask` fails closed rather than prompting the
+                    // human for a call the human did not make (ADR 0008, "Who answers a
+                    // child's ask").
+                    permissionGate: { store: derivedStore, getMode: parentPermissionGate.getMode },
+                    // Forwarded so a child that itself holds `delegate` can delegate again
+                    // (bounded by the depth guard above, read fresh from its own session
+                    // header on its next createAgentSession call) -- otherwise recursion
+                    // would be silently capped at one level regardless of maxDelegationDepth.
+                    delegation,
+                });
+                await childSession.bindExtensions({});
+                return {
+                    async run(task) {
+                        const prompt = definition.systemPrompt
+                            ? `${definition.systemPrompt}\n\nTask: ${task}`
+                            : `Task: ${task}`;
+                        await childSession.prompt(prompt);
+                        return { output: extractFinalAssistantText(childSession) };
+                    },
+                    dispose() {
+                        childSession.dispose();
+                    },
+                };
+            },
+        };
+        customTools.push(createDelegateToolDefinition(delegationRuntime));
+    }
     const session = new AgentSession({
         agent,
         sessionManager,
@@ -249,14 +373,17 @@ export async function createAgentSession(options = {}) {
         cwd,
         scopedModels: options.scopedModels,
         resourceLoader,
-        customTools: options.customTools,
+        customTools,
         modelRuntime,
         initialActiveToolNames,
         allowedToolNames,
         excludedToolNames,
         extensionRunnerRef,
         sessionStartEvent: options.sessionStartEvent,
+        permissionGate: options.permissionGate,
+        evidenceSink: options.evidenceSink,
     });
+    parentSessionRef.current = session;
     const extensionsResult = resourceLoader.getExtensions();
     return {
         session,