@tangle-network/agent-runtime 5.0.0 → 6.0.2

package/dist/runtime-hooks-CsW2pfFk.js.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-hooks-CsW2pfFk.js","names":[],"sources":["../src/runtime-hooks.ts"],"sourcesContent":["/**\n *\n * Runtime hook contracts. Hooks are execution-scoped observers, not part of an\n * `AgentProfile`: profiles stay portable agent recipes; hooks attach to the\n * loop or product harness that is running the profile.\n *\n * A `pursuitId` is deliberately orthogonal to `runId`: a pursuit can span many\n * resumed/retried/forked runs while every event remains attributable to the\n * durable objective that caused it. The observer plane is outside the agent\n * environment and must never be required for agent correctness.\n *\n * @experimental\n */\n\nexport type RuntimeHookPhase = 'before' | 'after' | 'error' | 'event'\n\nexport type RuntimeHookTarget =\n  | 'agent.run'\n  | 'agent.turn'\n  | 'agent.tool_call'\n  | 'agent.spawn'\n  | 'agent.child'\n  | 'agent.plan'\n  | 'agent.decision'\n  | (string & {})\n\nexport type RuntimeDecisionKind =\n  | 'continue'\n  | 'verify'\n  | 'ask'\n  | 'retry'\n  | 'stop'\n  | 'memory-write'\n  | 'memory-read'\n  | 'tool-select'\n  | 'skill-select'\n  | 'workflow-select'\n  | 'surface-promote'\n  | (string & {})\n\nexport interface RuntimeHookEvent<Payload = unknown> {\n  id: string\n  /** Stable identity for the long-lived objective. One pursuit may contain many runs. */\n  pursuitId?: string\n  runId: string\n  scenarioId?: string\n  target: RuntimeHookTarget\n  phase: RuntimeHookPhase\n  timestamp: number\n  stepIndex?: number\n  parentId?: string\n  payload?: Payload\n  metadata?: Record<string, unknown>\n}\n\nexport interface RuntimeHookContext {\n  signal?: AbortSignal\n}\n\nexport interface RuntimeDecisionEvidenceRef {\n  source: string\n  id: string\n  detail?: string\n  metadata?: Record<string, unknown>\n}\n\nexport interface RuntimeDecisionPoint {\n  id: string\n  /** Stable identity for the long-lived objective. One pursuit may contain many runs. */\n  pursuitId?: string\n  runId: string\n  scenarioId?: string\n  stepIndex: number\n  kind: RuntimeDecisionKind\n  candidateActions: string[]\n  context?: string\n  evidence: RuntimeDecisionEvidenceRef[]\n  metadata?: Record<string, unknown>\n}\n\nexport interface RuntimeHookErrorContext {\n  hook: 'onEvent' | 'onDecisionPoint'\n  eventId?: string\n  target?: RuntimeHookTarget\n  phase?: RuntimeHookPhase\n  decisionId?: string\n  decisionKind?: RuntimeDecisionKind\n}\n\n/**\n * The observation seam attached to a running loop (never to the portable genome).\n * Implement the optional hooks to receive lifecycle events, semantic decision points,\n * and hook errors. Author with {@link defineRuntimeHooks} for inference, and attach N\n * observers at once with {@link composeRuntimeHooks} — there is ONE event stream, not a\n * callback-prop zoo.\n */\nexport interface RuntimeHooks {\n  /**\n   * General before/after/event hook. Use this for telemetry, memory capture,\n   * policy wrapping, child lifecycle observers, or product-specific extension\n   * points.\n   */\n  onEvent?: (event: RuntimeHookEvent, context: RuntimeHookContext) => void | Promise<void>\n  /**\n   * Semantic decision hook. Belief-state evaluation consumes this, but runtime\n   * code should keep emitting ordinary lifecycle events as the base layer.\n   */\n  onDecisionPoint?: (\n    point: RuntimeDecisionPoint,\n    context: RuntimeHookContext,\n  ) => void | Promise<void>\n  onHookError?: (error: Error, context: RuntimeHookErrorContext) => void | Promise<void>\n}\n\n/** Identity helper that types a {@link RuntimeHooks} literal so the fields are inferred. */\nexport function defineRuntimeHooks(hooks: RuntimeHooks): RuntimeHooks {\n  return hooks\n}\n\n/**\n * Attach a stable pursuit identity to the entire observer stream without changing\n * agent code or teaching individual runtimes about pursuits. Because recursive Scope\n * execution already inherits one RuntimeHooks instance, this wrapper automatically\n * covers descendants, nested drivers, and resumed execution that reuses the wrapper.\n *\n * Existing matching pursuit ids are preserved. A conflicting id fails closed: silently\n * rewriting attribution would make the meta-observer untrustworthy.\n */\nexport function withPursuitContext(pursuitId: string, hooks: RuntimeHooks): RuntimeHooks {\n  const stableId = pursuitId.trim()\n  if (stableId.length === 0) throw new TypeError('withPursuitContext: pursuitId must be non-empty')\n\n  const assertAndStamp = <T extends RuntimeHookEvent | RuntimeDecisionPoint>(value: T): T => {\n    if (value.pursuitId !== undefined && value.pursuitId !== stableId) {\n      throw new Error(\n        `withPursuitContext: observer identity conflict (${value.pursuitId} !== ${stableId})`,\n      )\n    }\n    if (value.pursuitId === stableId) return value\n    return { ...value, pursuitId: stableId }\n  }\n\n  return {\n    onEvent: hooks.onEvent\n      ? (event, context) => hooks.onEvent?.(assertAndStamp(event), context)\n      : undefined,\n    onDecisionPoint: hooks.onDecisionPoint\n      ? (point, context) => hooks.onDecisionPoint?.(assertAndStamp(point), context)\n      : undefined,\n    onHookError: hooks.onHookError,\n  }\n}\n\n/**\n * Merge several {@link RuntimeHooks} into one. Falsy entries are dropped (so you can\n * pass `flag && hooks`), and every observer's `onEvent`/`onDecisionPoint` fires for each\n * event. Use this to attach N observers to a loop instead of a second event bus.\n */\nexport function composeRuntimeHooks(\n  ...entries: Array<RuntimeHooks | undefined | null | false>\n): RuntimeHooks {\n  const hooks = entries.filter((entry): entry is RuntimeHooks => !!entry)\n  return {\n    onEvent: hooks.some((hook) => hook.onEvent)\n      ? (event, context) => {\n          const pending: Promise<unknown>[] = []\n          for (const hook of hooks) {\n            const result = hook.onEvent?.(event, context)\n            if (isThenable(result)) pending.push(Promise.resolve(result))\n          }\n          if (pending.length > 0) return Promise.all(pending).then(() => undefined)\n          return undefined\n        }\n      : undefined,\n    onDecisionPoint: hooks.some((hook) => hook.onDecisionPoint)\n      ? (point, context) => {\n          const pending: Promise<unknown>[] = []\n          for (const hook of hooks) {\n            const result = hook.onDecisionPoint?.(point, context)\n            if (isThenable(result)) pending.push(Promise.resolve(result))\n          }\n          if (pending.length > 0) return Promise.all(pending).then(() => undefined)\n          return undefined\n        }\n      : undefined,\n    onHookError: hooks.some((hook) => hook.onHookError)\n      ? (error, context) => {\n          const pending: Promise<unknown>[] = []\n          for (const hook of hooks) {\n            const result = hook.onHookError?.(error, context)\n            if (isThenable(result)) pending.push(Promise.resolve(result))\n          }\n          if (pending.length > 0) return Promise.all(pending).then(() => undefined)\n          return undefined\n        }\n      : undefined,\n  }\n}\n\n/** Fire `hooks.onEvent`, swallowing sync throws and surfacing async failures to `onError`. */\nexport function notifyRuntimeHookEvent(\n  hooks: RuntimeHooks | undefined,\n  event: RuntimeHookEvent,\n  context: RuntimeHookContext = {},\n): void {\n  const onEvent = hooks?.onEvent\n  if (!onEvent) return\n\n  try {\n    const result = onEvent(event, context)\n    if (isThenable(result)) {\n      void result.catch((error) => {\n        notifyRuntimeHookError(hooks, toError(error), {\n          hook: 'onEvent',\n          eventId: event.id,\n          target: event.target,\n          phase: event.phase,\n        })\n      })\n    }\n  } catch (error) {\n    notifyRuntimeHookError(hooks, toError(error), {\n      hook: 'onEvent',\n      eventId: event.id,\n      target: event.target,\n      phase: event.phase,\n    })\n  }\n}\n\n/** Fire `hooks.onDecisionPoint`, swallowing sync throws and surfacing async failures to `onError`. */\nexport function notifyRuntimeDecisionPoint(\n  hooks: RuntimeHooks | undefined,\n  point: RuntimeDecisionPoint,\n  context: RuntimeHookContext = {},\n): void {\n  const onDecisionPoint = hooks?.onDecisionPoint\n  if (!onDecisionPoint) return\n\n  try {\n    const result = onDecisionPoint(point, context)\n    if (isThenable(result)) {\n      void result.catch((error) => {\n        notifyRuntimeHookError(hooks, toError(error), {\n          hook: 'onDecisionPoint',\n          decisionId: point.id,\n          decisionKind: point.kind,\n        })\n      })\n    }\n  } catch (error) {\n    notifyRuntimeHookError(hooks, toError(error), {\n      hook: 'onDecisionPoint',\n      decisionId: point.id,\n      decisionKind: point.kind,\n    })\n  }\n}\n\nfunction notifyRuntimeHookError(\n  hooks: RuntimeHooks | undefined,\n  error: Error,\n  context: RuntimeHookErrorContext,\n): void {\n  try {\n    const result = hooks?.onHookError?.(error, context)\n    if (isThenable(result)) void result.catch(() => undefined)\n  } catch {\n    // Hook errors must never become agent-loop errors.\n  }\n}\n\nfunction isThenable(value: unknown): value is PromiseLike<unknown> {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    'then' in value &&\n    typeof (value as { then?: unknown }).then === 'function'\n  )\n}\n\nfunction toError(error: unknown): Error {\n  return error instanceof Error ? error : new Error(String(error))\n}\n"],"mappings":"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"}
+{"version":3,"file":"runtime-hooks-CsW2pfFk.js","names":[],"sources":["../src/runtime-hooks.ts"],"sourcesContent":["/**\n *\n * Runtime hook contracts. Hooks are execution-scoped observers, not part of an\n * `AgentProfile`: profiles stay portable agent recipes; hooks attach to the\n * loop or product harness that is running the profile.\n *\n * A `pursuitId` is deliberately orthogonal to `runId`: a pursuit can span many\n * resumed/retried/forked runs while every event remains attributable to the\n * durable objective that caused it. The observer plane is outside the agent\n * environment and must never be required for agent correctness.\n *\n * @experimental\n */\n\nimport type { AgentExactRunControlRef } from '@tangle-network/agent-interface'\n\nexport type RuntimeHookPhase = 'before' | 'after' | 'error' | 'event'\n\nexport type RuntimeHookTarget =\n  | 'agent.run'\n  | 'agent.turn'\n  | 'agent.tool_call'\n  | 'agent.spawn'\n  | 'agent.child'\n  | 'agent.plan'\n  | 'agent.decision'\n  | 'agent.execution'\n  | 'agent.model'\n  | 'agent.steer'\n  | (string & {})\n\nexport type RuntimeDecisionKind =\n  | 'continue'\n  | 'verify'\n  | 'ask'\n  | 'retry'\n  | 'stop'\n  | 'memory-write'\n  | 'memory-read'\n  | 'tool-select'\n  | 'skill-select'\n  | 'workflow-select'\n  | 'surface-promote'\n  | (string & {})\n\nexport interface RuntimeHookEvent<Payload = unknown> {\n  id: string\n  /** Stable identity for the long-lived objective. One pursuit may contain many runs. */\n  pursuitId?: string\n  runId: string\n  scenarioId?: string\n  target: RuntimeHookTarget\n  phase: RuntimeHookPhase\n  timestamp: number\n  stepIndex?: number\n  parentId?: string\n  payload?: Payload\n  metadata?: Record<string, unknown>\n}\n\nexport interface RuntimeHookContext {\n  signal?: AbortSignal\n}\n\n/** A provider acknowledged this exact execution; planned and refused dispatches emit none. */\nexport interface RuntimeExecutionAdmittedPayload {\n  readonly attemptId?: string\n  readonly nodeId: string\n  readonly controlRef: AgentExactRunControlRef\n  readonly sessionId: string\n}\n\nexport interface RuntimeDecisionEvidenceRef {\n  source: string\n  id: string\n  detail?: string\n  metadata?: Record<string, unknown>\n}\n\nexport interface RuntimeDecisionPoint {\n  id: string\n  /** Stable identity for the long-lived objective. One pursuit may contain many runs. */\n  pursuitId?: string\n  runId: string\n  scenarioId?: string\n  stepIndex: number\n  kind: RuntimeDecisionKind\n  candidateActions: string[]\n  context?: string\n  evidence: RuntimeDecisionEvidenceRef[]\n  metadata?: Record<string, unknown>\n}\n\nexport interface RuntimeHookErrorContext {\n  hook: 'onEvent' | 'onDecisionPoint'\n  eventId?: string\n  target?: RuntimeHookTarget\n  phase?: RuntimeHookPhase\n  decisionId?: string\n  decisionKind?: RuntimeDecisionKind\n}\n\n/**\n * The observation seam attached to a running loop (never to the portable genome).\n * Implement the optional hooks to receive lifecycle events, semantic decision points,\n * and hook errors. Author with {@link defineRuntimeHooks} for inference, and attach N\n * observers at once with {@link composeRuntimeHooks} — there is ONE event stream, not a\n * callback-prop zoo.\n */\nexport interface RuntimeHooks {\n  /**\n   * General before/after/event hook. Use this for telemetry, memory capture,\n   * policy wrapping, child lifecycle observers, or product-specific extension\n   * points.\n   */\n  onEvent?: (event: RuntimeHookEvent, context: RuntimeHookContext) => void | Promise<void>\n  /**\n   * Semantic decision hook. Belief-state evaluation consumes this, but runtime\n   * code should keep emitting ordinary lifecycle events as the base layer.\n   */\n  onDecisionPoint?: (\n    point: RuntimeDecisionPoint,\n    context: RuntimeHookContext,\n  ) => void | Promise<void>\n  onHookError?: (error: Error, context: RuntimeHookErrorContext) => void | Promise<void>\n}\n\n/** Identity helper that types a {@link RuntimeHooks} literal so the fields are inferred. */\nexport function defineRuntimeHooks(hooks: RuntimeHooks): RuntimeHooks {\n  return hooks\n}\n\n/**\n * Attach a stable pursuit identity to the entire observer stream without changing\n * agent code or teaching individual runtimes about pursuits. Because recursive Scope\n * execution already inherits one RuntimeHooks instance, this wrapper automatically\n * covers descendants, nested drivers, and resumed execution that reuses the wrapper.\n *\n * Existing matching pursuit ids are preserved. A conflicting id fails closed: silently\n * rewriting attribution would make the meta-observer untrustworthy.\n */\nexport function withPursuitContext(pursuitId: string, hooks: RuntimeHooks): RuntimeHooks {\n  const stableId = pursuitId.trim()\n  if (stableId.length === 0) throw new TypeError('withPursuitContext: pursuitId must be non-empty')\n\n  const assertAndStamp = <T extends RuntimeHookEvent | RuntimeDecisionPoint>(value: T): T => {\n    if (value.pursuitId !== undefined && value.pursuitId !== stableId) {\n      throw new Error(\n        `withPursuitContext: observer identity conflict (${value.pursuitId} !== ${stableId})`,\n      )\n    }\n    if (value.pursuitId === stableId) return value\n    return { ...value, pursuitId: stableId }\n  }\n\n  return {\n    onEvent: hooks.onEvent\n      ? (event, context) => hooks.onEvent?.(assertAndStamp(event), context)\n      : undefined,\n    onDecisionPoint: hooks.onDecisionPoint\n      ? (point, context) => hooks.onDecisionPoint?.(assertAndStamp(point), context)\n      : undefined,\n    onHookError: hooks.onHookError,\n  }\n}\n\n/**\n * Merge several {@link RuntimeHooks} into one. Falsy entries are dropped (so you can\n * pass `flag && hooks`), and every observer's `onEvent`/`onDecisionPoint` fires for each\n * event. Use this to attach N observers to a loop instead of a second event bus.\n */\nexport function composeRuntimeHooks(\n  ...entries: Array<RuntimeHooks | undefined | null | false>\n): RuntimeHooks {\n  const hooks = entries.filter((entry): entry is RuntimeHooks => !!entry)\n  return {\n    onEvent: hooks.some((hook) => hook.onEvent)\n      ? (event, context) => {\n          const pending: Promise<unknown>[] = []\n          for (const hook of hooks) {\n            const result = hook.onEvent?.(event, context)\n            if (isThenable(result)) pending.push(Promise.resolve(result))\n          }\n          if (pending.length > 0) return Promise.all(pending).then(() => undefined)\n          return undefined\n        }\n      : undefined,\n    onDecisionPoint: hooks.some((hook) => hook.onDecisionPoint)\n      ? (point, context) => {\n          const pending: Promise<unknown>[] = []\n          for (const hook of hooks) {\n            const result = hook.onDecisionPoint?.(point, context)\n            if (isThenable(result)) pending.push(Promise.resolve(result))\n          }\n          if (pending.length > 0) return Promise.all(pending).then(() => undefined)\n          return undefined\n        }\n      : undefined,\n    onHookError: hooks.some((hook) => hook.onHookError)\n      ? (error, context) => {\n          const pending: Promise<unknown>[] = []\n          for (const hook of hooks) {\n            const result = hook.onHookError?.(error, context)\n            if (isThenable(result)) pending.push(Promise.resolve(result))\n          }\n          if (pending.length > 0) return Promise.all(pending).then(() => undefined)\n          return undefined\n        }\n      : undefined,\n  }\n}\n\n/** Fire `hooks.onEvent`, swallowing sync throws and surfacing async failures to `onError`. */\nexport function notifyRuntimeHookEvent(\n  hooks: RuntimeHooks | undefined,\n  event: RuntimeHookEvent,\n  context: RuntimeHookContext = {},\n): void {\n  const onEvent = hooks?.onEvent\n  if (!onEvent) return\n\n  try {\n    const result = onEvent(event, context)\n    if (isThenable(result)) {\n      void result.catch((error) => {\n        notifyRuntimeHookError(hooks, toError(error), {\n          hook: 'onEvent',\n          eventId: event.id,\n          target: event.target,\n          phase: event.phase,\n        })\n      })\n    }\n  } catch (error) {\n    notifyRuntimeHookError(hooks, toError(error), {\n      hook: 'onEvent',\n      eventId: event.id,\n      target: event.target,\n      phase: event.phase,\n    })\n  }\n}\n\n/** Fire `hooks.onDecisionPoint`, swallowing sync throws and surfacing async failures to `onError`. */\nexport function notifyRuntimeDecisionPoint(\n  hooks: RuntimeHooks | undefined,\n  point: RuntimeDecisionPoint,\n  context: RuntimeHookContext = {},\n): void {\n  const onDecisionPoint = hooks?.onDecisionPoint\n  if (!onDecisionPoint) return\n\n  try {\n    const result = onDecisionPoint(point, context)\n    if (isThenable(result)) {\n      void result.catch((error) => {\n        notifyRuntimeHookError(hooks, toError(error), {\n          hook: 'onDecisionPoint',\n          decisionId: point.id,\n          decisionKind: point.kind,\n        })\n      })\n    }\n  } catch (error) {\n    notifyRuntimeHookError(hooks, toError(error), {\n      hook: 'onDecisionPoint',\n      decisionId: point.id,\n      decisionKind: point.kind,\n    })\n  }\n}\n\nfunction notifyRuntimeHookError(\n  hooks: RuntimeHooks | undefined,\n  error: Error,\n  context: RuntimeHookErrorContext,\n): void {\n  try {\n    const result = hooks?.onHookError?.(error, context)\n    if (isThenable(result)) void result.catch(() => undefined)\n  } catch {\n    // Hook errors must never become agent-loop errors.\n  }\n}\n\nfunction isThenable(value: unknown): value is PromiseLike<unknown> {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    'then' in value &&\n    typeof (value as { then?: unknown }).then === 'function'\n  )\n}\n\nfunction toError(error: unknown): Error {\n  return error instanceof Error ? error : new Error(String(error))\n}\n"],"mappings":";;AAgIA,SAAgB,mBAAmB,OAAmC;CACpE,OAAO;AACT;;;;;;;;;;AAWA,SAAgB,mBAAmB,WAAmB,OAAmC;CACvF,MAAM,WAAW,UAAU,KAAK;CAChC,IAAI,SAAS,WAAW,GAAG,MAAM,IAAI,UAAU,iDAAiD;CAEhG,MAAM,kBAAqE,UAAgB;EACzF,IAAI,MAAM,cAAc,KAAA,KAAa,MAAM,cAAc,UACvD,MAAM,IAAI,MACR,mDAAmD,MAAM,UAAU,OAAO,SAAS,EACrF;EAEF,IAAI,MAAM,cAAc,UAAU,OAAO;EACzC,OAAO;GAAE,GAAG;GAAO,WAAW;EAAS;CACzC;CAEA,OAAO;EACL,SAAS,MAAM,WACV,OAAO,YAAY,MAAM,UAAU,eAAe,KAAK,GAAG,OAAO,IAClE,KAAA;EACJ,iBAAiB,MAAM,mBAClB,OAAO,YAAY,MAAM,kBAAkB,eAAe,KAAK,GAAG,OAAO,IAC1E,KAAA;EACJ,aAAa,MAAM;CACrB;AACF;;;;;;AAOA,SAAgB,oBACd,GAAG,SACW;CACd,MAAM,QAAQ,QAAQ,QAAQ,UAAiC,CAAC,CAAC,KAAK;CACtE,OAAO;EACL,SAAS,MAAM,MAAM,SAAS,KAAK,OAAO,KACrC,OAAO,YAAY;GAClB,MAAM,UAA8B,CAAC;GACrC,KAAK,MAAM,QAAQ,OAAO;IACxB,MAAM,SAAS,KAAK,UAAU,OAAO,OAAO;IAC5C,IAAI,WAAW,MAAM,GAAG,QAAQ,KAAK,QAAQ,QAAQ,MAAM,CAAC;GAC9D;GACA,IAAI,QAAQ,SAAS,GAAG,OAAO,QAAQ,IAAI,OAAO,CAAC,CAAC,WAAW,KAAA,CAAS;EAE1E,IACA,KAAA;EACJ,iBAAiB,MAAM,MAAM,SAAS,KAAK,eAAe,KACrD,OAAO,YAAY;GAClB,MAAM,UAA8B,CAAC;GACrC,KAAK,MAAM,QAAQ,OAAO;IACxB,MAAM,SAAS,KAAK,kBAAkB,OAAO,OAAO;IACpD,IAAI,WAAW,MAAM,GAAG,QAAQ,KAAK,QAAQ,QAAQ,MAAM,CAAC;GAC9D;GACA,IAAI,QAAQ,SAAS,GAAG,OAAO,QAAQ,IAAI,OAAO,CAAC,CAAC,WAAW,KAAA,CAAS;EAE1E,IACA,KAAA;EACJ,aAAa,MAAM,MAAM,SAAS,KAAK,WAAW,KAC7C,OAAO,YAAY;GAClB,MAAM,UAA8B,CAAC;GACrC,KAAK,MAAM,QAAQ,OAAO;IACxB,MAAM,SAAS,KAAK,cAAc,OAAO,OAAO;IAChD,IAAI,WAAW,MAAM,GAAG,QAAQ,KAAK,QAAQ,QAAQ,MAAM,CAAC;GAC9D;GACA,IAAI,QAAQ,SAAS,GAAG,OAAO,QAAQ,IAAI,OAAO,CAAC,CAAC,WAAW,KAAA,CAAS;EAE1E,IACA,KAAA;CACN;AACF;;AAGA,SAAgB,uBACd,OACA,OACA,UAA8B,CAAC,GACzB;CACN,MAAM,UAAU,OAAO;CACvB,IAAI,CAAC,SAAS;CAEd,IAAI;EACF,MAAM,SAAS,QAAQ,OAAO,OAAO;EACrC,IAAI,WAAW,MAAM,GACnB,OAAY,OAAO,UAAU;GAC3B,uBAAuB,OAAO,QAAQ,KAAK,GAAG;IAC5C,MAAM;IACN,SAAS,MAAM;IACf,QAAQ,MAAM;IACd,OAAO,MAAM;GACf,CAAC;EACH,CAAC;CAEL,SAAS,OAAO;EACd,uBAAuB,OAAO,QAAQ,KAAK,GAAG;GAC5C,MAAM;GACN,SAAS,MAAM;GACf,QAAQ,MAAM;GACd,OAAO,MAAM;EACf,CAAC;CACH;AACF;;AAGA,SAAgB,2BACd,OACA,OACA,UAA8B,CAAC,GACzB;CACN,MAAM,kBAAkB,OAAO;CAC/B,IAAI,CAAC,iBAAiB;CAEtB,IAAI;EACF,MAAM,SAAS,gBAAgB,OAAO,OAAO;EAC7C,IAAI,WAAW,MAAM,GACnB,OAAY,OAAO,UAAU;GAC3B,uBAAuB,OAAO,QAAQ,KAAK,GAAG;IAC5C,MAAM;IACN,YAAY,MAAM;IAClB,cAAc,MAAM;GACtB,CAAC;EACH,CAAC;CAEL,SAAS,OAAO;EACd,uBAAuB,OAAO,QAAQ,KAAK,GAAG;GAC5C,MAAM;GACN,YAAY,MAAM;GAClB,cAAc,MAAM;EACtB,CAAC;CACH;AACF;AAEA,SAAS,uBACP,OACA,OACA,SACM;CACN,IAAI;EACF,MAAM,SAAS,OAAO,cAAc,OAAO,OAAO;EAClD,IAAI,WAAW,MAAM,GAAG,OAAY,YAAY,KAAA,CAAS;CAC3D,QAAQ,CAER;AACF;AAEA,SAAS,WAAW,OAA+C;CACjE,OACE,OAAO,UAAU,YACjB,UAAU,QACV,UAAU,SACV,OAAQ,MAA6B,SAAS;AAElD;AAEA,SAAS,QAAQ,OAAuB;CACtC,OAAO,iBAAiB,QAAQ,QAAQ,IAAI,MAAM,OAAO,KAAK,CAAC;AACjE"}

package/dist/{runtime-hooks-ZQqPw-0g.d.ts → runtime-hooks-DPghSHV7.d.ts}

@@ -1,18 +1,6 @@
-/**
- *
- * Runtime hook contracts. Hooks are execution-scoped observers, not part of an
- * `AgentProfile`: profiles stay portable agent recipes; hooks attach to the
- * loop or product harness that is running the profile.
- *
- * A `pursuitId` is deliberately orthogonal to `runId`: a pursuit can span many
- * resumed/retried/forked runs while every event remains attributable to the
- * durable objective that caused it. The observer plane is outside the agent
- * environment and must never be required for agent correctness.
- *
- * @experimental
- */
+import { AgentExactRunControlRef } from "@tangle-network/agent-interface";
 type RuntimeHookPhase = 'before' | 'after' | 'error' | 'event';
-type RuntimeHookTarget = 'agent.run' | 'agent.turn' | 'agent.tool_call' | 'agent.spawn' | 'agent.child' | 'agent.plan' | 'agent.decision' | (string & {});
+type RuntimeHookTarget = 'agent.run' | 'agent.turn' | 'agent.tool_call' | 'agent.spawn' | 'agent.child' | 'agent.plan' | 'agent.decision' | 'agent.execution' | 'agent.model' | 'agent.steer' | (string & {});
 type RuntimeDecisionKind = 'continue' | 'verify' | 'ask' | 'retry' | 'stop' | 'memory-write' | 'memory-read' | 'tool-select' | 'skill-select' | 'workflow-select' | 'surface-promote' | (string & {});
 interface RuntimeHookEvent<Payload = unknown> {
   id: string;
@@ -31,6 +19,13 @@ interface RuntimeHookEvent<Payload = unknown> {
 interface RuntimeHookContext {
   signal?: AbortSignal;
 }
+/** A provider acknowledged this exact execution; planned and refused dispatches emit none. */
+interface RuntimeExecutionAdmittedPayload {
+  readonly attemptId?: string;
+  readonly nodeId: string;
+  readonly controlRef: AgentExactRunControlRef;
+  readonly sessionId: string;
+}
 interface RuntimeDecisionEvidenceRef {
   source: string;
   id: string;
@@ -87,5 +82,5 @@ declare function defineRuntimeHooks(hooks: RuntimeHooks): RuntimeHooks;
  * event. Use this to attach N observers to a loop instead of a second event bus.
  */
 declare function composeRuntimeHooks(...entries: Array<RuntimeHooks | undefined | null | false>): RuntimeHooks;
-export { RuntimeHookErrorContext as a, RuntimeHookTarget as c, defineRuntimeHooks as d, RuntimeHookContext as i, RuntimeHooks as l, RuntimeDecisionKind as n, RuntimeHookEvent as o, RuntimeDecisionPoint as r, RuntimeHookPhase as s, RuntimeDecisionEvidenceRef as t, composeRuntimeHooks as u };
-//# sourceMappingURL=runtime-hooks-ZQqPw-0g.d.ts.map
+export { RuntimeHookContext as a, RuntimeHookPhase as c, composeRuntimeHooks as d, defineRuntimeHooks as f, RuntimeExecutionAdmittedPayload as i, RuntimeHookTarget as l, RuntimeDecisionKind as n, RuntimeHookErrorContext as o, RuntimeDecisionPoint as r, RuntimeHookEvent as s, RuntimeDecisionEvidenceRef as t, RuntimeHooks as u };
+//# sourceMappingURL=runtime-hooks-DPghSHV7.d.ts.map