@alpacakit/agents 0.1.0-beta.19

package/dist/host/mcp-list.js

@@ -0,0 +1,122 @@
+/**
+ * Shared `mcp list` inventory: run the agent CLI with `--json`, parse the
+ * output into `McpServerState[]`. Parsing is tolerant of the shapes the
+ * claude/codex CLIs emit (array, `{servers: [...]}`  or name-keyed maps),
+ * but non-JSON output is a typed failure, never a raw `SyntaxError`.
+ */
+import { AGENT_ERROR_CODE, AgentError } from "../core/error.js";
+import { readString, readUnknownRecord, } from "../core/json.js";
+import { redactSecrets } from "../core/redact.js";
+import { MCP_TRANSPORT } from "./capabilities.js";
+import { runHostCommand } from "./run-command.js";
+const OUTPUT_TAIL_CHARS = 2_000;
+const MCP_LIST_ARGS = ["mcp", "list", "--json"];
+const MCP_LIST_FIELD = {
+    name: "name",
+    servers: "servers",
+    state: "state",
+    status: "status",
+    tools: "tools",
+    transport: "transport",
+    usable: "usable",
+};
+function readMcpTools(record) {
+    const tools = record[MCP_LIST_FIELD.tools];
+    if (!Array.isArray(tools)) {
+        // The CLI did not enumerate tools; that is unknown, not "no tools".
+        return null;
+    }
+    return tools.flatMap((tool) => {
+        if (typeof tool === "string") {
+            return [tool];
+        }
+        const toolRecord = readUnknownRecord(tool);
+        const name = toolRecord === null ? null : readString(toolRecord, MCP_LIST_FIELD.name);
+        return name === null ? [] : [name];
+    });
+}
+function isMcpUsable(record) {
+    const usable = record[MCP_LIST_FIELD.usable];
+    if (typeof usable === "boolean") {
+        return usable;
+    }
+    const status = readString(record, MCP_LIST_FIELD.status) ??
+        readString(record, MCP_LIST_FIELD.state);
+    return status === null
+        ? true
+        : !/disabled|failed|error|unusable/iu.test(status);
+}
+function mcpStateFromRecord(name, record) {
+    const rawTransport = readString(record, MCP_LIST_FIELD.transport) ?? MCP_TRANSPORT.stdio;
+    if (rawTransport !== MCP_TRANSPORT.stdio &&
+        rawTransport !== MCP_TRANSPORT.http) {
+        // A transport outside the vocabulary would be misreported as stdio;
+        // skip the entry instead of inventing a state for it.
+        return null;
+    }
+    return {
+        name,
+        transport: rawTransport,
+        usable: isMcpUsable(record),
+        tools: readMcpTools(record),
+    };
+}
+function serverListFromEntries(entries) {
+    return entries.flatMap((entry) => {
+        const record = readUnknownRecord(entry);
+        if (record === null) {
+            return [];
+        }
+        const name = readString(record, MCP_LIST_FIELD.name);
+        if (name === null) {
+            return [];
+        }
+        const state = mcpStateFromRecord(name, record);
+        return state === null ? [] : [state];
+    });
+}
+function serverListFromValue(value) {
+    if (Array.isArray(value)) {
+        return serverListFromEntries(value);
+    }
+    const record = readUnknownRecord(value);
+    if (record === null) {
+        return [];
+    }
+    const servers = record[MCP_LIST_FIELD.servers];
+    if (Array.isArray(servers)) {
+        return serverListFromEntries(servers);
+    }
+    const namedServers = readUnknownRecord(servers) ?? record;
+    return Object.entries(namedServers).flatMap(([name, entry]) => {
+        const serverRecord = readUnknownRecord(entry);
+        if (serverRecord === null) {
+            return [];
+        }
+        const state = mcpStateFromRecord(name, serverRecord);
+        return state === null ? [] : [state];
+    });
+}
+export async function listMcpServersViaCli(ctx, input) {
+    const result = await runHostCommand(ctx, {
+        command: input.command,
+        args: [...MCP_LIST_ARGS],
+    });
+    let parsed;
+    try {
+        parsed = JSON.parse(result.stdout);
+    }
+    catch (error) {
+        throw new AgentError({
+            code: AGENT_ERROR_CODE.failed,
+            message: "MCP server list output is not valid JSON",
+            data: {
+                exitCode: result.exit.code,
+                stdoutTail: redactSecrets(result.stdout.slice(-OUTPUT_TAIL_CHARS)) || null,
+                stderrTail: result.stderr.slice(-OUTPUT_TAIL_CHARS) || null,
+            },
+            cause: error,
+        });
+    }
+    return serverListFromValue(parsed);
+}

