eve 0.30.0 → 0.30.2

package/dist/src/harness/agent-handles.d.ts

@@ -1,238 +0,0 @@
-import type { HarnessSession, SessionStateMap } from "#harness/types.js";
-import type { AgentTurnOutcome } from "#shared/agent-turn-outcome.js";
-/** Session-state key for delegated agent handles. */
-export declare const AGENT_HANDLES_STATE_KEY = "eve.agent.handles";
-/** Error code for a requested agent id that is not registered. */
-export declare const AGENT_UNKNOWN = "AGENT_UNKNOWN";
-/** Error code for an agent id invoked through the wrong subagent tool. */
-export declare const AGENT_MISMATCH = "AGENT_MISMATCH";
-/** Error code for a registered agent that cannot be reached. */
-export declare const AGENT_UNREACHABLE = "AGENT_UNREACHABLE";
-/** Error code for an agent that is starting or already running a turn. */
-export declare const AGENT_BUSY = "AGENT_BUSY";
-/**
- * Stable identity of one delegated child, minted before its start side
- * effect runs. The model-visible `id` derives from the first start
- * operation, never from the child session id, so it exists before the
- * child does and cannot collide on externally supplied session suffixes.
- */
-export interface AgentIdentity {
-    /** Model-visible identifier: `ag_<name>:<operation-hash>`. */
-    readonly id: string;
-    /** Subagent tool name. */
-    readonly name: string;
-    /** Agent-graph node used to re-resolve delivery configuration. */
-    readonly nodeId: string;
-}
-/**
- * One dispatch the parent intends to perform or has performed. Repeating
- * the same operation is a replay; a different operation against a
- * starting/running handle is a busy conflict.
- */
-export interface StartOperation {
-    readonly kind: "start";
-    /** Derived via {@link deriveAgentOperationId}; stable across replays. */
-    readonly id: string;
-    readonly callId: string;
-    readonly parentTurnId: string;
-}
-/** A continuation delivery against a parked handle. */
-export interface ContinueOperation {
-    readonly kind: "continue";
-    /** Derived via {@link deriveAgentOperationId}; stable across replays. */
-    readonly id: string;
-    readonly callId: string;
-    readonly parentTurnId: string;
-    /**
-     * Status the handle showed before this delivery, restored when the
-     * delivery is rejected as retryable so the handle returns to `parked`
-     * without optional state.
-     */
-    readonly previousStatus: string;
-}
-/** Where a fresh child will be started. No session exists yet. */
-export type AgentStartTarget = {
-    readonly kind: "agent/local";
-    /** Deterministic child continuation token chosen at dispatch. */
-    readonly continuationToken: string;
-} | {
-    readonly kind: "agent/self";
-    readonly continuationToken: string;
-} | {
-    readonly kind: "agent/remote";
-    /** Deliver target base URL; never model-visible. */
-    readonly url: string;
-    /** Callback base URL stub captured at dispatch; never model-visible. */
-    readonly callbackBaseUrl: string;
-};
-/** Confirmed delivery coordinates of a started child. */
-export type AgentAddress = {
-    readonly kind: "agent/local";
-    readonly sessionId: string;
-    readonly continuationToken: string;
-} | {
-    readonly kind: "agent/self";
-    readonly sessionId: string;
-    readonly continuationToken: string;
-} | {
-    readonly kind: "agent/remote";
-    readonly sessionId: string;
-    readonly continuationToken: string;
-    readonly url: string;
-    readonly callbackBaseUrl: string;
-};
-/**
- * Durable ownership record for one delegated child.
- *
- * The store owns the full nonterminal lifecycle:
- *
- * - `starting` — the parent committed intent to start; the child may or
- *   may not exist yet.
- * - `running` — one identified child turn is outstanding.
- * - `parked` — the child is idle and resumable; only this phase is
- *   model-visible.
- *
- * A terminal child has no handle: settlement deletes it.
- */
-export type AgentHandle = {
-    readonly phase: "starting";
-    readonly identity: AgentIdentity;
-    readonly operation: StartOperation;
-    readonly target: AgentStartTarget;
-} | {
-    readonly phase: "running";
-    readonly identity: AgentIdentity;
-    readonly operation: StartOperation | ContinueOperation;
-    readonly address: AgentAddress;
-} | {
-    readonly phase: "parked";
-    readonly identity: AgentIdentity;
-    readonly address: AgentAddress;
-    readonly lastStatus: string;
-};
-/** Lifecycle phase of a delegated agent handle. */
-export type AgentHandlePhase = AgentHandle["phase"];
-/** Session-state collection of delegated agent handles. */
-export interface AgentHandleStore {
-    readonly handles: readonly AgentHandle[];
-}
-/**
- * Derives the stable operation id for one dispatch. All three inputs are
- * parent-controlled, so the id exists before any child does and replaying
- * the same call produces the same operation.
- */
-export declare function deriveAgentOperationId(input: {
-    readonly callId: string;
-    readonly parentSessionId: string;
-    readonly parentTurnId: string;
-}): string;
-/** Derives the model-visible agent id from the first start operation. */
-export declare function deriveAgentId(name: string, startOperationId: string): string;
-/** Collapses whitespace and truncates output into a handle status line. */
-export declare function formatAgentStatus(output: unknown): string;
-/**
- * Reads and validates the agent handle store from session state.
- *
- * Returns `undefined` only when no store has been written. A present but
- * invalid store throws: treating corruption as absence would let the next
- * transition silently replace every delegated child's delivery coordinates.
- */
-export declare function getAgentHandleStore(state: SessionStateMap | undefined): AgentHandleStore | undefined;
-/**
- * Records intent to start a fresh child. Must commit before the start
- * side effect runs so a crashed dispatch never orphans an unowned child.
- *
- * Throws when the identity or operation already exists: fresh starts mint
- * a new identity, so a collision means corrupted derivation, not a replay.
- */
-export declare function prepareAgentStart(session: HarnessSession, input: {
-    readonly identity: AgentIdentity;
-    readonly operation: StartOperation;
-    readonly target: AgentStartTarget;
-}): HarnessSession;
-/** Result of preparing a continuation against an existing handle. */
-export type PrepareAgentContinuationResult = {
-    readonly kind: "ready";
-    readonly session: HarnessSession;
-    readonly handle: Extract<AgentHandle, {
-        phase: "running";
-    }>;
-} | {
-    readonly kind: "unknown";
-} | {
-    readonly kind: "mismatch";
-} | {
-    readonly kind: "busy";
-};
-/**
- * Records intent to deliver a follow-up turn to a parked child. Must
- * commit before the delivery side effect runs.
- *
- * `unknown`, `mismatch`, and `busy` do not change the session; the caller
- * maps them onto {@link AGENT_UNKNOWN}, {@link AGENT_MISMATCH}, and
- * {@link AGENT_BUSY} results. Replaying the operation already recorded on
- * a running handle returns `ready` with the unchanged session.
- */
-export declare function prepareAgentContinuation(session: HarnessSession, input: {
-    readonly agentId: string;
-    readonly invokedName: string;
-    readonly operation: ContinueOperation;
-}): PrepareAgentContinuationResult;
-/**
- * Confirms a started child: `starting` becomes `running` with the child's
- * confirmed address. Throws when no starting handle carries the operation,
- * because confirming an unprepared start means ownership was never
- * committed. Re-confirming an already-running handle with the same
- * operation and address is a replay no-op.
- */
-export declare function confirmAgentStarted(session: HarnessSession, input: {
-    readonly operationId: string;
-    readonly address: AgentAddress;
-}): HarnessSession;
-/**
- * Resolves a dispatch that definitively failed.
- *
- * - A dead start or dead continuation deletes the handle: there is no
- *   child left to own.
- * - A retryable continuation failure restores `parked` with the status the
- *   handle showed before the delivery, so the model may retry the same
- *   `agentId` later.
- *
- * Unknown operations are a no-op: the failure raced a settlement that
- * already resolved the handle.
- */
-export declare function rejectAgentEffect(session: HarnessSession, input: {
-    readonly operationId: string;
-    readonly disposition: "dead" | "retryable";
-}): HarnessSession;
-/** Result of applying a settled child turn to the store. */
-export type SettleAgentTurnResult = {
-    readonly kind: "settled";
-    readonly session: HarnessSession;
-} | {
-    readonly kind: "ignored";
-    readonly reason: "unknown-operation" | "session-mismatch";
-};
-/**
- * Applies one settled child turn: `running` becomes `parked` for a parked
- * outcome or is deleted for a terminal outcome.
- *
- * The settlement must carry the operation currently recorded on the
- * running handle and the child session the address confirms; anything else
- * is ignored so a stale or forged delivery can never move a newer turn.
- */
-export declare function settleAgentTurn(session: HarnessSession, input: {
-    readonly operationId: string;
-    readonly sessionId: string;
-    readonly outcome: AgentTurnOutcome;
-}): SettleAgentTurnResult;
-/** Returns the resumable handles: the only phase the model may continue. */
-export declare function projectParkedAgentHandles(store: AgentHandleStore): readonly Extract<AgentHandle, {
-    phase: "parked";
-}>[];
-/**
- * Renders the model-visible agent listing. Only parked handles appear:
- * starting and running children cannot accept a continuation, and private
- * delivery coordinates never render.
- */
-export declare function renderAgentsSnippet(store: AgentHandleStore): string;

