agentenkit 0.3.0 → 0.5.0

package/dist/core/engine.d.ts

@@ -1,17 +1,22 @@
 import type { RuntimePorts } from '../ports/runtime.js';
-import type { ExecutionState, ProviderOptions } from './types.js';
+import type { ExecutionState, JobKind, ProviderOptions } from './types.js';
 import type { TokenAttribution } from './usage.js';
 import type { RegisteredAgent } from './agent.js';
 import { type AgentRunState } from './state.js';
 export { countTokens } from './usage.js';
 export { executeStep, isParked, runLoop, type LoopInput, type LoopOutcome, type RunLedger, type StepResult } from './loop.js';
-/** The safety cap (§2.1) must be either absent (unbounded apart from
- *  maxSteps) or a positive number — `0`/negative/NaN would silently disable
- *  the cap and let a run spend without bound. */
+/** A cap (§2.1, §4) is absent, 0 (no cap from this level: the next level's
+ *  applies), or a positive number. A negative or non-finite one is a bug in
+ *  the caller and is refused, never read as "no cap". The same rule as the Go
+ *  runtime, whose zero value can only mean "not set". */
 export declare function validateTokenBudget(value: number | undefined, label: string): void;
 /** Tools the engine treats as destructive: parked behind parkForApproval
  *  (§2.5) instead of executing directly. Purely a marker — see withHitl. */
 export declare function markRequiresConfirmation<T extends object>(t: T): T;
