@alpacakit/agents 0.1.0-beta.19

package/dist/fleet/fleet.js

@@ -0,0 +1,409 @@
+/**
+ * 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 { EMPTY_ENV_PATCH, mergeEnvPatches, } from "../core/env.js";
+import { AGENT_ERROR_CODE, AgentError, isAgentError, } from "../core/error.js";
+import { totalKeyedHandler } from "../kernel/keyed.js";
+import { COOLDOWN_SCOPE, FAILURE_ACTION_KIND, resolveFailurePolicy, } from "./policy.js";
+import { memoryFleetStore, } from "./store.js";
+export function candidateFromProfile(profile, options = {}) {
+    return candidateWithOptions({
+        agentId: profile.agentId,
+        profile,
+    }, options);
+}
+export function candidateForAgent(agentId, options = {}) {
+    return candidateWithOptions({ agentId }, options);
+}
+function candidateWithOptions(candidate, options) {
+    const next = { ...candidate };
+    if (options.model !== undefined) {
+        next.model = options.model;
+    }
+    if (options.effort !== undefined) {
+        next.effort = options.effort;
+    }
+    return next;
+}
+function encodeCooldownKey(parts) {
+    return JSON.stringify(parts);
+}
+export function candidateKey(candidate) {
+    return encodeCooldownKey([
+        COOLDOWN_SCOPE.candidate,
+        candidate.agentId,
+        candidate.profile?.id ?? null,
+        candidate.model ?? null,
+        candidate.effort ?? null,
+    ]);
+}
+/**
+ * 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 function profileCooldownKey(profileId) {
+    return encodeCooldownKey([COOLDOWN_SCOPE.profile, profileId]);
+}
+export const BLOCKER_REASON = {
+    cooldown: "cooldown",
+    retryableFailure: "retryable-failure",
+    authInvalid: "auth-invalid",
+    manualAuthRequired: "manual-auth-required",
+};
+export const ATTEMPT_STATUS = {
+    completed: "completed",
+    failed: "failed",
+    skipped: "skipped",
+};
+export const FLEET_OUTCOME_STATUS = {
+    completed: "completed",
+    deferred: "deferred",
+    failed: "failed",
+};
+const FLEET_ATTEMPT_OPTION_KEY = "attempt";
+function resolveCandidateIdentity(candidate) {
+    const key = candidateKey(candidate);
+    const profileId = candidate.profile?.id ?? null;
+    return {
+        candidate,
+        key,
+        profileId,
+        cooldownKeys: profileId === null ? [key] : [profileCooldownKey(profileId), key],
+    };
+}
+function combineAbortSignals(...signals) {
+    const active = signals.filter((signal) => signal !== undefined);
+    const [first] = active;
+    if (first === undefined) {
+        return undefined;
+    }
+    return active.length === 1 ? first : AbortSignal.any(active);
+}
+function withCandidateRunBinding(options, binding) {
+    const runOptions = {
+        ...options,
+        env: mergeEnvPatches(binding.authPatch, options.env ?? EMPTY_ENV_PATCH),
+    };
+    const { candidate } = binding;
+    if (runOptions.model === undefined && candidate.model !== undefined) {
+        runOptions.model = candidate.model;
+    }
+    if (runOptions.effort === undefined && candidate.effort !== undefined) {
+        runOptions.effort = candidate.effort;
+    }
+    const signal = combineAbortSignals(binding.fleetSignal, options.signal);
+    if (signal !== undefined) {
+        runOptions.signal = signal;
+    }
+    return runOptions;
+}
+function bindCandidate(agent, candidate, authPatch, fleetSignal) {
+    function run(options) {
+        return agent.run(withCandidateRunBinding(options, {
+            candidate,
+            authPatch,
+            fleetSignal,
+        }));
+    }
+    return {
+        ...agent,
+        run,
+    };
+}
+function invalidCandidate(reason) {
+    return new AgentError({
+        code: AGENT_ERROR_CODE.invalidInput,
+        message: reason,
+        data: { reason },
+    });
+}
+function completedAttempt(candidate) {
+    return { candidate, status: ATTEMPT_STATUS.completed };
+}
+function failedAttempt(candidate, error) {
+    return {
+        candidate,
+        status: ATTEMPT_STATUS.failed,
+        code: error.code,
+        detail: error.message,
+    };
+}
+function skippedAttempt(blocker, detail) {
+    return {
+        candidate: blocker.candidate,
+        status: ATTEMPT_STATUS.skipped,
+        reason: blocker.reason,
+        detail,
+    };
+}
+function cooldownFromError(error, fallbackMs, now) {
+    if (isAgentError(error, AGENT_ERROR_CODE.quota) ||
+        isAgentError(error, AGENT_ERROR_CODE.capacity)) {
+        if (error.data.cooldownUntil !== null) {
+            return error.data.cooldownUntil;
+        }
+    }
+    return fallbackMs === null ? null : new Date(now + fallbackMs).toISOString();
+}
+/**
+ * A candidate is blocked until every active cooldown expires, so the
+ * consulted levels (profile, candidate — A4) reduce to the latest one.
+ * ISO-8601 UTC strings compare lexicographically.
+ */
+class CandidateReadinessResolver {
+    store;
+    clock;
+    constructor(store, clock) {
+        this.store = store;
+        this.clock = clock;
+    }
+    async block(identity) {
+        if (identity.profileId !== null &&
+            (await this.store.isAuthInvalid(identity.profileId))) {
+            const blocker = {
+                candidate: identity.candidate,
+                reason: BLOCKER_REASON.authInvalid,
+                until: null,
+            };
+            return {
+                blocker,
+                trace: skippedAttempt(blocker, `profile "${identity.profileId}" is marked auth-invalid`),
+            };
+        }
+        const cooldownUntil = await this.activeCooldownUntil(identity.cooldownKeys);
+        if (cooldownUntil === null) {
+            return null;
+        }
+        const blocker = {
+            candidate: identity.candidate,
+            reason: BLOCKER_REASON.cooldown,
+            until: cooldownUntil,
+        };
+        return {
+            blocker,
+            trace: skippedAttempt(blocker, `cooling down until ${cooldownUntil}`),
+        };
+    }
+    async activeCooldownUntil(keys) {
+        const now = this.clock.now();
+        let latest = null;
+        for (const key of keys) {
+            const until = await this.store.getCooldownUntil(key);
+            if (until !== null &&
+                Date.parse(until) > now &&
+                (latest === null || until > latest)) {
+                latest = until;
+            }
+        }
+        return latest;
+    }
+}
+function earliestRetryAt(blockers) {
+    const times = blockers
+        .map((blocker) => blocker.until)
+        .filter((until) => until !== null)
+        .sort();
+    return times[0] ?? null;
+}
+async function resolveAuthPatch(agent, profile, agentId) {
+    if (profile === undefined) {
+        return EMPTY_ENV_PATCH;
+    }
+    if (profile.agentId !== agentId) {
+        throw invalidCandidate(`Profile "${profile.id}" targets agent "${profile.agentId}", not "${agentId}"`);
+    }
+    if (agent.auth === null) {
+        throw invalidCandidate(`Agent "${agentId}" has no auth capability but candidate carries profile "${profile.id}"`);
+    }
+    return agent.auth.toEnv(profile.material);
+}
+class CandidateAgentBinder {
+    runtime;
+    constructor(runtime) {
+        this.runtime = runtime;
+    }
+    async bind(identity, fleetSignal) {
+        const agent = this.runtime.agent(identity.candidate.agentId);
+        const authPatch = await resolveAuthPatch(agent, identity.candidate.profile, identity.candidate.agentId);
+        return bindCandidate(agent, identity.candidate, authPatch, fleetSignal);
+    }
+}
+const FAILURE_DISPOSITION_KIND = {
+    terminal: "terminal",
+    blocked: "blocked",
+};
+const terminalPolicyCodes = new Set([
+    AGENT_ERROR_CODE.invalidInput,
+    AGENT_ERROR_CODE.cancelled,
+]);
+function isPolicyCode(code) {
+    return !terminalPolicyCodes.has(code);
+}
+function terminalDisposition(error) {
+    return { kind: FAILURE_DISPOSITION_KIND.terminal, error };
+}
+function blockedDisposition(blocker) {
+    return { kind: FAILURE_DISPOSITION_KIND.blocked, blocker };
+}
+function failoverBlocker(identity, until) {
+    return until === null
+        ? {
+            candidate: identity.candidate,
+            reason: BLOCKER_REASON.retryableFailure,
+            until: null,
+        }
+        : {
+            candidate: identity.candidate,
+            reason: BLOCKER_REASON.cooldown,
+            until,
+        };
+}
+const failureActionHandlers = {
+    [FAILURE_ACTION_KIND.terminal]: async (_action, context) => terminalDisposition(context.error),
+    [FAILURE_ACTION_KIND.markAuthInvalid]: async (_action, context) => {
+        const { identity, store } = context;
+        if (identity.profileId !== null) {
+            await store.markAuthInvalid(identity.profileId);
+        }
+        return blockedDisposition({
+            candidate: identity.candidate,
+            reason: identity.profileId === null
+                ? BLOCKER_REASON.manualAuthRequired
+                : BLOCKER_REASON.authInvalid,
+            until: null,
+        });
+    },
+    [FAILURE_ACTION_KIND.failover]: async (action, context) => {
+        const { identity, error, store, clock } = context;
+        const until = cooldownFromError(error, action.cooldownMs, clock.now());
+        if (until !== null) {
+            const scopeKey = action.scope === COOLDOWN_SCOPE.profile && identity.profileId !== null
+                ? profileCooldownKey(identity.profileId)
+                : identity.key;
+            await store.setCooldownUntil(scopeKey, until);
+        }
+        return blockedDisposition(failoverBlocker(identity, until));
+    },
+};
+function failureActionHandler(action) {
+    // `satisfies FailureActionHandlerRegistry` above proves the record is
+    // total over FailureActionKind; the widening is owned by kernel/keyed.
+    return totalKeyedHandler(failureActionHandlers, action.kind);
+}
+class FailureActionApplier {
+    policy;
+    store;
+    clock;
+    constructor(policy, store, clock) {
+        this.policy = policy;
+        this.store = store;
+        this.clock = clock;
+    }
+    async apply(identity, error) {
+        if (!isPolicyCode(error.code)) {
+            return terminalDisposition(error);
+        }
+        const action = this.policy[error.code];
+        return failureActionHandler(action)(action, {
+            identity,
+            error,
+            store: this.store,
+            clock: this.clock,
+        });
+    }
+}
+function isFleetAttemptRunOptions(request) {
+    return FLEET_ATTEMPT_OPTION_KEY in request;
+}
+function stripRunSignal(options) {
+    const { signal: _signal, ...runOptions } = options;
+    return runOptions;
+}
+function normalizeFleetRunOptions(request) {
+    if (isFleetAttemptRunOptions(request)) {
+        return request;
+    }
+    const signal = combineAbortSignals(request.signal, request.runOptions.signal);
+    const runOptions = stripRunSignal(request.runOptions);
+    const normalized = {
+        candidates: request.candidates,
+        attempt: async (agent) => await agent.run(runOptions).result,
+    };
+    if (signal !== undefined) {
+        normalized.signal = signal;
+    }
+    return normalized;
+}
+export function createFleet(options) {
+    const store = options.store ?? memoryFleetStore();
+    const policy = resolveFailurePolicy(options.policy);
+    const { clock } = options.runtime.ports;
+    const readiness = new CandidateReadinessResolver(store, clock);
+    const binder = new CandidateAgentBinder(options.runtime);
+    const failures = new FailureActionApplier(policy, store, clock);
+    async function runCandidates(request) {
+        const attempts = [];
+        const blockers = [];
+        for (const candidate of request.candidates) {
+            if (request.signal?.aborted === true) {
+                return {
+                    status: FLEET_OUTCOME_STATUS.failed,
+                    error: new AgentError({
+                        code: AGENT_ERROR_CODE.cancelled,
+                        message: "Fleet run was cancelled",
+                        data: { reason: null },
+                    }),
+                    attempts,
+                };
+            }
+            const identity = resolveCandidateIdentity(candidate);
+            const blocked = await readiness.block(identity);
+            if (blocked !== null) {
+                blockers.push(blocked.blocker);
+                attempts.push(blocked.trace);
+                continue;
+            }
+            try {
+                const bound = await binder.bind(identity, request.signal);
+                const value = await request.attempt(bound, candidate);
+                attempts.push(completedAttempt(candidate));
+                return {
+                    status: FLEET_OUTCOME_STATUS.completed,
+                    value,
+                    candidate,
+                    attempts,
+                };
+            }
+            catch (thrown) {
+                if (!isAgentError(thrown)) {
+                    throw thrown;
+                }
+                attempts.push(failedAttempt(candidate, thrown));
+                const disposition = await failures.apply(identity, thrown);
+                if (disposition.kind === FAILURE_DISPOSITION_KIND.terminal) {
+                    return {
+                        status: FLEET_OUTCOME_STATUS.failed,
+                        error: disposition.error,
+                        attempts,
+                    };
+                }
+                blockers.push(disposition.blocker);
+            }
+        }
+        return {
+            status: FLEET_OUTCOME_STATUS.deferred,
+            blockers,
+            earliestRetryAt: earliestRetryAt(blockers),
+            attempts,
+        };
+    }
+    function run(request) {
+        return runCandidates(normalizeFleetRunOptions(request));
+    }
+    return { run };
+}