package/dist/host/requirement-ref.d.ts

@@ -0,0 +1,12 @@
+export type SkillRequirementRef = {
+    readonly agentId: string;
+    readonly skillId: string;
+};
+export type McpRequirementRef = {
+    readonly agentId: string;
+    readonly server: string;
+    readonly tool: string | null;
+};
+export declare function parseSkillRequirementRef(ref: string): SkillRequirementRef | null;
+export declare function parseMcpRequirementRef(ref: string): McpRequirementRef | null;
+//# sourceMappingURL=requirement-ref.d.ts.map

package/dist/host/requirement-ref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requirement-ref.d.ts","sourceRoot":"","sources":["../../src/host/requirement-ref.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B,CAAC;AAMF,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,MAAM,GACV,mBAAmB,GAAG,IAAI,CAM5B;AAED,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CAmB5E"}

package/dist/host/requirement-ref.js

@@ -0,0 +1,40 @@
+const AGENT_TARGET_SEPARATOR = ":";
+const MCP_TOOL_SEPARATOR = "/";
+const EMPTY_REF_PART = "";
+export function parseSkillRequirementRef(ref) {
+    const parts = splitAgentRef(ref);
+    if (parts === null || parts.target.includes(MCP_TOOL_SEPARATOR)) {
+        return null;
+    }
+    return { agentId: parts.agentId, skillId: parts.target };
+}
+export function parseMcpRequirementRef(ref) {
+    const parts = splitAgentRef(ref);
+    if (parts === null) {
+        return null;
+    }
+    const separator = parts.target.indexOf(MCP_TOOL_SEPARATOR);
+    if (separator < 0) {
+        return { agentId: parts.agentId, server: parts.target, tool: null };
+    }
+    const server = parts.target.slice(0, separator);
+    const tool = parts.target.slice(separator + 1);
+    if (server === EMPTY_REF_PART ||
+        tool === EMPTY_REF_PART ||
+        tool.includes(MCP_TOOL_SEPARATOR)) {
+        return null;
+    }
+    return { agentId: parts.agentId, server, tool };
+}
+function splitAgentRef(ref) {
+    const separator = ref.indexOf(AGENT_TARGET_SEPARATOR);
+    if (separator <= 0 || separator !== ref.lastIndexOf(AGENT_TARGET_SEPARATOR)) {
+        return null;
+    }
+    const agentId = ref.slice(0, separator);
+    const target = ref.slice(separator + 1);
+    if (target === EMPTY_REF_PART) {
+        return null;
+    }
+    return { agentId, target };
+}

package/dist/host/run-command.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared host-plane command runner: skill/MCP registrations shell out to
+ * the agent CLI outside a run. One implementation owns PATH resolution,
+ * stderr capture, redaction, and the typed failure boundary — adapters
+ * only choose the command and argv.
+ */
+import { AGENT_ERROR_CODE, AgentError } from "../core/error.js";
+import type { HostContext } from "./context.js";
+export type HostCommandResult = {
+    stdout: string;
+    stderr: string;
+    exit: {
+        code: number | null;
+        signal: string | null;
+    };
+};
+export declare function runHostCommandResult(ctx: HostContext, input: {
+    command: string;
+    args: readonly string[];
+}): Promise<HostCommandResult>;
+/** The one way a non-zero host command becomes a typed error. */
+export declare function hostCommandFailedError(command: string, result: HostCommandResult): AgentError<typeof AGENT_ERROR_CODE.failed>;
+export declare function runHostCommand(ctx: HostContext, input: {
+    command: string;
+    args: readonly string[];
+}): Promise<HostCommandResult>;
+//# sourceMappingURL=run-command.d.ts.map

