@alpacakit/agents 0.1.0-beta.19

package/dist/kernel/cli-login.js

@@ -0,0 +1,199 @@
+import { LOGIN_EVENT_TYPE, LOGIN_METHOD, } from "../auth/login.js";
+import { AUTH_MATERIAL_KIND, AUTH_STATUS, } from "../auth/material.js";
+import { applyEnvPatch } from "../core/env.js";
+import { AGENT_ERROR_CODE, AgentError, NOT_AVAILABLE_CAUSE, TIMEOUT_KIND, } from "../core/error.js";
+import { redactSecrets } from "../core/redact.js";
+import { OUTPUT_CHANNEL, PROCESS_SIGNAL } from "../core/values.js";
+import { classifyFailure, sharedFailureMatchers } from "./classify.js";
+const DEFAULT_CLI_LOGIN_TIMEOUT_MS = 20 * 60 * 1_000;
+const SIGKILL_ESCALATION_MS = 5_000;
+const RAW_OUTPUT_CAP_CHARS = 10 * 1024 * 1024;
+const OUTPUT_TAIL_CHARS = 2_000;
+const SCAN_BUFFER_CHARS = 12_000;
+const MINUTE_MS = 60_000;
+// Best-effort scanners over the accumulated (ANSI-stripped) CLI output, matching
+// the shape observed in design `an` Phase 0 (codex-cli 0.139.0): a hyphen-grouped
+// uppercase one-time code and an "expires in N minutes" hint. Each takes the
+// FIRST hit; a format drift only suppresses the derived event — exit code 0
+// still yields the outcome.
+const DEVICE_CODE_EXPIRY_PATTERN = /\bexpires in (\d+) minutes?\b/i;
+const DEVICE_CODE_PATTERN = /\b[A-Z0-9]{4,}(?:-[A-Z0-9]{4,})+\b/u;
+const URL_PATTERN = /https?:\/\/[^\s)]+/u;
+// biome-ignore lint/suspicious/noControlCharactersInRegex: strips ANSI/CSI escape sequences from colorized CLI output.
+const ANSI_PATTERN = /\x1b\[[0-?]*[ -/]*[@-~]/gu;
+function boundedTail(current, text, capChars) {
+    const combined = current + text;
+    return combined.length > capChars
+        ? combined.slice(combined.length - capChars)
+        : combined;
+}
+function stripAnsi(text) {
+    return text.replace(ANSI_PATTERN, "");
+}
+function firstMatch(text, pattern) {
+    return text.match(pattern)?.[0] ?? null;
+}
+function deviceCodeExpiresAt(buffer, now) {
+    const minutes = buffer.match(DEVICE_CODE_EXPIRY_PATTERN)?.[1];
+    return minutes === undefined
+        ? null
+        : new Date(now + Number(minutes) * MINUTE_MS).toISOString();
+}
+const LOGIN_EVENT_PARSERS = {
+    [LOGIN_METHOD.oauth]: (buffer) => {
+        const url = firstMatch(buffer, URL_PATTERN);
+        return url === null ? null : { type: LOGIN_EVENT_TYPE.openUrl, url };
+    },
+    [LOGIN_METHOD.device]: (buffer, now) => {
+        const url = firstMatch(buffer, URL_PATTERN);
+        const code = firstMatch(buffer, DEVICE_CODE_PATTERN);
+        return url === null || code === null
+            ? null
+            : {
+                type: LOGIN_EVENT_TYPE.deviceCode,
+                code,
+                url,
+                expiresAt: deviceCodeExpiresAt(buffer, now),
+            };
+    },
+};
+function loginExitError(input) {
+    const { command, exit, stdout, stderr, now } = input;
+    const classified = classifyFailure(sharedFailureMatchers, {
+        stdout,
+        stderr,
+        exitCode: exit.code,
+        signal: exit.signal,
+        now,
+    });
+    if (classified !== null) {
+        return new AgentError({
+            ...classified,
+            message: redactSecrets(classified.message),
+        });
+    }
+    const signal = exit.signal === null ? "" : ` (signal ${exit.signal})`;
+    return new AgentError({
+        code: AGENT_ERROR_CODE.failed,
+        message: redactSecrets(`Login command "${command}" exited with code ${exit.code ?? "null"}${signal}`),
+        data: {
+            exitCode: exit.code,
+            stdoutTail: redactSecrets(stdout.slice(-OUTPUT_TAIL_CHARS)) || null,
+            stderrTail: redactSecrets(stderr.slice(-OUTPUT_TAIL_CHARS)) || null,
+        },
+    });
+}
+function homeDirOutcome(request, status) {
+    return {
+        material: { kind: AUTH_MATERIAL_KIND.homeDir, path: request.homeDir },
+        status,
+    };
+}
+export async function* cliLoginCommand(options) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_CLI_LOGIN_TIMEOUT_MS;
+    const env = applyEnvPatch(options.ctx.env, options.envPatch);
+    const command = await options.ctx.exec.which(options.command, env);
+    if (command === null) {
+        throw new AgentError({
+            code: AGENT_ERROR_CODE.notAvailable,
+            message: `Login command "${options.command}" was not found on PATH`,
+            data: { cause: NOT_AVAILABLE_CAUSE.notInstalled },
+        });
+    }
+    const child = options.ctx.exec.spawn({
+        command,
+        args: [...options.args],
+        cwd: options.ctx.location.homeDir,
+        env,
+        stdin: null,
+    });
+    const parseEvent = LOGIN_EVENT_PARSERS[options.request.method];
+    let stdout = "";
+    let stderr = "";
+    let scanBuffer = "";
+    let emitted = false;
+    const { signal } = options.ctx;
+    let timedOut = false;
+    let killed = false;
+    // A box, not a bare `let`: the SIGKILL canceller is assigned only inside the
+    // escalation path, and control-flow analysis would otherwise narrow a
+    // closure-assigned `let` to `never` at the `finally` read site.
+    const cancelKill = { current: null };
+    // One kill path shared by the total-timeout and the caller-abort stops:
+    // SIGTERM, then SIGKILL after a grace — mirroring the run adapter's onAbort.
+    // Idempotent so a timeout racing an abort escalates once.
+    const escalateKill = () => {
+        if (killed) {
+            return;
+        }
+        killed = true;
+        child.kill(PROCESS_SIGNAL.sigterm);
+        cancelKill.current = options.ctx.clock.setTimeout(() => child.kill(PROCESS_SIGNAL.sigkill), SIGKILL_ESCALATION_MS);
+    };
+    const onAbort = () => escalateKill();
+    const cancelTimeout = options.ctx.clock.setTimeout(() => {
+        timedOut = true;
+        escalateKill();
+    }, timeoutMs);
+    if (signal.aborted) {
+        onAbort();
+    }
+    else {
+        signal.addEventListener("abort", onAbort, { once: true });
+    }
+    try {
+        for await (const chunk of child.chunks) {
+            if (chunk.channel === OUTPUT_CHANNEL.stdout) {
+                stdout = boundedTail(stdout, chunk.text, RAW_OUTPUT_CAP_CHARS);
+            }
+            else {
+                stderr = boundedTail(stderr, chunk.text, RAW_OUTPUT_CAP_CHARS);
+            }
+            yield {
+                type: LOGIN_EVENT_TYPE.output,
+                channel: chunk.channel,
+                chunk: chunk.text,
+            };
+            if (!emitted) {
+                scanBuffer = boundedTail(scanBuffer, stripAnsi(chunk.text), SCAN_BUFFER_CHARS);
+                const event = parseEvent(scanBuffer, options.ctx.clock.now());
+                if (event !== null) {
+                    emitted = true;
+                    yield event;
+                }
+            }
+        }
+        const exit = await child.exit;
+        if (signal.aborted) {
+            throw new AgentError({
+                code: AGENT_ERROR_CODE.cancelled,
+                message: `Login command "${options.command}" was cancelled`,
+                data: {
+                    reason: typeof signal.reason === "string" ? signal.reason : null,
+                },
+            });
+        }
+        if (timedOut) {
+            throw new AgentError({
+                code: AGENT_ERROR_CODE.timeout,
+                message: `Login command "${options.command}" exceeded its total timeout of ${timeoutMs}ms`,
+                data: { kind: TIMEOUT_KIND.total, limitMs: timeoutMs },
+            });
+        }
+        if (exit.code === 0) {
+            return homeDirOutcome(options.request, AUTH_STATUS.valid);
+        }
+        throw loginExitError({
+            command: options.command,
+            exit,
+            stdout,
+            stderr,
+            now: options.ctx.clock.now(),
+        });
+    }
+    finally {
+        signal.removeEventListener("abort", onAbort);
+        cancelTimeout();
+        cancelKill.current?.();
+    }
+}