+/** Close a run record that can never be worked on again (§2.9): the thread is
+ *  gone, or a newer run replaced this one. Without this the record stays
+ *  open for ever and every "in flight" count carries it. */
+export declare function closeIfOpen(deps: RuntimePorts, runId: string | undefined, stopReason: FinalizeInput['stopReason']): Promise<void>;
 /** The engine (§2.1, §5.6). Worker-side only — runs are dispatched via the
  *  queue (§2.8) and may outlive any HTTP response.
  *
@@ -23,16 +28,20 @@ export declare function markRequiresConfirmation<T extends object>(t: T): T;
  *  the SDK.
  *
  *  Concurrency: acquires the per-thread run lock (`agent:lock:{threadId}`,
- *  SET NX + lease) before any work — two workers can never run one thread,
- *  and a crashed worker's lock expires instead of blocking forever (§3.4).
- *  Returns 'lock-conflict' when the lock is held, so callers can tell a
- *  genuine no-op apart from a completed run. */
+ *  SET NX + lease) before any work, and renews it while it works — two
+ *  workers can never run one thread, and a crashed worker's lock expires
+ *  instead of blocking forever (§3.4). Returns 'lock-conflict' when the lock
+ *  is held, so callers can tell a genuine no-op apart from a completed run,
+ *  and 'lock-lost' when the lock could not be kept. */
 export interface ExecuteInput {
     threadId: string;
     model: string;
     /** This dispatch's run id (§2.1). A job without one keeps the old
      *  behavior: no staleness check, and no redrive on a lock conflict. */
     runId?: string;
+    /** The job's delivery id (see `RunJob.dispatchId`). Absent on a call that
+     *  did not come off the queue; the lock then makes one up. */
+    dispatchId?: string;
     /** Epoch ms at enqueue, for the queue-wait measurement (§2.9). */
     enqueuedAt?: number;
     /** The run's state (§2.10) — carried so a redrive keeps it. */
@@ -42,15 +51,32 @@ export interface ExecuteInput {
      *  what the caller asked for. */
     costBudgetMicros?: number;
     providerOptions?: ProviderOptions;
+    /** The run's own step cap (§2.1); 0 or absent keeps the config's. */
+    maxSteps?: number;
+    /** Epoch ms of the run's first dispatch (see RunJob.dispatchedAt). */
+    dispatchedAt?: number;
+    /** The caller's tenant (see RunJob.partitionKey). */
+    partitionKey?: string;
+    /** Why the job exists (see RunJob.kind). */
+    kind?: JobKind;
+    /** Aborted when the worker is shutting down. The segment stops at once and
+     *  the job goes back on the queue without spending an attempt: a shutdown
+     *  is not the run's fault. */
+    signal?: AbortSignal;
 }
 /** 'executed'      — this worker ran the segment (or it was a legitimate no-op).
  *  'lock-conflict' — someone else holds the thread's run lock; nothing ran.
- *  'stale'         — a NEWER run owns the thread; this job must do nothing. */
-export type ExecuteOutcome = 'executed' | 'lock-conflict' | 'stale';
+ *  'stale'         — a NEWER run owns the thread; this job must do nothing.
+ *  'lock-lost'     — this worker held the lock and could not keep it; the
+ *                    segment ended early and the job should come back once
+ *                    the lock is free. Every step it finished is persisted. */
+export type ExecuteOutcome = 'executed' | 'lock-conflict' | 'stale' | 'lock-lost';
 export declare function execute(deps: RuntimePorts, agent: RegisteredAgent, input: ExecuteInput): Promise<ExecuteOutcome>;
 export interface FinalizeInput {
     state: ExecutionState;
-    stopReason: 'completed' | 'token_budget' | 'cost_budget' | 'max_steps' | 'cancelled';
+    /** Why the run ended. 'failed' for a failure; 'replaced', 'orphaned' and
+     *  'deleted' close a record that can never be worked on again. */
+    stopReason: 'completed' | 'token_budget' | 'cost_budget' | 'max_steps' | 'cancelled' | 'failed' | 'timeout' | 'replaced' | 'orphaned' | 'deleted';
     tokensUsed: number;
     attribution: TokenAttribution;
     /** generate-text flavor only: publish the final text as one TEXT_RESULT. */
@@ -71,6 +97,10 @@ export interface FinalizeInput {
  *  A budget break is NOT a user stop: the run completes with stopReason
  *  'token_budget' and the usage it actually spent. */
 export declare function finalize(deps: RuntimePorts, agent: RegisteredAgent, threadId: string, f: FinalizeInput): Promise<void>;
+/** Fail a run the queue gave up on (§2.8), when it is still the thread's
+ *  current run and the thread is still waiting on it. False when the run had
+ *  already moved on. Runs under the run lock like every other terminal write. */
+export declare function failLostRun(deps: RuntimePorts, agent: RegisteredAgent, threadId: string, runId: string | undefined, reason: string): Promise<boolean>;
 /** §2.8 failure policy: transient errors redrive through the queue; exhausted
  *  attempts finalize FAILED (hot cache + durable). A user stop is never
  *  retried, and a successful run resets the attempt counter.

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

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/core/engine.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAiB,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACvE,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAA2B,MAAM,YAAY,CAAC;AAG3F,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAInD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAWlD,OAAO,EAAgB,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAG9D,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAGzC,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,KAAK,SAAS,EAAE,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AAI9H;;iDAEiD;AACjD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAIlF;AAED;4EAC4E;AAC5E,wBAAgB,wBAAwB,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,CAElE;AA6ND;;;;;;;;;;;;;;gDAcgD;AAChD,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd;2EACuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;qCACiC;IACjC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC;AAED;;+EAE+E;AAC/E,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,eAAe,GAAG,OAAO,CAAC;AAEpE,wBAAsB,OAAO,CAC3B,IAAI,EAAE,YAAY,EAClB,KAAK,EAAE,eAAe,EACtB,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,cAAc,CAAC,CAgRzB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,cAAc,CAAC;IACtB,UAAU,EAAE,WAAW,GAAG,cAAc,GAAG,aAAa,GAAG,WAAW,GAAG,WAAW,CAAC;IACrF,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,gBAAgB,CAAC;IAC9B,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;sDACkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;sDAMsD;AACtD,wBAAsB,QAAQ,CAC5B,IAAI,EAAE,YAAY,EAClB,KAAK,EAAE,eAAe,EACtB,QAAQ,EAAE,MAAM,EAChB,CAAC,EAAE,aAAa,GACf,OAAO,CAAC,IAAI,CAAC,CAkCf;AA6CD;;;;yEAIyE;AACzE,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,YAAY,EAClB,KAAK,EAAE,eAAe,EACtB,KAAK,EAAE,YAAY,EACnB,MAAM,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,EACjC,IAAI,GAAE,OAAO,OAAiB,GAC7B,OAAO,CAAC,IAAI,CAAC,CAmDf"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/core/engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACvE,OAAO,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,eAAe,EAAqC,MAAM,YAAY,CAAC;AAG9G,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAInD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAelD,OAAO,EAAgB,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAW9D,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAGzC,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,KAAK,SAAS,EAAE,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AAG9H;;;yDAGyD;AACzD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAIlF;AAQD;4EAC4E;AAC5E,wBAAgB,wBAAwB,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,CAElE;AAsPD;;4DAE4D;AAC5D,wBAAsB,WAAW,CAC/B,IAAI,EAAE,YAAY,EAClB,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,UAAU,EAAE,aAAa,CAAC,YAAY,CAAC,iBAYxC;AAmID;;;;;;;;;;;;;;;uDAeuD;AACvD,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd;2EACuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;kEAC8D;IAC9D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;qCACiC;IACjC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,4CAA4C;IAC5C,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;kCAE8B;IAC9B,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;+EAK+E;AAC/E,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,eAAe,GAAG,OAAO,GAAG,WAAW,CAAC;AAElF,wBAAsB,OAAO,CAC3B,IAAI,EAAE,YAAY,EAClB,KAAK,EAAE,eAAe,EACtB,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,cAAc,CAAC,CAifzB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,cAAc,CAAC;IACtB;sEACkE;IAClE,UAAU,EACN,WAAW,GAAG,cAAc,GAAG,aAAa,GAAG,WAAW,GAAG,WAAW,GACxE,QAAQ,GAAG,SAAS,GAAG,UAAU,GAAG,UAAU,GAAG,SAAS,CAAC;IAC/D,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,gBAAgB,CAAC;IAC9B,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;sDACkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;sDAMsD;AACtD,wBAAsB,QAAQ,CAC5B,IAAI,EAAE,YAAY,EAClB,KAAK,EAAE,eAAe,EACtB,QAAQ,EAAE,MAAM,EAChB,CAAC,EAAE,aAAa,GACf,OAAO,CAAC,IAAI,CAAC,CAkCf;AAED;;iFAEiF;AACjF,wBAAsB,WAAW,CAC/B,IAAI,EAAE,YAAY,EAClB,KAAK,EAAE,eAAe,EACtB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,OAAO,CAAC,CAkBlB;AA0FD;;;;yEAIyE;AACzE,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,YAAY,EAClB,KAAK,EAAE,eAAe,EACtB,KAAK,EAAE,YAAY,EACnB,MAAM,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,EACjC,IAAI,GAAE,OAAO,OAAiB,GAC7B,OAAO,CAAC,IAAI,CAAC,CAsEf"}