package/dist/host/run-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-command.d.ts","sourceRoot":"","sources":["../../src/host/run-command.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,gBAAgB,EAChB,UAAU,EAEX,MAAM,kBAAkB,CAAC;AAG1B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAIhD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;CACtD,CAAC;AAEF,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,WAAW,EAChB,KAAK,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAClD,OAAO,CAAC,iBAAiB,CAAC,CA+B5B;AAED,iEAAiE;AACjE,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,iBAAiB,GACxB,UAAU,CAAC,OAAO,gBAAgB,CAAC,MAAM,CAAC,CAc5C;AAED,wBAAsB,cAAc,CAClC,GAAG,EAAE,WAAW,EAChB,KAAK,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAClD,OAAO,CAAC,iBAAiB,CAAC,CAM5B"}

package/dist/host/run-command.js

@@ -0,0 +1,66 @@
+/**
+ * Shared host-plane command runner: skill/MCP registrations shell out to
+ * the agent CLI outside a run. One implementation owns PATH resolution,
+ * stderr capture, redaction, and the typed failure boundary — adapters
+ * only choose the command and argv.
+ */
+import { AGENT_ERROR_CODE, AgentError, NOT_AVAILABLE_CAUSE, } from "../core/error.js";
+import { redactSecrets } from "../core/redact.js";
+import { OUTPUT_CHANNEL } from "../core/values.js";
+const OUTPUT_TAIL_CHARS = 2_000;
+export async function runHostCommandResult(ctx, input) {
+    const command = await ctx.exec.which(input.command, ctx.env);
+    if (command === null) {
+        throw new AgentError({
+            code: AGENT_ERROR_CODE.notAvailable,
+            message: `Command "${input.command}" was not found on PATH`,
+            data: { cause: NOT_AVAILABLE_CAUSE.notInstalled },
+        });
+    }
+    const process = ctx.exec.spawn({
+        command,
+        args: [...input.args],
+        cwd: ctx.location.projectDir ?? ctx.location.homeDir,
+        env: ctx.env,
+        stdin: null,
+    });
+    let stdout = "";
+    let stderr = "";
+    for await (const chunk of process.chunks) {
+        if (chunk.channel === OUTPUT_CHANNEL.stdout) {
+            stdout += chunk.text;
+        }
+        else {
+            stderr += chunk.text;
+        }
+    }
+    const exit = await process.exit;
+    return {
+        stdout,
+        stderr: redactSecrets(stderr),
+        exit,
+    };
+}
+/** The one way a non-zero host command becomes a typed error. */
+export function hostCommandFailedError(command, result) {
+    // stdout is kept raw for parsing callers, so redact it here at the
+    // one place it can enter an error; stderr is redacted at capture.
+    const stdoutTail = redactSecrets(result.stdout.slice(-OUTPUT_TAIL_CHARS));
+    const stderrTail = result.stderr.slice(-OUTPUT_TAIL_CHARS);
+    return new AgentError({
+        code: AGENT_ERROR_CODE.failed,
+        message: `Host command "${command}" failed with exit code ${result.exit.code ?? "null"}`,
+        data: {
+            exitCode: result.exit.code,
+            stdoutTail: stdoutTail || null,
+            stderrTail: stderrTail || null,
+        },
+    });
+}
+export async function runHostCommand(ctx, input) {
+    const result = await runHostCommandResult(ctx, input);
+    if (result.exit.code !== 0) {
+        throw hostCommandFailedError(input.command, result);
+    }
+    return result;
+}