package/dist/kernel/definition.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The definition/instance split (design "Kernel"): an `AgentDefinition`
+ * is pure description; binding it to a runtime yields an `Agent`.
+ * Adapters yield `AgentEvent` and return an `AgentRunOutcome`; the
+ * kernel owns `runId`, timing, and the lifecycle bracket.
+ */
+import type { LoginCapability } from "../auth/login.js";
+import type { AuthCapability } from "../auth/material.js";
+import type { Clock, Exec, HttpClient, Logger } from "../core/ports.js";
+import type { AgentEvent, AgentRunOutcome } from "../core/run.js";
+import type { DoctorCapability, McpCapability, SkillsCapability } from "../host/capabilities.js";
+import type { ResolvedRunOptions } from "./options.js";
+/** Resolved (rule 2): the adapter's whole world. */
+export type RunContext = {
+    /** The ONE stop channel — caller abort, timeout, and guard violations. */
+    signal: AbortSignal;
+    /** Fully layered: baseEnv → auth patch → options.env. */
+    env: Record<string, string>;
+    exec: Exec;
+    http: HttpClient;
+    /** For adapter-owned time mechanics: kill escalation, completion grace. */
+    clock: Clock;
+    /** Pre-scoped to the run by the kernel. */
+    logger: Logger;
+};
+export type AgentRun = AsyncGenerator<AgentEvent, AgentRunOutcome, void>;
+export interface AgentDefinition<Id extends string = string> {
+    id: Id;
+    run(options: ResolvedRunOptions, ctx: RunContext): AgentRun;
+    auth?: AuthCapability;
+    login?: LoginCapability;
+    doctor?: DoctorCapability;
+    skills?: SkillsCapability;
+    mcp?: McpCapability;
+}
+/**
+ * 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>;
+//# sourceMappingURL=definition.d.ts.map

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

@@ -0,0 +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,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,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"}

package/dist/kernel/definition.js

@@ -0,0 +1,13 @@
+/**
+ * The definition/instance split (design "Kernel"): an `AgentDefinition`
+ * is pure description; binding it to a runtime yields an `Agent`.
+ * Adapters yield `AgentEvent` and return an `AgentRunOutcome`; the
+ * kernel owns `runId`, timing, and the lifecycle bracket.
+ */
+/**
+ * Identity helper for hand-rolled agents: pins the `Id` literal and
+ * type-checks the definition in place. No runtime behavior.
+ */
+export function defineAgent(definition) {
+    return definition;
+}