package/dist/fleet/policy.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Failure policy (design "Fleet"): a data table, overridable per code.
+ * `invalid_input` and `cancelled` are excluded from the type itself —
+ * caller bugs and aborts are unconditionally terminal, and no override
+ * can say otherwise. Same-candidate retry is deliberately absent from
+ * the action vocabulary.
+ */
+import { AGENT_ERROR_CODE, type AgentErrorCode } from "../core/error.js";
+/**
+ * Where a failover cooldown is written (A4: both levels are needed).
+ * `profile` cools every candidate sharing the credential — quota is
+ * account-scoped, so retrying the same profile on another model is a
+ * wasted attempt. `candidate` cools exactly one (agent, profile, model,
+ * effort) identity — capacity is model-scoped. A profile-scoped action
+ * on a profile-less candidate falls back to the candidate identity,
+ * the only credential identity that exists there.
+ */
+export declare const COOLDOWN_SCOPE: {
+    readonly profile: "profile";
+    readonly candidate: "candidate";
+};
+export type CooldownScope = (typeof COOLDOWN_SCOPE)[keyof typeof COOLDOWN_SCOPE];
+export declare const FAILURE_ACTION_KIND: {
+    readonly failover: "failover";
+    readonly markAuthInvalid: "mark-auth-invalid";
+    readonly terminal: "terminal";
+};
+export type FailureActionKind = (typeof FAILURE_ACTION_KIND)[keyof typeof FAILURE_ACTION_KIND];
+export type FailureAction = {
+    kind: typeof FAILURE_ACTION_KIND.failover;
+    cooldownMs: number | null;
+    scope: CooldownScope;
+} | {
+    kind: typeof FAILURE_ACTION_KIND.markAuthInvalid;
+} | {
+    kind: typeof FAILURE_ACTION_KIND.terminal;
+};
+export type PolicyCode = Exclude<AgentErrorCode, typeof AGENT_ERROR_CODE.invalidInput | typeof AGENT_ERROR_CODE.cancelled>;
+export type FailurePolicy = Record<PolicyCode, FailureAction>;
+/** v1 defaults (A3/A4): quota 3600s, capacity 900s, auth sticky mark. */
+export declare const QUOTA_DEFAULT_COOLDOWN_MS = 3600000;
+export declare const CAPACITY_DEFAULT_COOLDOWN_MS = 900000;
+export declare const defaultFailurePolicy: FailurePolicy;
+export declare function resolveFailurePolicy(overrides: Partial<FailurePolicy> | undefined): FailurePolicy;
+//# sourceMappingURL=policy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../src/fleet/policy.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,gBAAgB,EAAE,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEzE;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc;;;CAGjB,CAAC;AAEX,MAAM,MAAM,aAAa,GACvB,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,OAAO,cAAc,CAAC,CAAC;AAEvD,eAAO,MAAM,mBAAmB;;;;CAItB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAC3B,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,OAAO,mBAAmB,CAAC,CAAC;AAEjE,MAAM,MAAM,aAAa,GACrB;IACE,IAAI,EAAE,OAAO,mBAAmB,CAAC,QAAQ,CAAC;IAC1C,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,KAAK,EAAE,aAAa,CAAC;CACtB,GACD;IAAE,IAAI,EAAE,OAAO,mBAAmB,CAAC,eAAe,CAAA;CAAE,GACpD;IAAE,IAAI,EAAE,OAAO,mBAAmB,CAAC,QAAQ,CAAA;CAAE,CAAC;AAElD,MAAM,MAAM,UAAU,GAAG,OAAO,CAC9B,cAAc,EACd,OAAO,gBAAgB,CAAC,YAAY,GAAG,OAAO,gBAAgB,CAAC,SAAS,CACzE,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,UAAU,EAAE,aAAa,CAAC,CAAC;AAE9D,yEAAyE;AACzE,eAAO,MAAM,yBAAyB,UAAY,CAAC;AACnD,eAAO,MAAM,4BAA4B,SAAU,CAAC;AAEpD,eAAO,MAAM,oBAAoB,EAAE,aAiBlC,CAAC;AAEF,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,SAAS,GAC5C,aAAa,CAEf"}