package/dist/host/validate-spec.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Catalog secret rules (K7): no literal secrets in an MCP server spec.
+ * `Authorization` headers are forbidden (use `bearerTokenEnvVar`), and
+ * suspicious literal values are rejected.
+ */
+import type { Issue } from "../core/error.js";
+import { type McpServerSpec } from "./capabilities.js";
+/** Returns an issue list; empty means valid (rule 3). */
+export declare function validateSpecSecrets(spec: McpServerSpec): Issue[];
+//# sourceMappingURL=validate-spec.d.ts.map

package/dist/host/validate-spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-spec.d.ts","sourceRoot":"","sources":["../../src/host/validate-spec.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAiB,KAAK,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAoEtE,yDAAyD;AACzD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,aAAa,GAAG,KAAK,EAAE,CAOhE"}

package/dist/host/validate-spec.js

@@ -0,0 +1,69 @@
+/**
+ * Catalog secret rules (K7): no literal secrets in an MCP server spec.
+ * `Authorization` headers are forbidden (use `bearerTokenEnvVar`), and
+ * suspicious literal values are rejected.
+ */
+import { MCP_TRANSPORT } from "./capabilities.js";
+const SECRET_LIKE_VALUE = /\b(sk-|ghp_|github_pat_|xox[baprs]-|eyJ)/;
+const AUTHORIZATION_HEADER = "authorization";
+const ISSUE_PATH = {
+    headers: "headers",
+};
+const SPEC_SECRET_ISSUE_CODE = {
+    authorizationHeaderForbidden: "authorization_header_forbidden",
+    literalSecret: "literal_secret",
+};
+const SPEC_SECRET_ISSUE_MESSAGE = {
+    authorizationHeaderForbidden: "Use bearerTokenEnvVar instead of an Authorization header",
+    literalSecret: "MCP server spec appears to contain a literal secret; use an env reference",
+};
+function checkAuthorizationHeaderNames(headers) {
+    const issues = [];
+    for (const name of Object.keys(headers)) {
+        if (name.toLowerCase() === AUTHORIZATION_HEADER) {
+            issues.push({
+                path: [ISSUE_PATH.headers, name],
+                code: SPEC_SECRET_ISSUE_CODE.authorizationHeaderForbidden,
+                message: SPEC_SECRET_ISSUE_MESSAGE.authorizationHeaderForbidden,
+            });
+        }
+    }
+    return issues;
+}
+function checkLiteralSecretStrings(value) {
+    const issues = [];
+    collectLiteralSecretStringIssues(value, [], issues);
+    return issues;
+}
+function collectLiteralSecretStringIssues(value, path, issues) {
+    if (typeof value === "string") {
+        if (SECRET_LIKE_VALUE.test(value)) {
+            issues.push({
+                path,
+                code: SPEC_SECRET_ISSUE_CODE.literalSecret,
+                message: SPEC_SECRET_ISSUE_MESSAGE.literalSecret,
+            });
+        }
+        return;
+    }
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => {
+            collectLiteralSecretStringIssues(item, [...path, index], issues);
+        });
+        return;
+    }
+    if (value !== null && typeof value === "object") {
+        for (const [key, item] of Object.entries(value)) {
+            collectLiteralSecretStringIssues(item, [...path, key], issues);
+        }
+    }
+}
+/** Returns an issue list; empty means valid (rule 3). */
+export function validateSpecSecrets(spec) {
+    return [
+        ...checkLiteralSecretStrings(spec),
+        ...(spec.transport === MCP_TRANSPORT.http
+            ? checkAuthorizationHeaderNames(spec.headers)
+            : []),
+    ];
+}

package/dist/index.d.ts

