agentenkit 0.1.0

package/dist/core/types.d.ts

@@ -0,0 +1,286 @@
+import type { LanguageModel, ToolSet } from 'ai';
+import type { AgentRunState } from './state.js';
+/** Lifecycle of a thread. Durable truth lives in Storage.threads; the kv copy
+ *  (`agent:state:{threadId}`) is a hot cache the engine polls (§2.1, §3.4). */
+export type ExecutionState = 'IDLE' | 'RUNNING' | 'WAITING_FOR_INPUT' | 'CANCELLED' | 'COMPLETED' | 'FAILED';
+export type MessageRole = 'user' | 'assistant' | 'system' | 'tool';
+/** Generation flavor of a handle / spawned subagent (§4). */
+export type AgentKind = 'stream-text' | 'generate-text';
+export interface ThreadDTO {
+    id: string;
+    state: ExecutionState;
+    model: string;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface MessageDTO {
+    id: string;
+    threadId: string;
+    /** Producing agent; null = main agent (§2.7) */
+    agentId: string | null;
+    role: MessageRole;
+    /** AI SDK message state, plain text, or a CONTEXT_SUMMARY envelope (§2.6) */
+    content: unknown;
+    createdAt: Date;
+}
+export interface NewMessage {
+    agentId?: string | null;
+    role: MessageRole;
+    content: unknown;
+}
+/** Append-only event log entry: the replay source for SSE (re)connects and the
+ *  durable record of INPUT_REQUIRED (HITL) requests. `seq` is assigned by the
+ *  engine via Kv.incr before append (§3.4). */
+export interface AgentEvent {
+    threadId: string;
+    seq: number;
+    type: string;
+    payload: unknown;
+    createdAt: Date;
+}
+/** The durable record of ONE agent run (§2.9): when it started, how it ended,
+ *  what it cost. Keyed by the run id the platform already mints to fence stale
+ *  workers (§2.1), so a run is observable by the same identity that makes it
+ *  correct. A thread accumulates many of these over its life — `Thread.state`
+ *  only ever describes the latest one. */
+export interface RunRecord {
+    /** The run id (§2.1) for a dispatched run; the nested run's id otherwise —
+     *  which is also the `agentId` its messages and events are tagged with. */
+    id: string;
+    threadId: string;
+    /** The run that spawned this one; null for a dispatched run (§2.7). */
+    parentRunId?: string | null;
+    /** 0 = the main agent, 1+ = nested. */
+    depth: number;
+    /** Registered handle for a dispatched run; the delegation's name for a
+     *  nested one. */
+    agent: string;
+    model: string;
+    state: ExecutionState;
+    /** 'completed' | 'cancelled' | 'token_budget' | 'max_steps', set at finalize. */
+    stopReason?: string | null;
+    /** Why it failed, when it did. Previously dropped on the floor (§2.8). */
+    error?: string | null;
+    /** When the run was accepted and enqueued. */
+    startedAt: Date;
+    endedAt?: Date | null;
+    /** endedAt - startedAt, denormalised so a listing never recomputes it. A
+     *  parked run legitimately spans however long the human took (§2.5). */
+    durationMs?: number | null;
+    /** Milliseconds between enqueue and a worker starting work — the number that
+     *  says whether workers are keeping up (§2.8). */
+    queuedMs?: number | null;
+    /** Loop iterations completed, summed across every segment of the run. */
+    steps: number;
+    inputTokens: number;
+    cachedInputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    /** §2.8 redrive attempts consumed. Only a dispatched run has these. */
+    attempts: number;
+    /** What the run was dispatched with (§2.9) — the prompt that started it, the
+     *  budget it was given, and the state it carries. Present only when
+     *  `recordPayloads` is on. A nested run's is its brief. */
+    prompt?: string | null;
+    tokenBudget?: number | null;
+    runState?: Record<string, unknown> | null;
+    /** A nested run's capped result, handed back to its parent (§2.7). */
+    result?: unknown;
+}
+export interface NewRunRecord {
+    id: string;
+    threadId: string;
+    agent: string;
+    model: string;
+    prompt?: string | null;
+    tokenBudget?: number | null;
+    runState?: Record<string, unknown> | null;
+    /** Defaults to 0 — a dispatched run. */
+    depth?: number;
+    parentRunId?: string | null;
+}
+export type RunPatch = Partial<Omit<RunRecord, 'id' | 'threadId'>>;
+/** Token attribution only (§4): total tokens used. USD/credit pricing is a
+ *  downstream concern computed over the recorded counters. */
+/** Token attribution (§4): the platform records the counters; USD/credit
+ *  pricing is a downstream concern computed over them. */
+/** Cumulative token attribution across every run on a thread (§4). */
+export interface UsageTotals {
+    /** Fresh (uncached) prompt tokens. */
+    inputTokens: number;
+    /** Prompt tokens served from the provider's prompt cache (§2.6). */
+    cachedInputTokens: number;
+    outputTokens: number;
+    /** input + cached + output. */
+    totalTokens: number;
+}
+/** How full the next run's prompt would be (§2.6). Token counts are the same
+ *  rough estimate the engine itself compacts on, so the number a user sees is
+ *  the number the platform acts on. */
+export interface ContextUsage {
+    /** Estimated tokens the stored history occupies right now. */
+    usedTokens: number;
+    /** What history may fill: the model's window minus the output reserve. */
+    budgetTokens: number;
+    /** Compaction runs above this — `budgetTokens × compactionTrigger`. */
+    compactAtTokens: number;
+    /** Messages currently in the thread, summaries included. */
+    messages: number;
+}
+export interface NewUsage {
+    agentId?: string | null;
+    /** Fresh (uncached) prompt tokens. */
+    inputTokens: number;
+    /** Prompt tokens served from the provider's prompt cache (§2.6 caching). */
+    cachedInputTokens: number;
+    outputTokens: number;
+    /** input + cached + output. */
+    totalTokens: number;
+}
+/** Additional provider-specific options, passed through to the provider from
+ *  the AI SDK. Namespaced per provider — the platform never inspects them. */
+export interface ProviderOptions {
+    [provider: string]: any;
+}
+/** Shallow per-provider merge: the execute input wins over the spec default. */
+export declare function mergeProviderOptions(base?: ProviderOptions, override?: ProviderOptions): ProviderOptions | undefined;
+/** Dispatch ticket for the queue (§2.8). At-least-once — consumers must be
+ *  idempotent. `agent` resolves via `AgentCore.getAgent`; when missing, the
+ *  default handle executes. */
+export interface RunJob {
+    threadId: string;
+    model: string;
+    agent?: string;
+    /** Identifies THIS dispatch (§2.1). A thread has one live run at a time and
+     *  `agent:run:{threadId}` holds its id; a job whose id no longer matches has
+     *  been replaced by a newer run and must not execute. Omitted on legacy
+     *  dispatches, which keep the old no-identity behavior. */
+    runId?: string;
+    /** Epoch ms at enqueue. The worker subtracts it on pickup to record how long
+     *  the job waited — the number that says whether workers keep up (§2.9). */
+    enqueuedAt?: number;
+    /** The run's state (§2.10), so a worker rehydrates exactly what the caller
+     *  attached — hours later, in another process, after an approval. */
+    state?: AgentRunState;
+    tokenBudget?: number;
+    providerOptions?: ProviderOptions;
+}
+/** Identifies a nested run well enough to re-enter its loop (§2.7). Persisted
+ *  in the INPUT_REQUIRED payload so a resume never has to read it back. */
+export interface NestedDescriptor {
+    agentId: string;
+    name: string;
+    model: string;
+    depth: number;
+}
+/** Everything needed to resume a parked HITL run segment (§2.5). Persisted
+ *  inside the INPUT_REQUIRED event payload so any late reader — /respond or
+ *  TTL reclamation — can rebuild the dispatch ticket without extra state. */
+export interface ResumeInfo {
+    agent: string;
+    model: string;
+    /** The run these segments belong to (§2.9). */
+    runId?: string;
+    tokenBudget?: number;
+    providerOptions?: ProviderOptions;
+    /** The run's state (§2.10). A park can outlive the process that made it, so
+     *  the state has to travel on the ticket — rebuilt from here, not from a
+     *  closure that is long gone. Without it every storage call after an
+     *  approval loses whatever the caller attached, tenant scope included. */
+    state?: AgentRunState;
+}
+/** A model identity after resolution: the real provider instance (created
+ *  lazily per run) and the declared context window, which feeds the §2.6
+ *  compaction budget math. */
+export interface ResolvedModel {
+    instance: () => LanguageModel;
+    contextWindow?: number;
+}
+/** Opt-in subagent delegation config (§2.7): the platform constructs the
+ *  run-scoped spawnSubagent tool — users cannot build it themselves. */
+export interface SubagentsConfig {
+    /** Generation flavor for spawned subagents — picks the nested loop (§4).
+     *  Default: 'stream-text'. A 'generate-text' child publishes only
+     *  SUBAGENT_STARTED / SUBAGENT_COMPLETED / SUBAGENT_FAILED. */
+    kind?: AgentKind;
+    /** Registry key used when a delegation call omits `model`. */
+    model?: string;
+    /** Extra tools merged into every spawned subagent's toolset
+     *  (HITL-wrapped identically to the parent's tools). */
+    tools?: ToolSet;
+}
+export interface AgentConfig {
+    /** How long a parked HITL request stays answerable (§2.5) — expiry turns
+     *  it into the timeout denial ("user had no response") and the run continues. */
+    hitlTtlMs: number;
+    /** Grace beyond the HITL TTL before orphan reclamation may claim a thread (§2.5) */
+    reclaimGraceMs: number;
+    /** AI-SDK round-trip ceiling per run (§2.1 safety cap) — the platform loop
+     *  runs one executeStep (maxSteps: 1) per iteration up to this count. */
+    maxSteps: number;
+    /** Queue redrive attempts before a run finalizes FAILED (§2.8) */
+    runMaxAttempts: number;
+    /** How often a running worker re-reads the stop signal (§2.1). Also the
+     *  window in which it notices that a newer run has replaced it. */
+    stopPollMs: number;
+    /** Delay (seconds) before re-dispatching a job that found the run lock still
+     *  held by an OLDER run (§2.8). That job has not executed at all — dropping
+     *  it would strand the user's message — so it comes back once the previous
+     *  run has let go. */
+    runRedriveDelaySeconds: number;
+    /** Default per-run token budget (input + output) when neither the execute
+     *  input nor the agent spec declares one. `undefined` = unbounded apart
+     *  from `maxSteps` (§2.1 safety cap). */
+    tokenBudget?: number;
+    /** Subagent nesting cap (§2.7) */
+    subagentMaxDepth: number;
+    /** Concurrent subagents per run (§2.7) */
+    subagentMaxConcurrent: number;
+    /** AI-SDK step ceiling per subagent run (§2.7) — tighter than `maxSteps` */
+    subagentMaxSteps: number;
+    /** Characters of a subagent result handed back to the parent (§2.7) */
+    subagentResultCapChars: number;
+    /** Record payloads into the operational store (§2.9): the prompt and state a
+     *  run was dispatched with, and the text and tool arguments/results each step
+     *  produced. Off means timings and counts only.
+     *
+     *  On by default because a dashboard that cannot show what happened is worth
+     *  little — but this is the flag to turn off when prompts or tool payloads
+     *  carry anything that should not sit in an operational database. */
+    recordPayloads: boolean;
+    /** Characters kept per recorded value, so one large prompt or tool result
+     *  cannot bloat the store. */
+    payloadCapChars: number;
+    /** Universal context ceiling (§2.6) */
+    contextCeilingTokens: number;
+    /** Tokens reserved for the completion when compacting (§2.6) */
+    contextOutputReserveTokens: number;
+    /** Compact when history estimate exceeds this share of budget (§2.6) */
+    compactionTrigger: number;
+    /** Share of budget kept verbatim as the recent tail (§2.6) */
+    contextTailShare: number;
+    /** Prompt caching (§2.6): when true, the engine stamps Anthropic-style
+     *  ephemeral cache breakpoints on the prompt prefix so providers that
+     *  support marking cache it. OpenAI models cache automatically (≥1024
+     *  tokens) and ignore the flag. Default: true. */
+    promptCaching: boolean;
+    /** Per-model native windows below the ceiling (§2.6) — merged over defaults.
+     *  A `contextWindow` declared via `resolveModel` wins over this table. */
+    nativeWindows?: Record<string, number>;
+    /** Lease (seconds) for the per-thread run lock — must exceed the longest
+     *  possible run segment; parked HITL waits hold NO lock (§2.8, §3.4). */
+    runLockLeaseSeconds: number;
+    /** Billing pre-execution check (§4). Return `{ ok: false, error }` to reject a run. */
+    billingPreCheck?: (threadId: string) => Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    /** Provider-specific options applied to EVERY run (§3.1) — a reasoning
+     *  budget, a service tier, a safety identifier. The lowest of three levels:
+     *  an agent spec overrides this, and a run input overrides both, per
+     *  provider namespace. */
+    providerOptions?: ProviderOptions;
+}
+export declare const DEFAULT_CONFIG: AgentConfig;
+export declare function resolveConfig(partial?: Partial<AgentConfig>): AgentConfig;
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/core/types.js

@@ -0,0 +1,49 @@
+/** Shallow per-provider merge: the execute input wins over the spec default. */
+export function mergeProviderOptions(base, override) {
+    if (!base)
+        return override;
+    if (!override)
+        return base;
+    return { ...base, ...override };
+}
+export const DEFAULT_CONFIG = {
+    hitlTtlMs: 15 * 60_000,
+    reclaimGraceMs: 60_000,
+    maxSteps: 25,
+    runMaxAttempts: 3,
+    stopPollMs: 500,
+    runRedriveDelaySeconds: 2,
+    subagentMaxDepth: 2,
+    subagentMaxConcurrent: 3,
+    subagentMaxSteps: 10,
+    subagentResultCapChars: 8_000,
+    recordPayloads: true,
+    payloadCapChars: 2_000,
+    contextCeilingTokens: 265_000,
+    contextOutputReserveTokens: 16_000,
+    compactionTrigger: 0.8,
+    contextTailShare: 0.25,
+    promptCaching: true,
+    runLockLeaseSeconds: 30 * 60,
+};
+export function resolveConfig(partial) {
+    const config = { ...DEFAULT_CONFIG, ...partial };
+    if (config.subagentMaxSteps < 1 || config.subagentMaxSteps > config.maxSteps) {
+        // A subagent must never get a looser step ceiling than its parent run (§2.7)
+        throw new Error(`Invalid config: subagentMaxSteps (${config.subagentMaxSteps}) must be between 1 and maxSteps (${config.maxSteps})`);
+    }
+    if (!Number.isInteger(config.stopPollMs) || config.stopPollMs < 1) {
+        // The poll is the only thing that delivers a stop to a running worker (§2.1)
+        throw new Error(`Invalid config: stopPollMs (${config.stopPollMs}) must be an integer of at least 1`);
+    }
+    if (!Number.isInteger(config.runRedriveDelaySeconds) || config.runRedriveDelaySeconds < 0) {
+        throw new Error(`Invalid config: runRedriveDelaySeconds (${config.runRedriveDelaySeconds}) must be a non-negative integer`);
+    }
+    if (!Number.isInteger(config.runLockLeaseSeconds) || config.runLockLeaseSeconds < 1) {
+        // The lease is the only thing that heals a crashed worker's lock — a
+        // zero/fractional value would deadlock the thread forever (§3.4)
+        throw new Error(`Invalid config: runLockLeaseSeconds (${config.runLockLeaseSeconds}) must be an integer of at least 1`);
+    }
+    return config;
+}
+//# sourceMappingURL=types.js.map

package/dist/core/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAqKA,gFAAgF;AAChF,MAAM,UAAU,oBAAoB,CAClC,IAAsB,EACtB,QAA0B;IAE1B,IAAI,CAAC,IAAI;QAAE,OAAO,QAAQ,CAAC;IAC3B,IAAI,CAAC,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC3B,OAAO,EAAE,GAAG,IAAI,EAAE,GAAG,QAAQ,EAAE,CAAC;AAClC,CAAC;AA8ID,MAAM,CAAC,MAAM,cAAc,GAAgB;IACzC,SAAS,EAAE,EAAE,GAAG,MAAM;IACtB,cAAc,EAAE,MAAM;IACtB,QAAQ,EAAE,EAAE;IACZ,cAAc,EAAE,CAAC;IACjB,UAAU,EAAE,GAAG;IACf,sBAAsB,EAAE,CAAC;IACzB,gBAAgB,EAAE,CAAC;IACnB,qBAAqB,EAAE,CAAC;IACxB,gBAAgB,EAAE,EAAE;IACpB,sBAAsB,EAAE,KAAK;IAC7B,cAAc,EAAE,IAAI;IACpB,eAAe,EAAE,KAAK;IACtB,oBAAoB,EAAE,OAAO;IAC7B,0BAA0B,EAAE,MAAM;IAClC,iBAAiB,EAAE,GAAG;IACtB,gBAAgB,EAAE,IAAI;IACtB,aAAa,EAAE,IAAI;IACnB,mBAAmB,EAAE,EAAE,GAAG,EAAE;CAC7B,CAAC;AAEF,MAAM,UAAU,aAAa,CAAC,OAA8B;IAC1D,MAAM,MAAM,GAAG,EAAE,GAAG,cAAc,EAAE,GAAG,OAAO,EAAE,CAAC;IACjD,IAAI,MAAM,CAAC,gBAAgB,GAAG,CAAC,IAAI,MAAM,CAAC,gBAAgB,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC;QAC7E,6EAA6E;QAC7E,MAAM,IAAI,KAAK,CACb,qCAAqC,MAAM,CAAC,gBAAgB,qCAAqC,MAAM,CAAC,QAAQ,GAAG,CACpH,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,MAAM,CAAC,UAAU,GAAG,CAAC,EAAE,CAAC;QAClE,6EAA6E;QAC7E,MAAM,IAAI,KAAK,CACb,+BAA+B,MAAM,CAAC,UAAU,oCAAoC,CACrF,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,sBAAsB,CAAC,IAAI,MAAM,CAAC,sBAAsB,GAAG,CAAC,EAAE,CAAC;QAC1F,MAAM,IAAI,KAAK,CACb,2CAA2C,MAAM,CAAC,sBAAsB,kCAAkC,CAC3G,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,mBAAmB,CAAC,IAAI,MAAM,CAAC,mBAAmB,GAAG,CAAC,EAAE,CAAC;QACpF,qEAAqE;QACrE,iEAAiE;QACjE,MAAM,IAAI,KAAK,CACb,wCAAwC,MAAM,CAAC,mBAAmB,oCAAoC,CACvG,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/core/usage.d.ts

@@ -0,0 +1,40 @@
+/** Token attribution (§4): the platform records the counters; USD/credit
+ *  pricing is a downstream concern computed over them. */
+export interface TokenAttribution {
+    /** Fresh (uncached) prompt tokens. */
+    inputTokens: number;
+    /** Prompt tokens served from the provider's prompt cache (§2.6). */
+    cachedInputTokens: number;
+    outputTokens: number;
+    /** input + cached + output. */
+    totalTokens: number;
+}
+/** Where a cache hit is reported, per provider. The AI SDK's `usage` carries
+ *  only prompt/completion/total — cache counts live in provider metadata, so
+ *  reading `usage` alone can never see one. */
+export type ProviderMetadataLike = Record<string, Record<string, unknown> | undefined> | undefined;
+type UsageLike = {
+    inputTokens?: number;
+    cachedInputTokens?: number;
+    outputTokens?: number;
+    promptTokens?: number;
+    completionTokens?: number;
+    totalTokens?: number;
+} | undefined;
+/** Attribute one usage report into the four canonical counters, NaN-guarded.
+ *
+ *  Handles both AI-SDK namings (inputTokens/outputTokens and the older
+ *  promptTokens/completionTokens), and reads cache hits out of PROVIDER
+ *  METADATA, which is the only place they appear — `usage` has no field for
+ *  them, so attributing from it alone reports zero cache hits forever.
+ *
+ *  The two providers disagree about what "prompt tokens" means, and getting it
+ *  wrong double-counts:
+ *   - OpenAI's promptTokens INCLUDES the cached ones, so the fresh count is
+ *     the difference.
+ *   - Anthropic reports cache reads alongside input, not inside it. */
+export declare function attributeTokens(usage: UsageLike, meta?: ProviderMetadataLike): TokenAttribution;
+/** Total tokens used — input + cached + output, NaN-guarded. */
+export declare function countTokens(usage: UsageLike, meta?: ProviderMetadataLike): number;
+export {};
+//# sourceMappingURL=usage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../../src/core/usage.ts"],"names":[],"mappings":"AAAA;0DAC0D;AAE1D,MAAM,WAAW,gBAAgB;IAC/B,sCAAsC;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,oEAAoE;IACpE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,+BAA+B;IAC/B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;+CAE+C;AAC/C,MAAM,MAAM,oBAAoB,GAC5B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,GACnD,SAAS,CAAC;AAEd,KAAK,SAAS,GAAG;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GAAG,SAAS,CAAC;AASd;;;;;;;;;;;uEAWuE;AACvE,wBAAgB,eAAe,CAC7B,KAAK,EAAE,SAAS,EAChB,IAAI,CAAC,EAAE,oBAAoB,GAC1B,gBAAgB,CAsBlB;AAED,gEAAgE;AAChE,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,EAAE,oBAAoB,GAAG,MAAM,CAEjF"}

package/dist/core/usage.js

@@ -0,0 +1,43 @@
+/** Token attribution (§4): the platform records the counters; USD/credit
+ *  pricing is a downstream concern computed over them. */
+const pick = (...vals) => {
+    for (const v of vals) {
+        if (typeof v === 'number' && Number.isFinite(v))
+            return v;
+    }
+    return 0;
+};
+/** Attribute one usage report into the four canonical counters, NaN-guarded.
+ *
+ *  Handles both AI-SDK namings (inputTokens/outputTokens and the older
+ *  promptTokens/completionTokens), and reads cache hits out of PROVIDER
+ *  METADATA, which is the only place they appear — `usage` has no field for
+ *  them, so attributing from it alone reports zero cache hits forever.
+ *
+ *  The two providers disagree about what "prompt tokens" means, and getting it
+ *  wrong double-counts:
+ *   - OpenAI's promptTokens INCLUDES the cached ones, so the fresh count is
+ *     the difference.
+ *   - Anthropic reports cache reads alongside input, not inside it. */
+export function attributeTokens(usage, meta) {
+    const u = usage ?? {};
+    const reportedInput = pick(u.inputTokens, u.promptTokens);
+    const outputTokens = pick(u.outputTokens, u.completionTokens);
+    const openaiCached = pick(meta?.openai?.cachedPromptTokens);
+    const anthropicCached = pick(meta?.anthropic?.cacheReadInputTokens);
+    const cachedInputTokens = pick(u.cachedInputTokens) + openaiCached + anthropicCached;
+    const inputTokens = openaiCached > 0 ? Math.max(0, reportedInput - openaiCached) : reportedInput;
+    const totalFromProvider = pick(u.totalTokens);
+    const summed = inputTokens + cachedInputTokens + outputTokens;
+    return {
+        inputTokens,
+        cachedInputTokens,
+        outputTokens,
+        totalTokens: totalFromProvider > 0 ? totalFromProvider : summed,
+    };
+}
+/** Total tokens used — input + cached + output, NaN-guarded. */
+export function countTokens(usage, meta) {
+    return attributeTokens(usage, meta).totalTokens;
+}
+//# sourceMappingURL=usage.js.map

package/dist/core/usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.js","sourceRoot":"","sources":["../../src/core/usage.ts"],"names":[],"mappings":"AAAA;0DAC0D;AA4B1D,MAAM,IAAI,GAAG,CAAC,GAAG,IAA4B,EAAU,EAAE;IACvD,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;YAAE,OAAO,CAAC,CAAC;IAC5D,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC,CAAC;AAEF;;;;;;;;;;;uEAWuE;AACvE,MAAM,UAAU,eAAe,CAC7B,KAAgB,EAChB,IAA2B;IAE3B,MAAM,CAAC,GAAG,KAAK,IAAI,EAAE,CAAC;IACtB,MAAM,aAAa,GAAG,IAAI,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,YAAY,CAAC,CAAC;IAC1D,MAAM,YAAY,GAAG,IAAI,CAAC,CAAC,CAAC,YAAY,EAAE,CAAC,CAAC,gBAAgB,CAAC,CAAC;IAE9D,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,kBAAwC,CAAC,CAAC;IAClF,MAAM,eAAe,GAAG,IAAI,CAC1B,IAAI,EAAE,SAAS,EAAE,oBAA0C,CAC5D,CAAC;IACF,MAAM,iBAAiB,GAAG,IAAI,CAAC,CAAC,CAAC,iBAAiB,CAAC,GAAG,YAAY,GAAG,eAAe,CAAC;IAErF,MAAM,WAAW,GACf,YAAY,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,aAAa,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC;IAE/E,MAAM,iBAAiB,GAAG,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;IAC9C,MAAM,MAAM,GAAG,WAAW,GAAG,iBAAiB,GAAG,YAAY,CAAC;IAC9D,OAAO;QACL,WAAW;QACX,iBAAiB;QACjB,YAAY;QACZ,WAAW,EAAE,iBAAiB,GAAG,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,MAAM;KAChE,CAAC;AACJ,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,WAAW,CAAC,KAAgB,EAAE,IAA2B;IACvE,OAAO,eAAe,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,WAAW,CAAC;AAClD,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+export type { Storage } from './ports/storage.js';
+export type { EventBus } from './ports/bus.js';
+export type { EnqueueOptions, Queue } from './ports/queue.js';
+export type { Kv } from './ports/kv.js';
+export type { AgentCore, AgentHandle, AgentKind, DeleteThreadResult, GenerateTextAgentSpec, RespondInput, RespondResult, ResolvedModel, RunInput, RunResult, RuntimeOptions, RuntimePorts, StopResult, StreamTextAgentSpec, SubagentsConfig, ThreadSnapshot, ThreadUsage, } from './ports/runtime.js';
+export { setupAgentCore } from './runtime.js';
+export { execute, executeStep, executeWithPolicy, finalize, markRequiresConfirmation, type ExecuteInput, type ExecuteOutcome, type FinalizeInput, type StepResult, } from './core/engine.js';
+export { agentTool, type ToolContext } from './core/tools.js';
+export { followEvents, toSseStream, sseFrame, SSE_HEADERS, type FollowOptions, type SseOptions, type SseStream, } from './core/follow.js';
+export type { AgentRunState, BoundStorage, StorageContext } from './core/state.js';
+export { claimRun, redriveKey, runIdKey } from './core/keys.js';
+export { countTokens } from './core/usage.js';
+export { respond, parkForApproval, loadPendingHitl, loadOpenHitls, withHitl, HITL_PARKED, HITL_TTL_MS, hitlKey, type HitlFrame, type HitlResponse, type ParkInput, type PendingHitl, } from './core/hitl.js';
+export { reclaimIfOrphaned } from './core/reclaim.js';
+export { contextBudget, contextUsage, compactContext, CONTEXT_TOKEN_CEILING } from './core/context.js';
+export { Semaphore, runNestedAgent, spawnSubagentTool, type SubagentCtx } from './core/subagent.js';
+export { run } from './core/run.js';
+export { stop } from './core/stop.js';
+export { DEFAULT_CONFIG, resolveConfig, type AgentConfig, type AgentEvent, type ExecutionState, type MessageDTO, type MessageRole, type NewMessage, type NewRunRecord, type NewUsage, type ResolvedModel as ResolvedModelDTO, type RunPatch, type RunRecord, type RunJob, type ResumeInfo, type ContextUsage, type NestedDescriptor, type ThreadDTO, type UsageTotals, } from './core/types.js';
+export { PrismaStorage, type PrismaLike } from './adapters/prisma.js';
+export { UpstashBus, UpstashKv, THREAD_CHANNEL, type UpstashRedisLike, type UpstashSubscriberLike } from './adapters/upstash.js';
+export { RedisBus, RedisKv, type RedisClientLike, type RedisSubscriberLike } from './adapters/redis.js';
+export { QStashQueue, type QStashLike, type QStashQueueOptions } from './adapters/qstash.js';
+export { MemoryStorage, MemoryBus, MemoryQueue, MemoryKv } from './adapters/memory.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,23 @@
+// runtime — the factory that binds ports to behaviors
+export { setupAgentCore } from './runtime.js';
+// core — behaviors, all ports-only
+export { execute, executeStep, executeWithPolicy, finalize, markRequiresConfirmation, } from './core/engine.js';
+export { agentTool } from './core/tools.js';
+export { followEvents, toSseStream, sseFrame, SSE_HEADERS, } from './core/follow.js';
+export { claimRun, redriveKey, runIdKey } from './core/keys.js';
+export { countTokens } from './core/usage.js';
+export { respond, parkForApproval, loadPendingHitl, loadOpenHitls, withHitl, HITL_PARKED, HITL_TTL_MS, hitlKey, } from './core/hitl.js';
+export { reclaimIfOrphaned } from './core/reclaim.js';
+export { contextBudget, contextUsage, compactContext, CONTEXT_TOKEN_CEILING } from './core/context.js';
+export { Semaphore, runNestedAgent, spawnSubagentTool } from './core/subagent.js';
+export { run } from './core/run.js';
+export { stop } from './core/stop.js';
+// types
+export { DEFAULT_CONFIG, resolveConfig, } from './core/types.js';
+// reference adapters
+export { PrismaStorage } from './adapters/prisma.js';
+export { UpstashBus, UpstashKv, THREAD_CHANNEL } from './adapters/upstash.js';
+export { RedisBus, RedisKv } from './adapters/redis.js';
+export { QStashQueue } from './adapters/qstash.js';
+export { MemoryStorage, MemoryBus, MemoryQueue, MemoryKv } from './adapters/memory.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAyBA,sDAAsD;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,mCAAmC;AACnC,OAAO,EACL,OAAO,EACP,WAAW,EACX,iBAAiB,EACjB,QAAQ,EACR,wBAAwB,GAKzB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,SAAS,EAAoB,MAAM,iBAAiB,CAAC;AAC9D,OAAO,EACL,YAAY,EACZ,WAAW,EACX,QAAQ,EACR,WAAW,GAIZ,MAAM,kBAAkB,CAAC;AAI1B,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAChE,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EACL,OAAO,EACP,eAAe,EACf,eAAe,EACf,aAAa,EACb,QAAQ,EACR,WAAW,EACX,WAAW,EACX,OAAO,GAKR,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AACvG,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,iBAAiB,EAAoB,MAAM,oBAAoB,CAAC;AACpG,OAAO,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AACpC,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAEtC,QAAQ;AACR,OAAO,EACL,cAAc,EACd,aAAa,GAkBd,MAAM,iBAAiB,CAAC;AAEzB,qBAAqB;AACrB,OAAO,EAAE,aAAa,EAAmB,MAAM,sBAAsB,CAAC;AACtE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,cAAc,EAAqD,MAAM,uBAAuB,CAAC;AACjI,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAkD,MAAM,qBAAqB,CAAC;AACxG,OAAO,EAAE,WAAW,EAA4C,MAAM,sBAAsB,CAAC;AAC7F,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/ports/admin.d.ts

@@ -0,0 +1,102 @@
+import type { ExecutionState, NewRunRecord, RunPatch, RunRecord } from '../core/types.js';
+/** Operational history — run records and step timings (§2.9).
+ *
+ *  NOT a port a caller implements. agentic-kit owns this data and stores it
+ *  itself: SQLite in development, Postgres in production via
+ *  AGENTIC_KIT_ADMIN_DATABASE_URL. Callers only ever read it back, through
+ *  `runtime.admin`, and build whatever view they want on top.
+ *
+ *  It carries no StorageContext. A run's state belongs to the caller's own
+ *  data (§2.10); operational history is the platform's, and scoping it by
+ *  tenant is the reader's business, not the writer's. */
+export interface AdminStore {
+    /** The platform's OWN view of threads (§2.9). Deliberately a copy of the few
+     *  fields an operational view needs — not the caller's thread table, which
+     *  it never reads. That is what lets a dashboard answer "what is running
+     *  right now" without touching their database at all. */
+    threads: {
+        /** Record a thread at its current state. Called on every transition. */
+        upsert(thread: NewAdminThread): Promise<void>;
+        countByState(): Promise<Partial<Record<ExecutionState, number>>>;
+        list(filter: AdminThreadFilter): Promise<AdminThread[]>;
+    };
+    runs: {
+        start(run: NewRunRecord): Promise<RunRecord>;
+        patch(runId: string, patch: RunPatch): Promise<void>;
+        get(runId: string): Promise<RunRecord | null>;
+        /** Every run on a thread, newest first — nested runs included. */
+        listByThread(threadId: string): Promise<RunRecord[]>;
+        list(filter: RunFilter): Promise<RunRecord[]>;
+        /** Counts by state across every run. The "what is happening right now"
+         *  aggregate, pushed down so it never drags rows into memory. */
+        countByState(): Promise<Partial<Record<ExecutionState, number>>>;
+    };
+    steps: {
+        record(step: NewStepRecord): Promise<void>;
+        /** A run's steps in order. */
+        listByRun(runId: string): Promise<StepRecord[]>;
+        /** Every step on a thread, oldest first — the shape a timeline wants. */
+        listByThread(threadId: string): Promise<StepRecord[]>;
+    };
+    /** Release any handles. Development stores hold an open file. */
+    close?(): Promise<void>;
+}
+/** One completed loop iteration (§2.9). */
+export interface StepRecord {
+    runId: string;
+    /** Denormalised so a thread's whole timeline — across every run on it, main
+     *  and nested — is one query rather than one per run. */
+    threadId: string;
+    /** Which stream ran it — null is the main agent (§2.7). */
+    agentId: string | null;
+    index: number;
+    durationMs: number;
+    finishReason: string;
+    inputTokens: number;
+    cachedInputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    /** Tools the step executed, by name — the summary line. */
+    tools: string[];
+    /** What the step said, capped. Timing tells you where a run spent itself;
+     *  this tells you what it actually did. */
+    text?: string | null;
+    /** The tools it ran, with arguments and results, each capped.
+     *
+     *  Note what this means: tool arguments and results are operational data now,
+     *  sitting in the platform's store. If yours carry anything you would not
+     *  want there, set `recordPayloads: false`. */
+    toolCalls?: Array<{
+        toolName: string;
+        args: unknown;
+        result: unknown;
+    }>;
+    at: Date;
+}
+export type NewStepRecord = Omit<StepRecord, 'at'> & {
+    at?: Date;
+};
+export interface AdminThread {
+    id: string;
+    state: ExecutionState;
+    model: string;
+    firstSeenAt: Date;
+    updatedAt: Date;
+}
+export type NewAdminThread = Omit<AdminThread, 'firstSeenAt' | 'updatedAt'>;
+export interface AdminThreadFilter {
+    state?: ExecutionState[];
+    since?: Date;
+    limit?: number;
+}
+export interface RunFilter {
+    /** Any of these states; omitted means all. */
+    state?: ExecutionState[];
+    agent?: string;
+    threadId?: string;
+    since?: Date;
+    until?: Date;
+    /** Newest first. Implementations cap this — core passes a bounded value. */
+    limit?: number;
+}
+//# sourceMappingURL=admin.d.ts.map

package/dist/ports/admin.d.ts.map

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

package/dist/ports/admin.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=admin.js.map

package/dist/ports/admin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin.js","sourceRoot":"","sources":["../../src/ports/admin.ts"],"names":[],"mappings":""}

package/dist/ports/bus.d.ts

@@ -0,0 +1,13 @@
+import type { AgentEvent } from '../core/types.js';
+/** Pub/sub port: live fan-out + death notices (§2.2, §2.5).
+ *
+ *  Delivery is at-most-once — the §2.5 death-notice/heartbeat/watchdog pattern
+ *  exists precisely because pub/sub drops. Stronger buses may simplify the
+ *  heartbeat but reclamation stays (§3.4). */
+export interface EventBus {
+    publish(threadId: string, event: AgentEvent): Promise<void>;
+    /** Returns an unsubscribe function. The reference adapter runs the §2.5
+     *  heartbeat while any subscriber is attached. */
+    subscribe(threadId: string, handler: (event: AgentEvent) => void): Promise<() => void>;
+}
+//# sourceMappingURL=bus.d.ts.map

package/dist/ports/bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bus.d.ts","sourceRoot":"","sources":["../../src/ports/bus.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD;;;;8CAI8C;AAC9C,MAAM,WAAW,QAAQ;IACvB,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D;sDACkD;IAClD,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,CAAC;CACxF"}