package/dist/fleet/policy.js

@@ -0,0 +1,50 @@
+/**
+ * Failure policy (design "Fleet"): a data table, overridable per code.
+ * `invalid_input` and `cancelled` are excluded from the type itself —
+ * caller bugs and aborts are unconditionally terminal, and no override
+ * can say otherwise. Same-candidate retry is deliberately absent from
+ * the action vocabulary.
+ */
+import { AGENT_ERROR_CODE } from "../core/error.js";
+/**
+ * Where a failover cooldown is written (A4: both levels are needed).
+ * `profile` cools every candidate sharing the credential — quota is
+ * account-scoped, so retrying the same profile on another model is a
+ * wasted attempt. `candidate` cools exactly one (agent, profile, model,
+ * effort) identity — capacity is model-scoped. A profile-scoped action
+ * on a profile-less candidate falls back to the candidate identity,
+ * the only credential identity that exists there.
+ */
+export const COOLDOWN_SCOPE = {
+    profile: "profile",
+    candidate: "candidate",
+};
+export const FAILURE_ACTION_KIND = {
+    failover: "failover",
+    markAuthInvalid: "mark-auth-invalid",
+    terminal: "terminal",
+};
+/** v1 defaults (A3/A4): quota 3600s, capacity 900s, auth sticky mark. */
+export const QUOTA_DEFAULT_COOLDOWN_MS = 3_600_000;
+export const CAPACITY_DEFAULT_COOLDOWN_MS = 900_000;
+export const defaultFailurePolicy = {
+    [AGENT_ERROR_CODE.quota]: {
+        kind: FAILURE_ACTION_KIND.failover,
+        cooldownMs: QUOTA_DEFAULT_COOLDOWN_MS,
+        scope: COOLDOWN_SCOPE.profile,
+    },
+    [AGENT_ERROR_CODE.capacity]: {
+        kind: FAILURE_ACTION_KIND.failover,
+        cooldownMs: CAPACITY_DEFAULT_COOLDOWN_MS,
+        scope: COOLDOWN_SCOPE.candidate,
+    },
+    [AGENT_ERROR_CODE.auth]: { kind: FAILURE_ACTION_KIND.markAuthInvalid },
+    [AGENT_ERROR_CODE.notAvailable]: { kind: FAILURE_ACTION_KIND.terminal },
+    [AGENT_ERROR_CODE.timeout]: { kind: FAILURE_ACTION_KIND.terminal },
+    [AGENT_ERROR_CODE.limit]: { kind: FAILURE_ACTION_KIND.terminal },
+    [AGENT_ERROR_CODE.failed]: { kind: FAILURE_ACTION_KIND.terminal },
+    [AGENT_ERROR_CODE.outputRejected]: { kind: FAILURE_ACTION_KIND.terminal },
+};
+export function resolveFailurePolicy(overrides) {
+    return { ...defaultFailurePolicy, ...overrides };
+}