package/dist/kernel/env-template.d.ts

@@ -0,0 +1,17 @@
+export type EnvTemplate = string;
+declare const ENV_TEMPLATE_FAILURE_REASON: {
+    readonly missing: "missing";
+    readonly empty: "empty";
+};
+export declare function referencedEnvNames(value: unknown): readonly string[];
+export type EnvTemplateResolution = {
+    readonly ok: true;
+    readonly value: string;
+} | {
+    readonly ok: false;
+    readonly reason: (typeof ENV_TEMPLATE_FAILURE_REASON)[keyof typeof ENV_TEMPLATE_FAILURE_REASON];
+    readonly envName: string;
+};
+export declare function resolveEnvTemplate(value: EnvTemplate, env: Readonly<Record<string, string>>): EnvTemplateResolution;
+export {};
+//# sourceMappingURL=env-template.d.ts.map

package/dist/kernel/env-template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-template.d.ts","sourceRoot":"","sources":["../../src/kernel/env-template.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC;AAIjC,QAAA,MAAM,2BAA2B;;;CAGvB,CAAC;AAEX,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,MAAM,EAAE,CAIpE;AAED,MAAM,MAAM,qBAAqB,GAC7B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC7C;IACE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,MAAM,EAAE,CAAC,OAAO,2BAA2B,CAAC,CAAC,MAAM,OAAO,2BAA2B,CAAC,CAAC;IAChG,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEN,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,WAAW,EAClB,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACpC,qBAAqB,CA4BvB"}