package/dist/src/harness/agent-handles.js

@@ -1,2 +0,0 @@
-import{createHash}from"node:crypto";import{z}from"#compiled/zod/index.js";const AGENT_HANDLES_STATE_KEY=`eve.agent.handles`,AGENT_UNKNOWN=`AGENT_UNKNOWN`,AGENT_MISMATCH=`AGENT_MISMATCH`,AGENT_UNREACHABLE=`AGENT_UNREACHABLE`,AGENT_BUSY=`AGENT_BUSY`,nonEmptyString=z.string().min(1),identitySchema=z.strictObject({id:nonEmptyString,name:nonEmptyString,nodeId:nonEmptyString}),startOperationSchema=z.strictObject({callId:nonEmptyString,id:nonEmptyString,kind:z.literal(`start`),parentTurnId:nonEmptyString}),continueOperationSchema=z.strictObject({callId:nonEmptyString,id:nonEmptyString,kind:z.literal(`continue`),parentTurnId:nonEmptyString,previousStatus:z.string().max(120)}),startTargetSchema=z.discriminatedUnion(`kind`,[z.strictObject({continuationToken:nonEmptyString,kind:z.literal(`agent/local`)}),z.strictObject({continuationToken:nonEmptyString,kind:z.literal(`agent/self`)}),z.strictObject({callbackBaseUrl:z.url(),kind:z.literal(`agent/remote`),url:z.url()})]),addressSchema=z.discriminatedUnion(`kind`,[z.strictObject({continuationToken:nonEmptyString,kind:z.literal(`agent/local`),sessionId:nonEmptyString}),z.strictObject({continuationToken:nonEmptyString,kind:z.literal(`agent/self`),sessionId:nonEmptyString}),z.strictObject({callbackBaseUrl:z.url(),continuationToken:nonEmptyString,kind:z.literal(`agent/remote`),sessionId:nonEmptyString,url:z.url()})]),agentHandleSchema=z.discriminatedUnion(`phase`,[z.strictObject({identity:identitySchema,operation:startOperationSchema,phase:z.literal(`starting`),target:startTargetSchema}),z.strictObject({address:addressSchema,identity:identitySchema,operation:z.discriminatedUnion(`kind`,[startOperationSchema,continueOperationSchema]),phase:z.literal(`running`)}),z.strictObject({address:addressSchema,identity:identitySchema,lastStatus:z.string().max(120),phase:z.literal(`parked`)})]),agentHandleStoreSchema=z.strictObject({handles:z.array(agentHandleSchema)}).refine(e=>new Set(e.handles.map(e=>e.identity.id)).size===e.handles.length,{message:`Agent handle ids must be unique.`});function deriveAgentOperationId(t){return createHash(`sha256`).update(`${t.parentSessionId}\0${t.parentTurnId}\0${t.callId}`).digest(`hex`)}function deriveAgentId(e,t){return`ag_${e}:${t.slice(0,12)}`}function formatAgentStatus(e){return(typeof e==`string`?e:JSON.stringify(e)??``).replaceAll(/\s+/g,` `).trim().slice(0,120)}function getAgentHandleStore(e){let t=e?.[AGENT_HANDLES_STATE_KEY];if(t===void 0)return;let r=agentHandleStoreSchema.safeParse(t);if(!r.success)throw Error(`Corrupt agent handle store under session state key "${AGENT_HANDLES_STATE_KEY}": ${r.error.message}`);return r.data}function prepareAgentStart(e,t){let n=getAgentHandleStore(e.state)?.handles??[];if(n.some(e=>e.identity.id===t.identity.id))throw Error(`Agent handle "${t.identity.id}" already exists.`);return writeHandles(e,[...n,{identity:t.identity,operation:t.operation,phase:`starting`,target:t.target}])}function prepareAgentContinuation(e,t){let n=getAgentHandleStore(e.state)?.handles??[],r=n.find(e=>e.identity.id===t.agentId);if(r===void 0)return{kind:`unknown`};if(r.identity.name!==t.invokedName)return{kind:`mismatch`};if(r.phase===`running`&&r.operation.id===t.operation.id)return{handle:r,kind:`ready`,session:e};if(r.phase!==`parked`)return{kind:`busy`};let i={address:r.address,identity:r.identity,operation:{...t.operation,previousStatus:r.lastStatus},phase:`running`};return{handle:i,kind:`ready`,session:writeHandles(e,n.map(e=>e.identity.id===t.agentId?i:e))}}function findActiveHandle(e,t){return e.find(e=>e.phase!==`parked`&&e.operation.id===t)}function confirmAgentStarted(e,t){let n=getAgentHandleStore(e.state)?.handles??[],r=findActiveHandle(n,t.operationId);if(r===void 0)throw Error(`No prepared agent handle for operation "${t.operationId}".`);return r.phase===`running`?e:writeHandles(e,n.map(e=>e===r?{address:t.address,identity:r.identity,operation:r.operation,phase:`running`}:e))}function rejectAgentEffect(e,t){let n=getAgentHandleStore(e.state)?.handles??[],r=findActiveHandle(n,t.operationId);if(r===void 0)return e;if(t.disposition===`retryable`&&r.phase===`running`){let{operation:t}=r;if(t.kind===`continue`)return writeHandles(e,n.map(e=>e===r?{address:r.address,identity:r.identity,lastStatus:t.previousStatus,phase:`parked`}:e))}return writeHandles(e,n.filter(e=>e!==r))}function settleAgentTurn(e,t){let n=getAgentHandleStore(e.state)?.handles??[],r=n.find(e=>e.phase===`running`&&e.operation.id===t.operationId);if(r===void 0||r.phase!==`running`)return{kind:`ignored`,reason:`unknown-operation`};if(r.address.sessionId!==t.sessionId)return{kind:`ignored`,reason:`session-mismatch`};if(t.outcome.kind===`terminal`)return{kind:`settled`,session:writeHandles(e,n.filter(e=>e!==r))};let{result:i}=t.outcome,a=i.kind===`succeeded`?formatAgentStatus(i.output):i.kind===`failed`?formatAgentStatus(i.error):`(cancelled)`;return{kind:`settled`,session:writeHandles(e,n.map(e=>e===r?{address:r.address,identity:r.identity,lastStatus:a,phase:`parked`}:e))}}function projectParkedAgentHandles(e){return e.handles.filter(e=>e.phase===`parked`)}function renderAgentsSnippet(e){return[`[Agents]`,`<agents>`,...projectParkedAgentHandles(e).map(e=>`<agent id="${escapeXml(e.identity.id)}" name="${escapeXml(e.identity.name)}">${escapeXml(e.lastStatus===``?`(no status)`:e.lastStatus)}</agent>`),`</agents>`].join(`
-`)}function writeHandles(e,t){return{...e,state:{...e.state,[AGENT_HANDLES_STATE_KEY]:{handles:t}}}}function escapeXml(e){return e.replaceAll(`&`,`&amp;`).replaceAll(`"`,`&quot;`).replaceAll(`<`,`&lt;`).replaceAll(`>`,`&gt;`)}export{AGENT_BUSY,AGENT_HANDLES_STATE_KEY,AGENT_MISMATCH,AGENT_UNKNOWN,AGENT_UNREACHABLE,confirmAgentStarted,deriveAgentId,deriveAgentOperationId,formatAgentStatus,getAgentHandleStore,prepareAgentContinuation,prepareAgentStart,projectParkedAgentHandles,rejectAgentEffect,renderAgentsSnippet,settleAgentTurn};