@alpacakit/agents 0.1.0-beta.19

package/dist/core/redact.js

@@ -0,0 +1,66 @@
+/**
+ * Library-wide rule (design F7): every surfaced diagnostic passes secret
+ * redaction before it can appear in an error message or telemetry event.
+ */
+const SECRET_PATTERNS = [
+    /\bsk-[A-Za-z0-9_-]{8,}\b/g,
+    /\bsk-ant-[A-Za-z0-9_-]{8,}\b/g,
+    /\bgh[pousr]_[A-Za-z0-9]{20,}\b/g,
+    /\bgithub_pat_[A-Za-z0-9_]{20,}\b/g,
+    /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g,
+    /\bBearer\s+[A-Za-z0-9._~+/=-]{8,}/g,
+    /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9._-]{10,}\b/g,
+];
+const REDACTED = "[redacted]";
+const SENSITIVE_JSON_KEY_SUFFIXES = [
+    "apikey",
+    "accesskey",
+    "passwd",
+    "password",
+    "privatekey",
+    "secret",
+    "token",
+];
+const CREDENTIAL_REDACTION_RULES = [
+    {
+        pattern: /([a-z][a-z0-9+.-]*:\/\/)([^/\s:@]+):([^/\s@]+)@/giu,
+        replacement: `$1${REDACTED}@`,
+    },
+    {
+        pattern: /(^|[\s;])((?:_?auth[_-]?token|api[_-]?key|access[_-]?token|password|passwd|secret|token)\s*=\s*)([^\s"'`]+)/giu,
+        replacement: `$1$2${REDACTED}`,
+    },
+    {
+        pattern: /(^|[;\r\n])((?:_?auth[_-]?token|api[_-]?key|access[_-]?token|password|passwd|secret|token)\s*:\s*)([^\s"'`]+)/giu,
+        replacement: `$1$2${REDACTED}`,
+    },
+];
+export function redactSecrets(text) {
+    let redacted = text;
+    for (const pattern of SECRET_PATTERNS) {
+        redacted = redacted.replace(pattern, REDACTED);
+    }
+    for (const rule of CREDENTIAL_REDACTION_RULES) {
+        redacted = redacted.replace(rule.pattern, rule.replacement);
+    }
+    return redacted;
+}
+export function redactJsonSecrets(value) {
+    if (typeof value === "string") {
+        return redactSecrets(value);
+    }
+    if (Array.isArray(value)) {
+        return value.map(redactJsonSecrets);
+    }
+    if (value === null || typeof value !== "object") {
+        return value;
+    }
+    return Object.fromEntries(Object.entries(value).map(([key, entry]) => [
+        key,
+        isSensitiveJsonKey(key) ? REDACTED : redactJsonSecrets(entry),
+    ]));
+}
+function isSensitiveJsonKey(key) {
+    const normalized = key.replaceAll(/[^a-z0-9]/giu, "").toLowerCase();
+    return SENSITIVE_JSON_KEY_SUFFIXES.some((suffix) => normalized.endsWith(suffix));
+}

package/dist/core/run.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Run-plane vocabulary. Adapters yield only `AgentEvent`; the kernel
+ * brackets every run with `started`/`ended`, so lifecycle forgery is
+ * unrepresentable. Outbound types follow absence rule 2: keys always
+ * present, `null` is meaningful absence.
+ */
+import type { AgentErrorCode } from "./error.js";
+import type { OutputChannel } from "./values.js";
+export declare const AGENT_EVENT_TYPE: {
+    readonly output: "output";
+    readonly message: "message";
+    readonly turn: "turn";
+    readonly tool: "tool";
+    readonly trace: "trace";
+    readonly failureClassified: "failure_classified";
+};
+export declare const RUN_EVENT_TYPE: {
+    readonly started: "started";
+    readonly ended: "ended";
+};
+export declare const RUN_OUTCOME: {
+    readonly completed: "completed";
+    readonly failed: "failed";
+    readonly cancelled: "cancelled";
+};
+export declare const RUN_COMPLETION_KIND: {
+    readonly natural: "natural";
+    readonly earlyGrace: "early-grace";
+};
+export type AgentEvent = {
+    type: typeof AGENT_EVENT_TYPE.output;
+    channel: OutputChannel;
+    chunk: string;
+} | {
+    type: typeof AGENT_EVENT_TYPE.message;
+    text: string;
+} | {
+    type: typeof AGENT_EVENT_TYPE.turn;
+} | {
+    type: typeof AGENT_EVENT_TYPE.tool;
+    name: string;
+} | {
+    type: typeof AGENT_EVENT_TYPE.trace;
+    data: unknown;
+} | {
+    type: typeof AGENT_EVENT_TYPE.failureClassified;
+    code: AgentErrorCode;
+    evidence: {
+        stdoutTail: string | null;
+        stderrTail: string | null;
+        exitCode: number | null;
+        signal: string | null;
+    };
+};
+export type RunEvent = AgentEvent | {
+    type: typeof RUN_EVENT_TYPE.started;
+    model: string | null;
+} | {
+    type: typeof RUN_EVENT_TYPE.ended;
+    outcome: (typeof RUN_OUTCOME)[keyof typeof RUN_OUTCOME];
+};
+/** Identity lives on the telemetry envelope, never on each event. */
+export type RunTelemetry = {
+    runId: string;
+    agentId: string;
+    event: RunEvent;
+};
+export type RunTiming = {
+    startedAt: string;
+    endedAt: string;
+    durationMs: number;
+};
+export type RunCompletion = {
+    kind: typeof RUN_COMPLETION_KIND.natural;
+} | {
+    kind: typeof RUN_COMPLETION_KIND.earlyGrace;
+};
+export type RunExit = {
+    code: number | null;
+    signal: string | null;
+    completion: RunCompletion;
+};
+export type RunUsage = {
+    inputTokens: number | null;
+    outputTokens: number | null;
+    costUsd: number | null;
+};
+export type RunResult = {
+    runId: string;
+    text: string;
+    agentId: string;
+    model: string | null;
+    timing: RunTiming;
+    exit: RunExit | null;
+    raw: {
+        stdout: string;
+        stderr: string;
+    } | null;
+    usage: RunUsage | null;
+};
+/**
+ * What an adapter's generator returns. The kernel completes it into a
+ * `RunResult` — adapters cannot know `runId` or timing, so those never
+ * appear on the adapter side.
+ */
+export type AgentRunOutcome = {
+    text: string;
+    model: string | null;
+    exit: RunExit | null;
+    raw: {
+        stdout: string;
+        stderr: string;
+    } | null;
+    usage: RunUsage | null;
+};
+/**
+ * Awaitable handle (execa-style): `await handle` ≡ `await handle.result`.
+ * Streaming callers iterate `events`; not consuming never blocks the run.
+ */
+export type RunHandle = PromiseLike<RunResult> & {
+    readonly runId: string;
+    readonly events: AsyncIterable<RunEvent>;
+    readonly result: Promise<RunResult>;
+};
+//# sourceMappingURL=run.d.ts.map

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

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

package/dist/core/run.js

@@ -0,0 +1,27 @@
+/**
+ * Run-plane vocabulary. Adapters yield only `AgentEvent`; the kernel
+ * brackets every run with `started`/`ended`, so lifecycle forgery is
+ * unrepresentable. Outbound types follow absence rule 2: keys always
+ * present, `null` is meaningful absence.
+ */
+export const AGENT_EVENT_TYPE = {
+    output: "output",
+    message: "message",
+    turn: "turn",
+    tool: "tool",
+    trace: "trace",
+    failureClassified: "failure_classified",
+};
+export const RUN_EVENT_TYPE = {
+    started: "started",
+    ended: "ended",
+};
+export const RUN_OUTCOME = {
+    completed: "completed",
+    failed: "failed",
+    cancelled: "cancelled",
+};
+export const RUN_COMPLETION_KIND = {
+    natural: "natural",
+    earlyGrace: "early-grace",
+};

package/dist/core/values.d.ts

@@ -0,0 +1,12 @@
+export declare const OUTPUT_CHANNEL: {
+    readonly stdout: "stdout";
+    readonly stderr: "stderr";
+};
+export type OutputChannel = (typeof OUTPUT_CHANNEL)[keyof typeof OUTPUT_CHANNEL];
+export declare const PROCESS_SIGNAL: {
+    readonly sigterm: "SIGTERM";
+    readonly sigkill: "SIGKILL";
+};
+export type ProcessSignal = (typeof PROCESS_SIGNAL)[keyof typeof PROCESS_SIGNAL];
+export declare const TEXT_ENCODING = "utf8";
+//# sourceMappingURL=values.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"values.d.ts","sourceRoot":"","sources":["../../src/core/values.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,cAAc;;;CAGjB,CAAC;AAEX,MAAM,MAAM,aAAa,GACvB,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,OAAO,cAAc,CAAC,CAAC;AAEvD,eAAO,MAAM,cAAc;;;CAGjB,CAAC;AAEX,MAAM,MAAM,aAAa,GACvB,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,OAAO,cAAc,CAAC,CAAC;AAEvD,eAAO,MAAM,aAAa,SAAS,CAAC"}

package/dist/core/values.js

@@ -0,0 +1,9 @@
+export const OUTPUT_CHANNEL = {
+    stdout: "stdout",
+    stderr: "stderr",
+};
+export const PROCESS_SIGNAL = {
+    sigterm: "SIGTERM",
+    sigkill: "SIGKILL",
+};
+export const TEXT_ENCODING = "utf8";

package/dist/corpus/failure-corpus.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Consumer-side corpus capture (design v D2): a `TelemetrySink` that a
+ * composition subscribes behind an explicit dev flag. It lives outside
+ * the kernel on purpose — the kernel only emits `failure_classified` on
+ * the run event stream; recording candidates to disk is a consumer
+ * concern. Promotion into `tests/fixtures/classify/` is manual curation.
+ */
+import type { TelemetrySink } from "../core/ports.js";
+export interface FailureCorpusRecorder extends TelemetrySink {
+    /** Settle pending writes; rejects once with the last write failure. */
+    flush(): Promise<void>;
+}
+/**
+ * Recording is opt-in by construction: a composition that does not want
+ * a corpus simply never creates a recorder.
+ */
+export type FailureCorpusRecorderOptions = {
+    directory: string;
+};
+export declare function createFailureCorpusRecorder(options: FailureCorpusRecorderOptions): FailureCorpusRecorder;
+//# sourceMappingURL=failure-corpus.d.ts.map

package/dist/corpus/failure-corpus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"failure-corpus.d.ts","sourceRoot":"","sources":["../../src/corpus/failure-corpus.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAOtD,MAAM,WAAW,qBAAsB,SAAQ,aAAa;IAC1D,uEAAuE;IACvE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,MAAM,4BAA4B,GAAG;IACzC,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AA8GF,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,4BAA4B,GACpC,qBAAqB,CAEvB"}

package/dist/corpus/failure-corpus.js

@@ -0,0 +1,89 @@
+/**
+ * Consumer-side corpus capture (design v D2): a `TelemetrySink` that a
+ * composition subscribes behind an explicit dev flag. It lives outside
+ * the kernel on purpose — the kernel only emits `failure_classified` on
+ * the run event stream; recording candidates to disk is a consumer
+ * concern. Promotion into `tests/fixtures/classify/` is manual curation.
+ */
+import { readdir, rm } from "node:fs/promises";
+import path from "node:path";
+import { writeFileAtomically } from "../core/fs.js";
+import { redactSecrets } from "../core/redact.js";
+import { AGENT_EVENT_TYPE } from "../core/run.js";
+const MAX_CORPUS_FILES = 200;
+const CORPUS_FILE_EXTENSION = ".json";
+function isFailureClassifiedTelemetry(telemetry) {
+    return telemetry.event.type === AGENT_EVENT_TYPE.failureClassified;
+}
+function safeFilePart(value) {
+    return value.replace(/[^A-Za-z0-9_.-]/gu, "_");
+}
+async function pruneCorpusFiles(directory) {
+    const entries = await readdir(directory, { withFileTypes: true });
+    const files = entries
+        .filter((entry) => entry.isFile() && entry.name.endsWith(CORPUS_FILE_EXTENSION))
+        .map((entry) => entry.name)
+        .sort();
+    const excess = files.length - MAX_CORPUS_FILES;
+    if (excess <= 0) {
+        return;
+    }
+    await Promise.all(files.slice(0, excess).map((file) => rm(path.join(directory, file))));
+}
+async function writeCandidate(directory, telemetry, sequence) {
+    const event = telemetry.event;
+    const agentDirectory = path.join(directory, safeFilePart(telemetry.agentId));
+    const fixture = {
+        description: `Captured ${telemetry.agentId} failure classified as ${event.code}`,
+        evidence: {
+            stdout: event.evidence.stdoutTail ?? "",
+            stderr: event.evidence.stderrTail ?? "",
+            exitCode: event.evidence.exitCode,
+            signal: event.evidence.signal,
+        },
+        expected: null,
+    };
+    const filename = [
+        String(Date.now()).padStart(13, "0"),
+        String(sequence).padStart(4, "0"),
+        safeFilePart(telemetry.runId),
+    ].join("-");
+    const raw = `${JSON.stringify(fixture, null, 2)}\n`;
+    await writeFileAtomically(path.join(agentDirectory, `${filename}${CORPUS_FILE_EXTENSION}`), redactSecrets(raw));
+    await pruneCorpusFiles(agentDirectory);
+}
+class FileFailureCorpusRecorder {
+    directory;
+    sequence = 0;
+    // The chain never rejects: each link swallows its own failure into
+    // `lastWriteError` so one bad write cannot poison later candidates or
+    // leave an unhandled rejection dangling.
+    queue = Promise.resolve();
+    lastWriteError = null;
+    constructor(directory) {
+        this.directory = directory;
+    }
+    emit(telemetry) {
+        if (!isFailureClassifiedTelemetry(telemetry)) {
+            return;
+        }
+        this.sequence += 1;
+        const current = this.sequence;
+        this.queue = this.queue
+            .then(() => writeCandidate(this.directory, telemetry, current))
+            .catch((error) => {
+            this.lastWriteError = error;
+        });
+    }
+    async flush() {
+        await this.queue;
+        if (this.lastWriteError !== null) {
+            const error = this.lastWriteError;
+            this.lastWriteError = null;
+            throw error;
+        }
+    }
+}
+export function createFailureCorpusRecorder(options) {
+    return new FileFailureCorpusRecorder(options.directory);
+}

package/dist/fleet/fleet.d.ts

@@ -0,0 +1,120 @@
+/**
+ * The fleet (design "Fleet"): failover is a strategy over an ordered
+ * candidate list plus a state store. The consumer decides what the
+ * candidates are and in which order; `attempt` is the composition seam.
+ * The agent handed to `attempt` is candidate-bound: auth env, model /
+ * effort defaults, and the linked signal are already folded in.
+ */
+import type { AuthProfile } from "../auth/material.js";
+import { AgentError, type AgentErrorCode } from "../core/error.js";
+import type { RunResult } from "../core/run.js";
+import type { RunOptions } from "../kernel/options.js";
+import type { Agent, AgentRuntime } from "../kernel/runtime.js";
+import type { StructuredResult, StructuredRunOptions } from "../structured/run-structured.js";
+import { type FailurePolicy } from "./policy.js";
+import { type CooldownKey, type FleetStateStore } from "./store.js";
+/** Inbound (rule 1); `profile.agentId` must equal `agentId`. */
+export type Candidate<Id extends string = string> = {
+    agentId: Id;
+    profile?: AuthProfile<Id>;
+    model?: string;
+    effort?: string;
+};
+export type CandidateOptions = {
+    readonly model?: string;
+    readonly effort?: string;
+};
+export declare function candidateFromProfile<const Id extends string>(profile: AuthProfile<Id>, options?: CandidateOptions): Candidate<Id>;
+export declare function candidateForAgent<const Id extends string>(agentId: Id, options?: CandidateOptions): Candidate<Id>;
+export declare function candidateKey(candidate: Candidate): CooldownKey;
+/**
+ * Store key for a profile-scoped cooldown (`CooldownScope` "profile").
+ * The store stays a flat key-value map, but the key is an encoded,
+ * branded value so raw profile/model text cannot collide by separator.
+ */
+export declare function profileCooldownKey(profileId: string): CooldownKey;
+export declare const BLOCKER_REASON: {
+    readonly cooldown: "cooldown";
+    readonly retryableFailure: "retryable-failure";
+    readonly authInvalid: "auth-invalid";
+    readonly manualAuthRequired: "manual-auth-required";
+};
+export type BlockerReason = (typeof BLOCKER_REASON)[keyof typeof BLOCKER_REASON];
+export type Blocker<Id extends string = string> = {
+    candidate: Candidate<Id>;
+    reason: typeof BLOCKER_REASON.cooldown;
+    until: string;
+} | {
+    candidate: Candidate<Id>;
+    reason: typeof BLOCKER_REASON.retryableFailure | typeof BLOCKER_REASON.authInvalid | typeof BLOCKER_REASON.manualAuthRequired;
+    until: null;
+};
+export declare const ATTEMPT_STATUS: {
+    readonly completed: "completed";
+    readonly failed: "failed";
+    readonly skipped: "skipped";
+};
+export type AttemptStatus = (typeof ATTEMPT_STATUS)[keyof typeof ATTEMPT_STATUS];
+export type AttemptTrace<Id extends string = string> = {
+    candidate: Candidate<Id>;
+    status: typeof ATTEMPT_STATUS.completed;
+} | {
+    candidate: Candidate<Id>;
+    status: typeof ATTEMPT_STATUS.failed;
+    code: AgentErrorCode;
+    detail: string;
+} | {
+    candidate: Candidate<Id>;
+    status: typeof ATTEMPT_STATUS.skipped;
+    reason: BlockerReason;
+    detail: string;
+};
+export declare const FLEET_OUTCOME_STATUS: {
+    readonly completed: "completed";
+    readonly deferred: "deferred";
+    readonly failed: "failed";
+};
+export type FleetOutcomeStatus = (typeof FLEET_OUTCOME_STATUS)[keyof typeof FLEET_OUTCOME_STATUS];
+export type FleetOutcome<T, Id extends string = string> = {
+    status: typeof FLEET_OUTCOME_STATUS.completed;
+    value: T;
+    candidate: Candidate<Id>;
+    attempts: AttemptTrace<Id>[];
+} | {
+    status: typeof FLEET_OUTCOME_STATUS.deferred;
+    blockers: Blocker<Id>[];
+    earliestRetryAt: string | null;
+    attempts: AttemptTrace<Id>[];
+} | {
+    status: typeof FLEET_OUTCOME_STATUS.failed;
+    error: AgentError;
+    attempts: AttemptTrace<Id>[];
+};
+export type FleetAttemptRunOptions<T, Id extends string = string> = {
+    candidates: readonly Candidate<Id>[];
+    attempt: (agent: Agent<Id>, candidate: Candidate<Id>) => Promise<T>;
+    signal?: AbortSignal;
+};
+export type FleetPlainRunOptions<Id extends string = string> = {
+    candidates: readonly Candidate<Id>[];
+    runOptions: RunOptions;
+    signal?: AbortSignal;
+};
+export type FleetStructuredRunOptions<T, Id extends string = string> = {
+    candidates: readonly Candidate<Id>[];
+    runOptions: StructuredRunOptions<T>;
+    signal?: AbortSignal;
+};
+export type FleetRunOptions<T, Id extends string = string> = FleetAttemptRunOptions<T, Id> | FleetPlainRunOptions<Id> | FleetStructuredRunOptions<T, Id>;
+export interface Fleet<Id extends string = string> {
+    run<T>(options: FleetStructuredRunOptions<T, Id>): Promise<FleetOutcome<StructuredResult<T>, Id>>;
+    run(options: FleetPlainRunOptions<Id>): Promise<FleetOutcome<RunResult, Id>>;
+    run<T>(options: FleetAttemptRunOptions<T, Id>): Promise<FleetOutcome<T, Id>>;
+}
+export type CreateFleetOptions<Id extends string> = {
+    runtime: AgentRuntime<Id>;
+    store?: FleetStateStore;
+    policy?: Partial<FailurePolicy>;
+};
+export declare function createFleet<Id extends string>(options: CreateFleetOptions<Id>): Fleet<Id>;
+//# sourceMappingURL=fleet.d.ts.map

package/dist/fleet/fleet.d.ts.map

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