package/dist/kernel/env-template.js

@@ -0,0 +1,78 @@
+import { AGENT_ERROR_CODE, AgentError } from "../core/error.js";
+const ENV_TEMPLATE_EXPRESSION = /\$\{([^}]*)\}/gu;
+const ENV_TEMPLATE_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/u;
+const ENV_TEMPLATE_FAILURE_REASON = {
+    missing: "missing",
+    empty: "empty",
+};
+export function referencedEnvNames(value) {
+    const names = new Set();
+    collectReferencedEnvNames(value, names);
+    return [...names];
+}
+export function resolveEnvTemplate(value, env) {
+    assertValidEnvTemplate(value);
+    let failed = null;
+    const resolved = value.replace(ENV_TEMPLATE_EXPRESSION, (expression, key) => {
+        if (!ENV_TEMPLATE_NAME.test(String(key))) {
+            throw invalidTemplateError(expression);
+        }
+        const replacement = env[String(key)];
+        if (replacement === undefined) {
+            failed = {
+                ok: false,
+                reason: ENV_TEMPLATE_FAILURE_REASON.missing,
+                envName: String(key),
+            };
+            return expression;
+        }
+        if (replacement.length === 0) {
+            failed = {
+                ok: false,
+                reason: ENV_TEMPLATE_FAILURE_REASON.empty,
+                envName: String(key),
+            };
+            return expression;
+        }
+        return replacement;
+    });
+    return failed ?? { ok: true, value: resolved };
+}
+function collectReferencedEnvNames(value, names) {
+    if (typeof value === "string") {
+        assertValidEnvTemplate(value);
+        for (const match of value.matchAll(ENV_TEMPLATE_EXPRESSION)) {
+            const expression = match[0] ?? "";
+            const name = match[1] ?? "";
+            if (!ENV_TEMPLATE_NAME.test(name)) {
+                throw invalidTemplateError(expression);
+            }
+            names.add(name);
+        }
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            collectReferencedEnvNames(item, names);
+        }
+        return;
+    }
+    if (value !== null && typeof value === "object") {
+        for (const item of Object.values(value)) {
+            collectReferencedEnvNames(item, names);
+        }
+    }
+}
+function assertValidEnvTemplate(value) {
+    const unresolved = value.replace(ENV_TEMPLATE_EXPRESSION, "");
+    if (unresolved.includes("${")) {
+        throw invalidTemplateError("${");
+    }
+}
+function invalidTemplateError(expression) {
+    return new AgentError({
+        code: AGENT_ERROR_CODE.invalidInput,
+        message: `Invalid environment template: ${expression}`,
+        data: { reason: `invalid environment template: ${expression}` },
+    });
+}

package/dist/kernel/facets.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Bound capability facets (design "Architecture"): the runtime owns the
+ * effectful context parts and binds them once; call sites pass only a
+ * `HostLocation`. Keyed-record dispatch is enforced here — a missing
+ * handler key is a typed `invalid_input`, never a silent fallback.
+ */
+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 { Clock, Exec, HttpClient, Logger, SecretResolvers } from "../core/ports.js";
+import type { DoctorCapability, DoctorReport, InstalledSkill, InstallOptions, InstallOutcome, McpCapability, McpScope, McpServerSpec, McpServerState, SkillSource, SkillsCapability } from "../host/capabilities.js";
+import type { HostLocation } from "../host/context.js";
+export type AgentAuth = {
+    supports(kind: AuthMaterialKind): boolean;
+    /** Supported material kinds in canonical order (empty if none). */
+    kinds(): AuthMaterialKind[];
+    /** Per-kind introspection for setup UIs (empty if none). */
+    describe(): AuthMaterialDescriptor[];
+    toEnv(material: AuthMaterial): Promise<EnvPatch>;
+    check(material: AuthMaterial, location: HostLocation): Promise<AuthStatus>;
+};
+export type AgentDoctor = {
+    probe(location: HostLocation): Promise<DoctorReport>;
+};
+export type AgentLogin = {
+    /** Supported sign-in methods in canonical order (empty if none). */
+    methods(): LoginMethod[];
+    supports(method: LoginMethod): boolean;
+    start(request: LoginRequest, location: HostLocation): LoginHandle;
+};
+export type AgentSkills = {
+    list(location: HostLocation): Promise<InstalledSkill[]>;
+    install(location: HostLocation, source: SkillSource, options?: InstallOptions): Promise<InstallOutcome>;
+};
+export type AgentMcp = {
+    list(location: HostLocation): Promise<McpServerState[]>;
+    add(location: HostLocation, name: string, spec: McpServerSpec, options: {
+        scope: McpScope;
+    }): Promise<InstallOutcome>;
+    remove(location: HostLocation, name: string, options: {
+        scope: McpScope;
+    }): Promise<void>;
+};
+export type FacetBinding = {
+    agentId: string;
+    env: Record<string, string>;
+    exec: Exec;
+    http: HttpClient;
+    clock: Clock;
+    logger: Logger;
+    secrets: SecretResolvers;
+};
+export declare function bindAuth(capability: AuthCapability, binding: FacetBinding): AgentAuth;
+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 bindMcp(capability: McpCapability, binding: FacetBinding): AgentMcp;
+//# sourceMappingURL=facets.d.ts.map

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

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