package/dist/fleet/store.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Fleet state store port (design A4/A5): cooldowns keyed by candidate
+ * identity, sticky auth marks keyed by profile id. Expiry is purely
+ * time-based and evaluated by the fleet, not the store. The file
+ * implementation writes atomically (temp + rename) under an advisory
+ * cross-process lock with 0700/0600 modes. Fleet state is a cache:
+ * unknown versions are discarded and reconstructed from future runs.
+ */
+import type { Clock } from "../core/ports.js";
+declare const COOLDOWN_KEY: unique symbol;
+export type CooldownKey = string & {
+    readonly [COOLDOWN_KEY]: true;
+};
+export interface FleetStateStore {
+    getCooldownUntil(key: CooldownKey): Promise<string | null>;
+    setCooldownUntil(key: CooldownKey, untilIso: string): Promise<void>;
+    isAuthInvalid(profileId: string): Promise<boolean>;
+    markAuthInvalid(profileId: string): Promise<void>;
+}
+export declare function memoryFleetStore(): FleetStateStore;
+/**
+ * Lock retry pacing and stale-lock age both read the injected clock
+ * (inbound, rule 1: absent = production system clock) so contention and
+ * takeover are testable without real waiting.
+ */
+export declare function fileFleetStore(filePath: string, clock?: Clock): FleetStateStore;
+export {};
+//# sourceMappingURL=store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/fleet/store.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAYH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAG9C,OAAO,CAAC,MAAM,YAAY,EAAE,OAAO,MAAM,CAAC;AAC1C,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,CAAC,YAAY,CAAC,EAAE,IAAI,CAAA;CAAE,CAAC;AAErE,MAAM,WAAW,eAAe;IAC9B,gBAAgB,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC3D,gBAAgB,CAAC,GAAG,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACnD,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnD;AAgPD,wBAAgB,gBAAgB,IAAI,eAAe,CAElD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAChB,KAAK,CAAC,EAAE,KAAK,GACZ,eAAe,CAEjB"}