@@ -0,0 +1,69 @@
+/**
+ * `@alpacakit/agents` — run AI coding agents programmatically.
+ *
+ * One root entry holds the whole surface: extension points must never
+ * require knowing which internal layer owns them. Only genuine isolation
+ * lives on a subpath — dev fakes (`/testing`), the codex app-server client
+ * (`/codex`), the native keyring (`/keyring`), and machine-local config
+ * storage (`/config`).
+ */
+export { BUILTIN_AGENT_ID, type BuiltinAgentId, builtinAgentFactories, } from "./agents/builtin.js";
+export { claude, structuredQuotaMatcher } from "./agents/claude.js";
+export { capacityTextMatcher, codex } from "./agents/codex.js";
+export type { PiSessionEngineOptions } from "./agents/openai-compatible/pi/engine.js";
+export { PI_DEFAULT_CONTEXT_WINDOW, PI_DEFAULT_MAX_TOKENS, piSessionEngine, } from "./agents/openai-compatible/pi/engine.js";
+export type { JsonValue, OpenAiCompatibleConfig, OpenAiCompatibleConfigInput, OpenAiCompatibleEngine, } from "./agents/openai-compatible.js";
+export { openaiCompatible } from "./agents/openai-compatible.js";
+export type { LoginCapability, LoginContext, LoginEvent, LoginHandle, LoginHandler, LoginMethod, LoginOutcome, LoginRequest, LoginRun, } from "./auth/login.js";
+export { LOGIN_EVENT_TYPE, LOGIN_METHOD } from "./auth/login.js";
+export type { ApiKeyProfileOptions, AuthCapability, AuthMaterial, AuthMaterialDescriptor, AuthMaterialKind, AuthProfile, AuthStatus, HomeDirProfileOptions, MaterialHandler, MaterialHandlers, SecretRef, } from "./auth/material.js";
+export { AUTH_MATERIAL_KIND, AUTH_STATUS, createApiKeyProfile, createHomeDirProfile, envVarAuthMaterial, } from "./auth/material.js";
+export { fileProfileStore, type ProfileStore } from "./auth/profile-store.js";
+export { envResolver, requireSecret } from "./auth/secrets.js";
+export type { EnvPatch } from "./core/env.js";
+export { applyEnvPatch, EMPTY_ENV_PATCH, mergeEnvPatches, processEnv, } from "./core/env.js";
+export type { AgentErrorCode, AgentErrorData, AgentErrorOptions, AuthFailureReason, GuardViolation, Issue, NotAvailableCause, TimeoutKind, } from "./core/error.js";
+export { AGENT_ERROR_CODE, AgentError, AUTH_FAILURE_REASON, isAgentError, NOT_AVAILABLE_CAUSE, TIMEOUT_KIND, } from "./core/error.js";
+export type { Clock, Exec, ExecChunk, ExecExit, ExecProcess, ExecSpawnOptions, HttpClient, InteractiveExecProcess, InteractiveExecSpawnOptions, Logger, LogLevel, Ports, SecretResolver, SecretResolvers, TelemetrySink, } from "./core/ports.js";
+export { LOG_LEVEL } from "./core/ports.js";
+export { redactJsonSecrets, redactSecrets } from "./core/redact.js";
+export type { AgentEvent, AgentRunOutcome, RunCompletion, RunEvent, RunExit, RunHandle, RunResult, RunTelemetry, RunTiming, RunUsage, } from "./core/run.js";
+export { AGENT_EVENT_TYPE, RUN_COMPLETION_KIND, RUN_EVENT_TYPE, RUN_OUTCOME, } from "./core/run.js";
+export type { OutputChannel, ProcessSignal } from "./core/values.js";
+export { OUTPUT_CHANNEL, PROCESS_SIGNAL } from "./core/values.js";
+export type { FailureCorpusRecorder, FailureCorpusRecorderOptions, } from "./corpus/failure-corpus.js";
+export { createFailureCorpusRecorder } from "./corpus/failure-corpus.js";
+export type { AttemptStatus, AttemptTrace, Blocker, BlockerReason, Candidate, CandidateOptions, CreateFleetOptions, FleetAttemptRunOptions, Fleet, FleetOutcome, FleetPlainRunOptions, FleetOutcomeStatus, FleetRunOptions, FleetStructuredRunOptions, } from "./fleet/fleet.js";
+export { ATTEMPT_STATUS, BLOCKER_REASON, candidateForAgent, candidateFromProfile, candidateKey, createFleet, FLEET_OUTCOME_STATUS, profileCooldownKey, } from "./fleet/fleet.js";
+export type { CooldownScope, FailureAction, FailureActionKind, FailurePolicy, PolicyCode, } from "./fleet/policy.js";
+export { CAPACITY_DEFAULT_COOLDOWN_MS, COOLDOWN_SCOPE, defaultFailurePolicy, FAILURE_ACTION_KIND, QUOTA_DEFAULT_COOLDOWN_MS, } from "./fleet/policy.js";
+export type { CooldownKey, FleetStateStore } from "./fleet/store.js";
+export { fileFleetStore, memoryFleetStore } from "./fleet/store.js";
+export type { DoctorCapability, DoctorCheck, DoctorReport, InstalledSkill, InstallOptions, InstallOutcome, McpAvailability, McpCapability, McpScope, McpServerSpec, McpServerState, McpTransport, SkillAvailability, SkillSource, SkillSourceKind, SkillsCapability, StdioMcpServerSpec, } from "./host/capabilities.js";
+export { CAPABILITY_AVAILABILITY_STATUS, checkMcpAvailability, checkSkillAvailability, DOCTOR_CHECK_STATUS, INSTALL_STATUS, MCP_SCOPE, MCP_TRANSPORT, SKILL_SOURCE_KIND, } from "./host/capabilities.js";
+export type { HostContext, HostLocation } from "./host/context.js";
+export type { McpRequirementRef, SkillRequirementRef, } from "./host/requirement-ref.js";
+export { parseMcpRequirementRef, parseSkillRequirementRef, } from "./host/requirement-ref.js";
+export { validateSpecSecrets } from "./host/validate-spec.js";
+export type { ClassifiedFailure, FailureEvidence, FailureMatcher, } from "./kernel/classify.js";
+export { authIf, capacityIf, classifyFailure, parseCooldownHint, quotaIf, sharedFailureMatchers, } from "./kernel/classify.js";
+export type { ArgContext, CliAgentBlueprint, CliResultCapture, OutputState, SandboxArgBuilders, } from "./kernel/cli-agent.js";
+export { defineCliAgent } from "./kernel/cli-agent.js";
+export type { AgentDefinition, AgentRun, RunContext, } from "./kernel/definition.js";
+export { defineAgent } from "./kernel/definition.js";
+export type { EnvTemplate, EnvTemplateResolution, } from "./kernel/env-template.js";
+export { referencedEnvNames, resolveEnvTemplate, } from "./kernel/env-template.js";
+export type { AgentAuth, AgentDoctor, AgentLogin, AgentMcp, AgentSkills, } from "./kernel/facets.js";
+export type { Guard, GuardContext, GuardFactory } from "./kernel/guard.js";
+export { maxToolCalls, maxTurns, noProgress, repeatedOutput, } from "./kernel/guard.js";
+export type { Grant, Limits, ResolvedLimits, ResolvedRunOptions, ResolvedSandbox, RunOptions, Sandbox, SandboxMode, } from "./kernel/options.js";
+export { GRANT_KIND, SANDBOX_MODE } from "./kernel/options.js";
+export type { Agent, AgentRuntime, AgentRuntimeOptions, } from "./kernel/runtime.js";
+export { createAgentRuntime, resolvePorts } from "./kernel/runtime.js";
+export { type RunAgentOptions, runAgent } from "./run-agent.js";
+export type { ExtractionStrategy, JsonParseOutcome, Markers, } from "./structured/extract.js";
+export { DEFAULT_MARKERS, defaultExtractionStrategies, extractBlock, parseJsonResilient, } from "./structured/extract.js";
+export type { ContractPromptPlacement, OutputContract, ParseOutcome, RepairContext, StructuredAttempt, StructuredHandle, StructuredResult, StructuredRunOptions, } from "./structured/run-structured.js";
+export { CONTRACT_PROMPT_PLACEMENT } from "./structured/run-structured.js";
+export type { StandardSchemaIssue, StandardSchemaV1, } from "./structured/standard-schema.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,41 @@
+/**
+ * `@alpacakit/agents` — run AI coding agents programmatically.
+ *
+ * One root entry holds the whole surface: extension points must never
+ * require knowing which internal layer owns them. Only genuine isolation
+ * lives on a subpath — dev fakes (`/testing`), the codex app-server client
+ * (`/codex`), the native keyring (`/keyring`), and machine-local config
+ * storage (`/config`).
+ */
+export { BUILTIN_AGENT_ID, builtinAgentFactories, } from "./agents/builtin.js";
+export { claude, structuredQuotaMatcher } from "./agents/claude.js";
+export { capacityTextMatcher, codex } from "./agents/codex.js";
+export { PI_DEFAULT_CONTEXT_WINDOW, PI_DEFAULT_MAX_TOKENS, piSessionEngine, } from "./agents/openai-compatible/pi/engine.js";
+export { openaiCompatible } from "./agents/openai-compatible.js";
+export { LOGIN_EVENT_TYPE, LOGIN_METHOD } from "./auth/login.js";
+export { AUTH_MATERIAL_KIND, AUTH_STATUS, createApiKeyProfile, createHomeDirProfile, envVarAuthMaterial, } from "./auth/material.js";
+export { fileProfileStore } from "./auth/profile-store.js";
+export { envResolver, requireSecret } from "./auth/secrets.js";
+export { applyEnvPatch, EMPTY_ENV_PATCH, mergeEnvPatches, processEnv, } from "./core/env.js";
+export { AGENT_ERROR_CODE, AgentError, AUTH_FAILURE_REASON, isAgentError, NOT_AVAILABLE_CAUSE, TIMEOUT_KIND, } from "./core/error.js";
+export { LOG_LEVEL } from "./core/ports.js";
+export { redactJsonSecrets, redactSecrets } from "./core/redact.js";
+export { AGENT_EVENT_TYPE, RUN_COMPLETION_KIND, RUN_EVENT_TYPE, RUN_OUTCOME, } from "./core/run.js";
+export { OUTPUT_CHANNEL, PROCESS_SIGNAL } from "./core/values.js";
+export { createFailureCorpusRecorder } from "./corpus/failure-corpus.js";
+export { ATTEMPT_STATUS, BLOCKER_REASON, candidateForAgent, candidateFromProfile, candidateKey, createFleet, FLEET_OUTCOME_STATUS, profileCooldownKey, } from "./fleet/fleet.js";
+export { CAPACITY_DEFAULT_COOLDOWN_MS, COOLDOWN_SCOPE, defaultFailurePolicy, FAILURE_ACTION_KIND, QUOTA_DEFAULT_COOLDOWN_MS, } from "./fleet/policy.js";
+export { fileFleetStore, memoryFleetStore } from "./fleet/store.js";
+export { CAPABILITY_AVAILABILITY_STATUS, checkMcpAvailability, checkSkillAvailability, DOCTOR_CHECK_STATUS, INSTALL_STATUS, MCP_SCOPE, MCP_TRANSPORT, SKILL_SOURCE_KIND, } from "./host/capabilities.js";
+export { parseMcpRequirementRef, parseSkillRequirementRef, } from "./host/requirement-ref.js";
+export { validateSpecSecrets } from "./host/validate-spec.js";
+export { authIf, capacityIf, classifyFailure, parseCooldownHint, quotaIf, sharedFailureMatchers, } from "./kernel/classify.js";
+export { defineCliAgent } from "./kernel/cli-agent.js";
+export { defineAgent } from "./kernel/definition.js";
+export { referencedEnvNames, resolveEnvTemplate, } from "./kernel/env-template.js";
+export { maxToolCalls, maxTurns, noProgress, repeatedOutput, } from "./kernel/guard.js";
+export { GRANT_KIND, SANDBOX_MODE } from "./kernel/options.js";
+export { createAgentRuntime, resolvePorts } from "./kernel/runtime.js";
+export { runAgent } from "./run-agent.js";
+export { DEFAULT_MARKERS, defaultExtractionStrategies, extractBlock, parseJsonResilient, } from "./structured/extract.js";
+export { CONTRACT_PROMPT_PLACEMENT } from "./structured/run-structured.js";