package/dist/kernel/facets.js

@@ -0,0 +1,102 @@
+/**
+ * Bound capability facets (design "Architecture"): the runtime owns the
+ * effectful context parts and binds them once; call sites pass only a
+ * `HostLocation`. Keyed-record dispatch is enforced here — a missing
+ * handler key is a typed `invalid_input`, never a silent fallback.
+ */
+import { LOGIN_METHOD, } from "../auth/login.js";
+import { AUTH_MATERIAL_KIND, AUTH_STATUS, authMaterialRequiresSecret, } from "../auth/material.js";
+import { AGENT_ERROR_CODE, AgentError } from "../core/error.js";
+import { resolveHostLocation } from "../host/context.js";
+import { validateSpecSecrets } from "../host/validate-spec.js";
+import { keyedHandler, requireKeyedHandler } from "./keyed.js";
+import { startLogin } from "./login.js";
+function hostContext(binding, location) {
+    return {
+        location: resolveHostLocation(location),
+        env: binding.env,
+        exec: binding.exec,
+        http: binding.http,
+        clock: binding.clock,
+        logger: binding.logger,
+    };
+}
+/** Supported kinds in canonical declaration order, not the record's key order. */
+function supportedKinds(materials) {
+    return Object.values(AUTH_MATERIAL_KIND).filter((kind) => materials[kind] !== undefined);
+}
+function supportedLoginMethods(capability) {
+    return Object.values(LOGIN_METHOD).filter((method) => capability.methods[method] !== undefined);
+}
+export function bindAuth(capability, binding) {
+    const requireHandler = (kind) => requireKeyedHandler(capability.materials, kind, binding.agentId, `auth material "${kind}"`);
+    return {
+        supports: (kind) => keyedHandler(capability.materials, kind) !== null,
+        kinds: () => supportedKinds(capability.materials),
+        describe: () => supportedKinds(capability.materials).map((kind) => ({
+            kind,
+            requiresSecret: authMaterialRequiresSecret(kind),
+            canProbe: capability.materials[kind]?.check !== undefined,
+        })),
+        toEnv: (material) => requireHandler(material.kind).toEnv(material, binding.secrets),
+        check: (material, location) => {
+            const handler = requireHandler(material.kind);
+            if (handler.check === undefined) {
+                return Promise.resolve(AUTH_STATUS.unknown);
+            }
+            return handler.check(material, hostContext(binding, location));
+        },
+    };
+}
+export function bindLogin(capability, binding) {
+    const requireHandler = (method) => requireKeyedHandler(capability.methods, method, binding.agentId, `login method "${method}"`);
+    return {
+        methods: () => supportedLoginMethods(capability),
+        supports: (method) => keyedHandler(capability.methods, method) !== null,
+        start: (request, location) => startLogin({
+            agentId: binding.agentId,
+            request,
+            ctx: hostContext(binding, location),
+            handler: requireHandler(request.method),
+            // Strip the signal off the request into the driver's stop channel,
+            // exactly as `bindAgent.run` does with `RunOptions.signal`.
+            callerSignal: request.signal ?? null,
+        }),
+    };
+}
+export function bindDoctor(capability, binding) {
+    return {
+        probe: (location) => capability.probe(hostContext(binding, location)),
+    };
+}
+export function bindSkills(capability, binding) {
+    return {
+        list: (location) => capability.list(hostContext(binding, location)),
+        install: (location, source, options) => {
+            const handler = requireKeyedHandler(capability.install, source.kind, binding.agentId, `skill source "${source.kind}"`);
+            return handler(hostContext(binding, location), source, options ?? {});
+        },
+    };
+}
+export function bindMcp(capability, binding) {
+    return {
+        list: (location) => capability.list(hostContext(binding, location)),
+        add: (location, name, spec, options) => {
+            const issues = validateSpecSecrets(spec);
+            if (issues.length > 0) {
+                throw new AgentError({
+                    code: AGENT_ERROR_CODE.invalidInput,
+                    message: "MCP server spec contains a literal or forbidden secret",
+                    data: {
+                        reason: issues
+                            .map((issue) => `${issue.path.join(".")}: ${issue.code}`)
+                            .join("; "),
+                    },
+                });
+            }
+            const handler = requireKeyedHandler(capability.add, spec.transport, binding.agentId, `MCP transport "${spec.transport}"`);
+            return handler(hostContext(binding, location), name, spec, options);
+        },
+        remove: (location, name, options) => capability.remove(hostContext(binding, location), name, options),
+    };
+}

package/dist/kernel/guard.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Guards are kernel-owned event observers (design "Limits and guards"):
+ * the kernel feeds them every RunEvent, polls `violation()` on its own
+ * timer so time-based guards fire between events, and trips the run's
+ * abort on violation. Factories receive `{ clock }` — no `Date.now()`
+ * in guards, so `noProgress` stays deterministic under a fake clock.
+ */
+import type { GuardViolation } from "../core/error.js";
+import type { Clock } from "../core/ports.js";
+import type { RunEvent } from "../core/run.js";
+export type GuardContext = {
+    clock: Clock;
+};
+export interface Guard {
+    readonly id: string;
+    observe(event: RunEvent): void;
+    violation(): GuardViolation | null;
+}
+export type GuardFactory = (ctx: GuardContext) => Guard;
+export declare function maxTurns(limit: number): GuardFactory;
+export declare function maxToolCalls(limit: number): GuardFactory;
+export declare function repeatedOutput(times: number): GuardFactory;
+export declare function noProgress(ms: number): GuardFactory;
+//# sourceMappingURL=guard.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../../src/kernel/guard.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAG/C,MAAM,MAAM,YAAY,GAAG;IAAE,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC;AAE5C,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC/B,SAAS,IAAI,cAAc,GAAG,IAAI,CAAC;CACpC;AAED,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,EAAE,YAAY,KAAK,KAAK,CAAC;AA0BxD,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,CAQpD;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,CAQxD;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,CAsB1D;AAED,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,CAiBnD"}

package/dist/kernel/guard.js