package/dist/kernel/classify.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Failure classification (design "Errors"): the matcher contract, the
+ * combinators custom agents build on, cooldown-hint parsing, and the
+ * generic quota / auth free-text matchers shared by every agent
+ * (v1 F3/F5 signals, kept verbatim). Provider-specific matchers live on
+ * their adapter modules and enter via the blueprints' `classify` arrays.
+ */
+import type { AgentErrorCode, AgentErrorData, AuthFailureReason } from "../core/error.js";
+export type FailureEvidence = {
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+    signal: string | null;
+    /** Epoch ms used as the base for relative cooldown hints. */
+    now: number;
+};
+export type ClassifiedFailure<C extends AgentErrorCode = AgentErrorCode> = {
+    [K in C]: {
+        code: K;
+        message: string;
+        data: AgentErrorData[K];
+    };
+}[C];
+export type FailureMatcher = (evidence: FailureEvidence) => ClassifiedFailure | null;
+export declare function parseEpochTimestamp(value: number): string;
+/**
+ * Cooldown-time parsing (F3): ISO timestamps, epoch digits after
+ * reset/retry-after, "retry after N s", and relative "in N minutes".
+ */
+export declare function parseCooldownHint(text: string, now: number): string | null;
+/** Matcher combinator: classify as quota when the pattern matches. */
+export declare function quotaIf(pattern: RegExp): FailureMatcher;
+/** Matcher combinator: classify as capacity when the pattern matches. */
+export declare function capacityIf(pattern: RegExp): FailureMatcher;
+export declare function detectAuthReason(text: string): AuthFailureReason;
+/** Matcher combinator: classify as auth when the pattern matches. */
+export declare function authIf(pattern: RegExp): FailureMatcher;
+/**
+ * Shared matchers, consulted after agent-specific ones. Provider-specific
+ * structured quota and capacity text matchers live on built-in blueprints.
+ */
+export declare const sharedFailureMatchers: readonly FailureMatcher[];
+export declare function classifyFailure(matchers: readonly FailureMatcher[], evidence: FailureEvidence): ClassifiedFailure | null;
+//# sourceMappingURL=classify.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"classify.d.ts","sourceRoot":"","sources":["../../src/kernel/classify.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,cAAc,EACd,iBAAiB,EAClB,MAAM,kBAAkB,CAAC;AAG1B,MAAM,MAAM,eAAe,GAAG;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,6DAA6D;IAC7D,GAAG,EAAE,MAAM,CAAC;CACb,CAAC;AAEF,MAAM,MAAM,iBAAiB,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,IAAI;KACxE,CAAC,IAAI,CAAC,GAAG;QAAE,IAAI,EAAE,CAAC,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC,CAAA;KAAE;CAChE,CAAC,CAAC,CAAC,CAAC;AAEL,MAAM,MAAM,cAAc,GAAG,CAC3B,QAAQ,EAAE,eAAe,KACtB,iBAAiB,GAAG,IAAI,CAAC;AAuB9B,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGzD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAoB1E;AAED,sEAAsE;AACtE,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAYvD;AAED,yEAAyE;AACzE,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAY1D;AAiBD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,CAOhE;AAED,qEAAqE;AACrE,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAatD;AAQD;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,SAAS,cAAc,EAG1D,CAAC;AAEF,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,SAAS,cAAc,EAAE,EACnC,QAAQ,EAAE,eAAe,GACxB,iBAAiB,GAAG,IAAI,CAQ1B"}