@@ -0,0 +1,69 @@
+/**
+ * Guards are kernel-owned event observers (design "Limits and guards"):
+ * the kernel feeds them every RunEvent, polls `violation()` on its own
+ * timer so time-based guards fire between events, and trips the run's
+ * abort on violation. Factories receive `{ clock }` — no `Date.now()`
+ * in guards, so `noProgress` stays deterministic under a fake clock.
+ */
+import { AGENT_EVENT_TYPE } from "../core/run.js";
+const MAX_TURNS_GUARD_ID = "max-turns";
+const MAX_TOOL_CALLS_GUARD_ID = "max-tool-calls";
+const REPEATED_OUTPUT_GUARD_ID = "repeated-output";
+const NO_PROGRESS_GUARD_ID = "no-progress";
+function countingGuard(id, limit, counts, describe) {
+    let count = 0;
+    return {
+        id,
+        observe: (event) => {
+            if (counts(event)) {
+                count += 1;
+            }
+        },
+        violation: () => count > limit ? { guardId: id, reason: describe(limit) } : null,
+    };
+}
+export function maxTurns(limit) {
+    return () => countingGuard(MAX_TURNS_GUARD_ID, limit, (event) => event.type === AGENT_EVENT_TYPE.turn, (max) => `exceeded ${max} turns`);
+}
+export function maxToolCalls(limit) {
+    return () => countingGuard(MAX_TOOL_CALLS_GUARD_ID, limit, (event) => event.type === AGENT_EVENT_TYPE.tool, (max) => `exceeded ${max} tool calls`);
+}
+export function repeatedOutput(times) {
+    return () => {
+        let lastText = null;
+        let repeats = 0;
+        return {
+            id: REPEATED_OUTPUT_GUARD_ID,
+            observe: (event) => {
+                if (event.type !== AGENT_EVENT_TYPE.message) {
+                    return;
+                }
+                repeats = event.text === lastText ? repeats + 1 : 1;
+                lastText = event.text;
+            },
+            violation: () => repeats >= times
+                ? {
+                    guardId: REPEATED_OUTPUT_GUARD_ID,
+                    reason: `identical assistant message repeated ${repeats} times`,
+                }
+                : null,
+        };
+    };
+}
+export function noProgress(ms) {
+    return ({ clock }) => {
+        let lastEventAt = clock.now();
+        return {
+            id: NO_PROGRESS_GUARD_ID,
+            observe: () => {
+                lastEventAt = clock.now();
+            },
+            violation: () => clock.now() - lastEventAt >= ms
+                ? {
+                    guardId: NO_PROGRESS_GUARD_ID,
+                    reason: `no events for ${ms}ms`,
+                }
+                : null,
+        };
+    };
+}

package/dist/kernel/handle.d.ts

@@ -0,0 +1,29 @@
+/**
+ * RunHandle internals: a bounded-replay broadcast and an awaitable
+ * handle (`then` delegates to `result`). Not consuming events never
+ * blocks the run. Subscribers attached while the run streams receive
+ * every event live; a LATE subscriber gets the retained replay window —
+ * bounded by payload bytes so a verbose run cannot hold its whole
+ * output in memory a second time (the capped raw transcript already
+ * lives on the result).
+ */
+import type { RunEvent, RunHandle, RunResult } from "../core/run.js";
+type EventCost<Event> = (event: Event) => number;
+export declare class EventBroadcast<Event = RunEvent> {
+    private readonly replayBudgetBytes;
+    private readonly eventCost;
+    private history;
+    private historyStart;
+    private retainedBytes;
+    private readonly subscribers;
+    private ended;
+    constructor(replayBudgetBytes?: number, eventCost?: EventCost<Event>);
+    push(event: Event): void;
+    /** The most recent event always survives, however large. */
+    private evictOverBudget;
+    end(): void;
+    get events(): AsyncIterable<Event>;
+}
+export declare function createRunHandle(runId: string, broadcast: EventBroadcast<RunEvent>, result: Promise<RunResult>): RunHandle;
+export {};
+//# sourceMappingURL=handle.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"handle.d.ts","sourceRoot":"","sources":["../../src/kernel/handle.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAKrE,KAAK,SAAS,CAAC,KAAK,IAAI,CAAC,KAAK,EAAE,KAAK,KAAK,MAAM,CAAC;AAYjD,qBAAa,cAAc,CAAC,KAAK,GAAG,QAAQ;IAQxC,OAAO,CAAC,QAAQ,CAAC,iBAAiB;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS;IAR5B,OAAO,CAAC,OAAO,CAAe;IAC9B,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAgC;IAC5D,OAAO,CAAC,KAAK,CAAS;gBAGH,iBAAiB,SAA8B,EAC/C,SAAS,GAAE,SAAS,CAAC,KAAK,CAAkC;IAG/E,IAAI,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAYxB,4DAA4D;IAC5D,OAAO,CAAC,eAAe;IAkBvB,GAAG,IAAI,IAAI;IAQX,IAAI,MAAM,IAAI,aAAa,CAAC,KAAK,CAAC,CAejC;CACF;AAED,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,cAAc,CAAC,QAAQ,CAAC,EACnC,MAAM,EAAE,OAAO,CAAC,SAAS,CAAC,GACzB,SAAS,CAUX"}