@dougbots/avenor-core 0.14.0 → 0.16.0

package/dist/index.d.ts

@@ -144,11 +144,119 @@ interface WorkflowControllerCreateParams {
   controller_id: string;
   max_inflight: number;
 }
+interface MessageSendParams {
+  to_run_id: string;
+  message_id: string;
+  generation: string;
+  body: string;
+  no_reply?: boolean;
+}
+interface MessageSendResult {
+  outcome: string;
+  message_id?: string;
+  generation?: string;
+}
+interface MessageWaitParams {
+  message_id: string;
+  generation: string;
+  timeout_ms?: number;
+}
+interface MessageInbound {
+  message_id: string;
+  from_run_id: string;
+  sender?: string;
+  kind?: string;
+  payload?: unknown;
+}
+interface MessageWaitResult {
+  outcome: string;
+  message_id?: string;
+  reply?: MessageInbound;
+}
+interface MessageWithdrawParams {
+  message_id: string;
+  generation: string;
+}
+interface MessageFence {
+  sender: string;
+  message_id: string;
+  generation: string;
+  deadline: number;
+  terminal: boolean;
+}
+interface MessageWithdrawResult {
+  outcome: string;
+  fence?: MessageFence;
+}
+interface MessageReceiveParams {
+  generation: string;
+  timeout_ms?: number;
+  limit?: number;
+}
+interface MessageReceiveResult {
+  messages: MessageInbound[];
+  generation?: string;
+}
+interface MessagePeersParams {
+  generation: string;
+}
+interface MessagePeer {
+  run_id: string;
+  session?: unknown;
+}
+interface MessagePeersResult {
+  peers: MessagePeer[];
+  generation?: string;
+}
+interface MessagePreflightResult {
+  protocol: number;
+  generation: string;
+}
+interface ResumeParams {
+  run_id: string;
+  target: string;
+  message: string;
+  label?: string;
+  idempotency_key?: string;
+  sentinel_file?: string;
+  on_event?: string;
+}
+interface ResumeResult {
+  run_id: string;
+  label: string;
+  runtime_id: string;
+  session_id: string;
+  sentinel_file: string;
+  on_event: string;
+}
+interface SessionRenameResult {
+  run_id: string;
+  label: string;
+  previous_label: string;
+}
+interface SessionLastResult {
+  run_id: string;
+  label?: string;
+  has_record: boolean;
+  final_output: string;
+  stop_reason?: string;
+  final_output_truncated?: boolean;
+  at?: number;
+}
 declare class RpcError extends Error {
   readonly code: number;
   readonly data?: unknown;
   constructor(code: number, message: string, data?: unknown);
 }
+type OwnerAuthFailureKind = 'unauthenticated' | 'unsupported' | 'timeout';
+/** A classified owner-authentication rejection, not generic transport failure. */
+declare class OwnerAuthError extends Error {
+  readonly kind: OwnerAuthFailureKind;
+  constructor(kind: OwnerAuthFailureKind, options?: {
+    code?: number;
+    reason?: string;
+  });
+}
 declare class Client {
   private socket;
   private rl;
@@ -171,6 +279,22 @@ declare class Client {
   call(method: string, params?: unknown, opts?: {
     timeoutMs?: number;
   }): Promise<unknown>;
+  /**
+   * Send a credential-free identity probe. The control server returns the
+   * startup token only after it has published its own owner record.
+   */
+  identity(timeoutMs?: number): Promise<string>;
+  /**
+   * Present the owner capability on this connection. The caller must already
+   * have bound the connection to a trusted peer: an owner attach checks the
+   * socket's ownership and identity, and an owned start proves the child with
+   * its attempt token.
+   */
+  authenticateOwner(capability: {
+    id: string;
+    secret: string;
+  }, timeoutMs?: number): Promise<void>;
+  private sendCall;
   subscribe(options?: SubscribeOptions): Promise<void>;
   events(options?: SubscribeOptions): AsyncIterableIterator<Event>;
   history(options: HistoryOptions): Promise<HistoryResult>;
@@ -200,24 +324,64 @@ declare class Client {
   workflowControllerCreate(params: WorkflowControllerCreateParams): Promise<Record<string, unknown>>;
   workflowControllerEnable(controllerId: string): Promise<Record<string, unknown>>;
   workflowControllerDisable(controllerId: string, reason: string): Promise<Record<string, unknown>>;
-  brokerSend(fromRunId: string, toRunId: string, message: string, role?: string): Promise<void>;
-  brokerAsk(toRunId: string, message: string, role?: string, timeoutMs?: number): Promise<Record<string, unknown>>;
-  brokerPeers(): Promise<Array<Record<string, unknown>>>;
-  brokerCancel(messageId: string): Promise<void>;
-  brokerReceive(): Promise<Array<{
-    from_run_id: string;
+  messageSend(params: MessageSendParams): Promise<MessageSendResult>;
+  messageWait(params: MessageWaitParams): Promise<MessageWaitResult>;
+  messageReply(params: {
+    to_run_id: string;
     message_id: string;
-    message: string;
-    role?: string;
-  }>>;
-  brokerReply(toRunId: string, replyTo: string, message: string): Promise<void>;
+    correlation_id?: string;
+    body: string;
+  }): Promise<MessageSendResult>;
+  messageWithdraw(params: MessageWithdrawParams): Promise<MessageWithdrawResult>;
+  messageReceive(params: MessageReceiveParams): Promise<MessageReceiveResult>;
+  messagePeers(params: MessagePeersParams): Promise<MessagePeersResult>;
+  messagePreflight(): Promise<MessagePreflightResult>;
+  resume(params: ResumeParams): Promise<ResumeResult>;
+  sessionRename(sessionId: string, name: string): Promise<SessionRenameResult>;
+  sessionLast(runtimeId: string): Promise<SessionLastResult>;
+  sessionLastSet(runtimeId: string, finalOutput: string, stopReason: string, truncated: boolean): Promise<void>;
+  workflowCancel(workflowId: string, actor: string, reason: string): Promise<Record<string, unknown>>;
   isClosed(): boolean;
   close(): void;
 }
 declare function dial(socketPath: string, opts?: {
   callTimeoutMs?: number;
+  connectTimeoutMs?: number;
 }): Promise<Client>;
 //#endregion
+//#region src/owner-attach.d.ts
+/** The owner record published beside a control socket is absent. */
+declare class OwnerRecordMissingError extends Error {
+  readonly socketPath: string;
+  constructor(socketPath: string);
+}
+/** The record or the socket it names no longer describes the live path. */
+declare class StaleOwnerRecordError extends Error {
+  readonly socketPath: string;
+  readonly reason: string;
+  constructor(socketPath: string, reason: string);
+}
+/**
+ * The control socket path is not bound to this euid, or its directory is
+ * writable by another user. No credential byte may be sent to that peer.
+ */
+declare class ForeignPeerError extends Error {
+  readonly socketPath: string;
+  readonly euid: number;
+  readonly reason: string;
+  readonly peerUID?: number | undefined;
+  constructor(socketPath: string, euid: number, reason: string, peerUID?: number | undefined);
+}
+interface OwnerAttachOptions {
+  timeoutMs?: number;
+}
+/**
+ * Load the owner record, bind the socket path to this euid and require it to be
+ * the record's socket, dial, re-check the socket identity and authenticate. The
+ * whole attach is bounded by the timeout.
+ */
+declare function attachOwner(socketPath: string, options?: OwnerAttachOptions): Promise<Client>;
+//#endregion
 //#region src/run-events.d.ts
 type RunChunkRole = 'assistant' | 'thought' | 'user';
 interface RunPermissionOption {
@@ -429,6 +593,20 @@ declare class Supervisor {
    * Public run IDs are canonical; labels are lookup-only aliases.
    */
   getRunByReference(reference: string): RunInfo | undefined;
+  /**
+   * Look up a run by its public run ID only, never by a label alias. The
+   * messaging router resolves public IDs and labels on separate planes, so a
+   * label that happens to equal another run's old ID must not match here.
+   */
+  getRunById(runId: string): RunInfo | undefined;
+  /**
+   * Register a run this supervisor resumed, so its ID and label stay resolvable.
+   * Last write wins: an existing entry with the same run ID, or a label held by
+   * another run, is replaced. Duplicate rejection is the resume provider's job.
+   */
+  registerResumed(run: RunInfo): void;
+  /** The one place a run's ID and label are registered, for spawn and for resume. */
+  private register;
   /** Match a stored run by its broker runtime ID. */
   getRunByRuntimeId(runtimeId: string): RunInfo | undefined;
   /**
@@ -452,7 +630,11 @@ declare class Supervisor {
 declare function socketsRoot(): string;
 //#endregion
 //#region src/tools/get-supervisor-client.d.ts
-declare function getSupervisorClient(supervisorId: string | undefined): Promise<{
+interface SupervisorClientOptions {
+  /** Attach with the socket's published owner capability instead of a bare dial. */
+  owner?: boolean;
+}
+declare function getSupervisorClient(supervisorId: string | undefined, options?: SupervisorClientOptions): Promise<{
   client: Client;
   isSingleton: boolean;
   sup: Supervisor | null;
@@ -626,20 +808,6 @@ declare function answerPermissionTool(args: {
   ok: boolean;
 }>;
 //#endregion
-//#region src/tools/follow-up.d.ts
-interface FollowUpToolArgs {
-  runId: string;
-  message: string;
-  label?: string;
-  supervisorId?: string;
-}
-interface FollowUpToolResult {
-  run_id: string;
-  label: string;
-  runtime_id?: string;
-}
-declare const followUpTool: (args: FollowUpToolArgs) => Promise<FollowUpToolResult>;
-//#endregion
 //#region src/tools/shutdown.d.ts
 declare function shutdownTool(args: {
   supervisorId?: string;
@@ -649,45 +817,368 @@ declare function shutdownTool(args: {
   cleaned_up: string[];
 }>;
 //#endregion
-//#region src/tools/ask.d.ts
-interface AskToolArgs {
-  toRunId: string;
-  message: string;
-  supervisorId?: string;
-  timeoutMs?: number;
-}
-interface AskResult {
-  reply: string;
-  from_run_id: string;
-}
-declare const askTool: (args: AskToolArgs) => Promise<AskResult>;
+//#region src/messaging-text.d.ts
+/** Every outcome the contract declares: the nine messaging rows and the two tool rows. */
+declare const MESSAGE_OUTCOMES: [string, ...string[]];
+type MessageOutcome = (typeof MESSAGE_OUTCOMES)[number];
+/** The ask acceptance window the message ids encode, in milliseconds. */
+declare const MAX_WAIT_MS = 600000;
+/** The bound `session_last_set` carries from the producer, in code points. */
+declare const MAX_FINAL_OUTPUT_RUNES = 4096;
+/** Render the (action, outcome) template; an unlisted pair renders as "". */
+declare function renderOutcome(action: string, outcome: string, facts?: Record<string, string>): string;
+/** Render a repair sentence; the templates are the conformance fixture's `repairs`. */
+declare function repair(code: string, facts?: Record<string, string>): string;
+/** Render one of the peers `last` templates. */
+declare function renderLast(key: string, facts?: Record<string, string>): string;
+/**
+ * Render a value for a template fact as one JSON string literal. Control,
+ * format, line- and paragraph-separator characters are escaped, so a label a
+ * producer controls cannot carry a bidi override or a zero-width character into
+ * tool text. The rule is byte-identical to internal/messaging.Quote.
+ */
+declare function quote(value: string): string;
+/** Escape the same characters as quote without adding the surrounding quotes. */
+declare function sanitize(value: string): string;
+/** Render every value with quote and join them with ", ". */
+declare function quoteList(values: string[]): string;
+/**
+ * Mint a versioned message id whose acceptance deadline is encoded inside it.
+ * The zero-deadline form spans the shared wait window, exactly like
+ * messaging.NewMsgID(now, time.Time{}).
+ */
+declare function newMsgID(now?: number): string;
+/**
+ * Map pi's raw stop reasons onto avenor's canonical words, so a Pi host's
+ * published reason and a Pi child's session.end reason agree. The table is
+ * exactly internal/runtime/pi/events.go:normalizePiStopReason's; a spelling it
+ * does not know passes through and stays unknown here too.
+ */
+declare function normalizeTurnStopReason(stopReason: string): string;
+/**
+ * Read the last assistant message's text and raw stop reason from an agent_end
+ * payload's `messages`, the TS twin of internal/runtime/pi's extractPiText plus
+ * the per-message `stopReason` read that translateAgentEnd does. Go also falls
+ * back to payload-level stopReason/errorMessage and normalises the stop reason;
+ * this helper sees only the messages array and does neither.
+ */
+declare function extractTurnText(messages: unknown[]): {
+  text: string;
+  stopReason: string;
+};
+/** Bound a published turn at the same rune count the Go recorder uses. */
+declare function boundFinalOutput(text: string): string;
+/** Extract the reply body from a wait result payload, as askclient.RenderReply does. */
+declare function extractReplyMessage(result: Record<string, unknown>): string;
+/**
+ * Render the shared ask failure sentence for an ask that failed. The outcome
+ * and the sentence both come from the contract, so TS and Go text agree.
+ */
+declare function renderAskFailure(messageId: string, target: string, outcome?: MessageOutcome): string;
+/**
+ * Reduce a caller-supplied ask timeout to what the broker accepts: a positive
+ * finite number of milliseconds, or undefined to keep the broker's own wait.
+ */
+declare function normalizeAskTimeoutMs(timeoutMs: number | undefined): number | undefined;
 //#endregion
-//#region src/tools/peers.d.ts
-interface PeersToolArgs {
-  supervisorId?: string;
-}
-interface PeerEntry {
+//#region src/message.d.ts
+type MessageCallerKind = 'owner' | 'broker';
+type MessageSurface = 'pi-host' | 'pi-child' | 'opencode' | 'mcp-ts' | 'mcp' | 'channeltools' | 'sidecar';
+/** One peers `list` entry: the tool's projection of the broker's SessionInfo. */
+interface PeerRecord {
   run_id: string;
   label?: string;
+  kind?: string;
   status?: string;
   backend?: string;
   model?: string;
   dir?: string;
 }
-interface PeersResult {
-  peers: PeerEntry[];
+/**
+ * One routed call's outcome and the facts a surface reports. `text` is the
+ * (action, outcome) render template and is set on every result, so no surface
+ * composes a sentence and every failure says whether an ask can still be
+ * withdrawn.
+ */
+interface ProviderResult {
+  action?: string;
+  outcome: MessageOutcome;
+  messageId?: string;
+  reply?: string;
+  text?: string;
+  runId?: string;
+  runtimeId?: string;
+  sessionId?: string;
+  label?: string;
+  previousLabel?: string;
+  sentinelFile?: string;
+  onEvent?: string;
+  finalOutput?: string;
+  stopReason?: string;
+  truncated?: boolean;
+  hasRecord?: boolean;
+  /** A peers `list` transport's error text; set only on an incomplete listing. */
+  detail?: string;
+}
+interface Resolution {
+  runId: string;
+  publicRunId?: string;
+  match: 'unique' | 'ambiguous' | 'none';
+  label?: string;
+  candidates?: string[];
+}
+interface RunFacts {
+  live: boolean;
+  resumable: boolean;
+  status: string;
+}
+interface PeersProviderResult {
+  peers: PeerRecord[];
+  /** Set when the transport returned peers together with an error. */
+  detail?: string;
 }
-declare const peersTool: (args: PeersToolArgs) => Promise<PeersResult>;
+/**
+ * What one bound surface supplies to the router: who it speaks as, how it
+ * resolves and reads state, and the action methods only it can perform.
+ */
+interface MessageProvider {
+  caller(): {
+    kind: MessageCallerKind;
+    runId: string;
+  };
+  surface(): MessageSurface;
+  role(): string;
+  resolve(ref: string): Promise<Resolution>;
+  state(runId: string): Promise<RunFacts>;
+  tell(targetRunId: string, message: string): Promise<ProviderResult>;
+  ask(targetRunId: string, message: string, timeoutMs?: number, signal?: AbortSignal): Promise<ProviderResult>;
+  reply(inboundAskId: string, message: string, askerRunId: string): Promise<ProviderResult>;
+  withdraw(messageId: string): Promise<ProviderResult>;
+  controlReply?(target: string, payload: unknown): Promise<ProviderResult>;
+  /** `target` is the RESOLVED runtime id; the provider mints runId and paths. */
+  resume(req: {
+    target: string;
+    message: string;
+    label?: string;
+    idempotencyKey?: string;
+  }): Promise<ProviderResult>;
+  rename(req: {
+    sessionId?: string;
+    name: string;
+  }): Promise<ProviderResult>;
+  last(runId: string): Promise<ProviderResult>;
+  peers(): Promise<PeersProviderResult>;
+  /** Host surfaces that own a turn loop publish their own finished turn. */
+  recordLastTurn?(text: string, stopReason: string, truncated: boolean): Promise<void>;
+  claimAsk?(messageId: string): string | undefined;
+  restoreAsk?(messageId: string, askerRunId: string): void;
+  /** Drop a claim once the asker has the answer; the claim map may belong to the surface. */
+  releaseAsk?(messageId: string): void;
+  onResumed?(result: ProviderResult): void | Promise<void>;
+  registerResumed?(result: ProviderResult): void | Promise<void>;
+}
+/** A typed tool denial: one fixed code and the rendered sentence. */
+declare class ToolError extends Error {
+  readonly code: string;
+  readonly facts: Record<string, string>;
+  constructor(code: string, message: string, facts?: Record<string, string>);
+}
+interface MessageInput {
+  action: 'tell' | 'ask' | 'reply' | 'resume' | 'withdraw' | 'control_reply';
+  target?: string;
+  message?: string;
+  reply_to?: string;
+  message_id?: string;
+  timeout_ms?: number;
+  label?: string;
+  idempotency_key?: string;
+  payload?: Record<string, unknown>;
+}
+interface PeersInput {
+  action?: 'list' | 'rename' | 'last';
+  name?: string;
+  session_id?: string;
+  target?: string;
+}
+interface PeersRouterResult {
+  action: 'list' | 'rename' | 'last';
+  outcome?: MessageOutcome;
+  text: string;
+  peers: PeerRecord[];
+  renamed?: {
+    run_id: string;
+    label: string;
+    previous_label: string;
+  };
+  last?: {
+    run_id: string;
+    runtime_id: string;
+    label: string;
+    final_output: string;
+    stop_reason: string;
+    final_output_truncated: boolean;
+  };
+}
+/**
+ * Phase 1 for avenor_message: the action enum, the action's permitted and
+ * required field sets, and each field's declared wire type and limits. The
+ * table is the one the Go router validates against.
+ */
+declare function assertMessageInput(input: unknown): asserts input is MessageInput;
+/**
+ * Phase 1 for avenor_peers. An omitted action means `list`; a present but
+ * non-string or unknown action is one invalid action, like the Go router.
+ */
+declare function assertPeersInput(input: unknown): asserts input is PeersInput;
+/** Route one avenor_message call through one provider. */
+declare function executeMessage(provider: MessageProvider, input: unknown, options?: {
+  signal?: AbortSignal;
+}): Promise<ProviderResult>;
+/** Route one avenor_peers call through one provider. */
+declare function executePeers(provider: MessageProvider, input: unknown): Promise<PeersRouterResult>;
+/**
+ * Render the peers list block the surfaces show: the one list text for the
+ * shared records, so every surface that routes through the router renders a
+ * peer identically.
+ */
+declare function renderPeerList(records: PeerRecord[]): string;
+/**
+ * The one result object every surface returns for a routed message call.
+ * Snake_case and the contract field set, exactly like the Go router's
+ * `Result.Output()`: a fact that is absent is a key that is absent, `text` is
+ * always present, and the resume paths travel with the result that minted them.
+ */
+declare function resultOutput(result: ProviderResult): Record<string, unknown>;
+/**
+ * The one structured result every surface returns for a peers call, matching
+ * `router.PeersDetails` field for field: `list` carries the peer records,
+ * `rename` the new and previous label, `last` the recorded turn. An optional
+ * peer field that is absent is a key that is absent.
+ */
+declare function peersDetails(result: PeersRouterResult): Record<string, unknown>;
 //#endregion
-//#region src/tools/cancel.d.ts
-interface CancelToolArgs {
-  messageId: string;
-  supervisorId?: string;
+//#region src/tools/message.d.ts
+/**
+ * The one avenor_message handler: every surface routes through it, so the six
+ * actions and their failure text exist once. A router tool error is thrown as a
+ * typed Error, which each surface reports as its own error result.
+ */
+declare function messageTool(args: unknown, provider: MessageProvider, options?: {
+  signal?: AbortSignal;
+}): Promise<ProviderResult>;
+/** Bind the handler to one provider. */
+declare function createMessageTool(provider: MessageProvider): (args: unknown, options?: {
+  signal?: AbortSignal;
+}) => Promise<ProviderResult>;
+//#endregion
+//#region src/tools/message-provider.d.ts
+/** The control-client surface a host provider needs, narrowed for testability. */
+interface MessageClient {
+  messageSend(params: {
+    to_run_id: string;
+    message_id: string;
+    generation: string;
+    body: string;
+    no_reply?: boolean;
+  }): Promise<MessageSendResult>;
+  messageWait(params: {
+    message_id: string;
+    generation: string;
+    timeout_ms?: number;
+  }): Promise<MessageWaitResult>;
+  messageReply(params: {
+    to_run_id: string;
+    message_id: string;
+    correlation_id?: string;
+    body: string;
+  }): Promise<MessageSendResult>;
+  messageWithdraw(params: {
+    message_id: string;
+    generation: string;
+  }): Promise<MessageWithdrawResult>;
+  messagePeers(params: {
+    generation: string;
+  }): Promise<MessagePeersResult>;
+  resume(params: {
+    run_id: string;
+    target: string;
+    message: string;
+    label?: string;
+    idempotency_key?: string;
+    sentinel_file?: string;
+    on_event?: string;
+  }): Promise<ResumeResult>;
+  sessionRename(sessionId: string, name: string): Promise<SessionRenameResult>;
+  sessionLast(runtimeId: string): Promise<SessionLastResult>;
+  sessionLastSet(runtimeId: string, finalOutput: string, stopReason: string, truncated: boolean): Promise<void>;
+  status(runtimeId?: string): Promise<Record<string, unknown>>;
 }
-interface CancelResult {
-  cancelled: boolean;
+/** One route's answer from a child surface's inherited broker. */
+interface ChildBroker {
+  tell(targetRunId: string, message: string, messageId: string): Promise<ProviderResult>;
+  ask(targetRunId: string, message: string, messageId: string, timeoutMs?: number, signal?: AbortSignal): Promise<ProviderResult>;
+  reply(askerRunId: string, inboundAskId: string, message: string): Promise<ProviderResult>;
+  withdraw(messageId: string): Promise<ProviderResult>;
+  peers(): Promise<PeersProviderResult>;
+  rename(req: {
+    sessionId?: string;
+    name: string;
+  }): Promise<ProviderResult>;
+  last(runId: string): Promise<ProviderResult>;
+}
+interface PendingAsk {
+  from_run_id: string;
+  message_id: string;
 }
-declare const cancelTool: (args: CancelToolArgs) => Promise<CancelResult>;
+/** The broker rejected a receive because the caller's generation is stale. */
+declare function isGenerationMismatchError(error: unknown): boolean;
+interface HostProviderOptions {
+  surface: MessageSurface;
+  supervisorId: string;
+  generation: string;
+  client: MessageClient;
+  /** The pending inbound asks the surface's poll fills; absent = no inbound. */
+  pendingAsks?: Map<string, PendingAsk>;
+  /** The poll generation a restore is scoped to, so a restart cannot resurrect an ask. */
+  pollGeneration?: () => number;
+  /** Runs after a successful resume registration; the surface's own tracking. */
+  onResumed?: (result: ProviderResult) => void | Promise<void>;
+}
+type AskClaims = Map<string, {
+  asker: string;
+  generation: number;
+}>;
+/** Install the claim/restore pair both factories share, so a restart cannot resurrect a stale ask. */
+declare function installAskClaims(provider: MessageProvider, claims: AskClaims, pendingAsks: Map<string, PendingAsk>, pollGeneration: (() => number) | undefined): void;
+/**
+ * Build the bound host provider: one supervisor, one generation, one control
+ * client. It never reads an ambient singleton or retargets, and it never
+ * preflights per call.
+ */
+declare function createHostMessageProvider(options: HostProviderOptions): MessageProvider;
+interface ChildProviderOptions {
+  surface: MessageSurface;
+  runId: string;
+  broker: ChildBroker;
+  /** The pending inbound asks the child's poll fills. */
+  pendingAsks?: Map<string, PendingAsk>;
+  /** The poll generation a restore is scoped to, so a restart cannot resurrect an ask. */
+  pollGeneration?: () => number;
+}
+/**
+ * Build a child provider over the surface's inherited broker. A child never
+ * learns a public run id, and it cannot read a sentinel, so it is never
+ * resumable from here: the supervisor owns a resume.
+ */
+declare function createChildMessageProvider(options: ChildProviderOptions): MessageProvider;
+//#endregion
+//#region src/tools/peers.d.ts
+interface PeersToolArgs extends PeersInput {}
+type PeersResult = PeersRouterResult;
+/** The one avenor_peers handler; it resolves and reads through the bound provider. */
+declare function peersTool(args: PeersToolArgs, provider: MessageProvider): Promise<PeersResult>;
+/** Bind the peers handler to one provider. */
+declare function createPeersTool(provider: MessageProvider): (args: PeersToolArgs) => Promise<PeersResult>;
 //#endregion
 //#region src/tools/kill.d.ts
 interface KillToolArgs {
@@ -704,6 +1195,10 @@ declare const killTool: (args: KillToolArgs) => Promise<KillResult>;
 //#region src/tools/broker-receive.d.ts
 interface BrokerReceiveArgs {
   supervisorId?: string;
+  /** The generation this poll is bound to; absent asks the tool to preflight once. */
+  generation?: string;
+  /** Bound on the receive wait; the caller owns it, so the tool adds no default. */
+  timeout_ms?: number;
 }
 interface InboundAsk {
   from_run_id: string;
@@ -713,21 +1208,11 @@ interface InboundAsk {
 }
 interface BrokerReceiveResult {
   asks: InboundAsk[];
+  /** The generation the receive ran under, so the caller can bind its next poll. */
+  generation?: string;
 }
 declare const brokerReceiveTool: (args: BrokerReceiveArgs) => Promise<BrokerReceiveResult>;
 //#endregion
-//#region src/tools/broker-reply.d.ts
-interface BrokerReplyArgs {
-  toRunId: string;
-  replyTo: string;
-  message: string;
-  supervisorId?: string;
-}
-interface BrokerReplyResult {
-  ok: true;
-}
-declare const brokerReplyTool: (args: BrokerReplyArgs) => Promise<BrokerReplyResult>;
-//#endregion
 //#region src/tools/workflow-client.d.ts
 type GetSupervisorClient = typeof getSupervisorClient;
 //#endregion
@@ -805,4 +1290,19 @@ type WorkflowReadyResult = Record<string, unknown>;
 declare function createWorkflowReadyTool(getSupervisorClient: GetSupervisorClient): (args: WorkflowReadyToolArgs) => Promise<WorkflowReadyResult>;
 declare const workflowReadyTool: (args: WorkflowReadyToolArgs) => Promise<WorkflowReadyResult>;
 //#endregion
-export { type AskResult, type AskToolArgs, type BrokerReceiveArgs, type BrokerReceiveResult, type BrokerReplyArgs, type BrokerReplyResult, type CancelResult, type CancelToolArgs, type Client, DEFAULT_RUN_REDUCER_LIMITS, type Event, type ExecutionIdentity, type FollowUpToolArgs, type FollowUpToolResult, type HistoryOptions, type HistoryResult, type InboundAsk, type InspectResult, type KillResult, type KillToolArgs, type NormalizedRunEvent, type ObserveRunOptions, type PeerEntry, type PeersResult, type ResultResult, type ResultToolArgs, RpcError, type RunChunkRole, type RunIdentity, type RunInfo, type RunObserver, type RunObserverClient, type RunPermissionOption, type RunPermissionSummary, RunReducer, type RunReducerLimits, type RunSnapshot, type RunSnapshotSeed, type RunToolState, type RunToolSummary, type RunTranscriptEntry, type SpawnMetadata, type SpawnParams, type SpawnResult, type SpawnSelectionInput, type SpawnToolArgs, type SpawnToolResult, type StatusListResult, type StatusResult, type StatusToolArgs, type StatusView, type SubscribeOptions, Supervisor, type SupervisorOptions, THINKING_LEVELS, type ThinkingLevel, type ThinkingOutcome, type WorkflowCompleteParams, type WorkflowCompleteResult, type WorkflowCompleteToolArgs, type WorkflowControllerCreateParams, type WorkflowControllerStatusResult, type WorkflowControllerStatusToolArgs, type WorkflowEventsResult, type WorkflowEventsToolArgs, type WorkflowGateOperation, type WorkflowGateParams, type WorkflowGateResult, type WorkflowGateToolArgs, type WorkflowHeartbeatParams, type WorkflowInspectResult, type WorkflowInspectToolArgs, type WorkflowReadyResult, type WorkflowReadyToolArgs, type WorkflowStatusResult, type WorkflowStatusToolArgs, type WorkflowWaitResult, type WorkflowWaitToolArgs, answerPermissionTool, askTool, brokerReceiveTool, brokerReplyTool, cancelTool, createRunSnapshot, createWorkflowCompleteTool, createWorkflowControllerStatusTool, createWorkflowEventsTool, createWorkflowGateTool, createWorkflowInspectTool, createWorkflowReadyTool, createWorkflowStatusTool, createWorkflowWaitTool, dial, evaluateThinkingPolicy, eventsTool, extractEventText, findAvenorBinary, followUpTool, getInstallDir, getVersion, inspectTool, installerBinaryPath, isThinkingLevel, killTool, normalizeRunEvent, observeRun, peersTool, reduceRunSnapshot, resultTool, shutdownTool, socketsRoot, spawnTool, statusTool, validateSpawnSelection, validateThinking, validateThinkingForBackend, validateThinkingForBackendResume, workflowCompleteTool, workflowControllerStatusTool, workflowEventsTool, workflowGateTool, workflowInspectTool, workflowReadyTool, workflowStatusTool, workflowWaitTool };
+//#region src/tools/workflow-cancel.d.ts
+interface WorkflowCancelArgs {
+  workflow_id: string;
+  actor: string;
+  reason: string;
+  supervisorId?: string;
+}
+type WorkflowCancelResult = Record<string, unknown>;
+/**
+ * Cancel a workflow. The manager validates the actor before the reason, so the
+ * handler checks them in the same order and forwards all three unchanged.
+ */
+declare function createWorkflowCancelTool(getSupervisorClient: GetSupervisorClient): (args: WorkflowCancelArgs) => Promise<WorkflowCancelResult>;
+declare const workflowCancelTool: (args: WorkflowCancelArgs) => Promise<WorkflowCancelResult>;
+//#endregion
+export { type AskClaims, type BrokerReceiveArgs, type BrokerReceiveResult, type ChildBroker, type Client, DEFAULT_RUN_REDUCER_LIMITS, type Event, type ExecutionIdentity, ForeignPeerError, type HistoryOptions, type HistoryResult, type InboundAsk, type InspectResult, type KillResult, type KillToolArgs, MAX_FINAL_OUTPUT_RUNES, MAX_WAIT_MS, MESSAGE_OUTCOMES, type MessageCallerKind, type MessageClient, type MessageInput, type MessageOutcome, type MessageProvider, type MessageSurface, type NormalizedRunEvent, type ObserveRunOptions, type OwnerAttachOptions, OwnerAuthError, OwnerRecordMissingError, type PeerRecord, type PeersInput, type PeersProviderResult, type PeersResult, type PeersRouterResult, type PeersToolArgs, type PendingAsk, type ProviderResult, type Resolution, type ResultResult, type ResultToolArgs, RpcError, type RunChunkRole, type RunFacts, type RunIdentity, type RunInfo, type RunObserver, type RunObserverClient, type RunPermissionOption, type RunPermissionSummary, RunReducer, type RunReducerLimits, type RunSnapshot, type RunSnapshotSeed, type RunToolState, type RunToolSummary, type RunTranscriptEntry, type SpawnMetadata, type SpawnParams, type SpawnResult, type SpawnSelectionInput, type SpawnToolArgs, type SpawnToolResult, StaleOwnerRecordError, type StatusListResult, type StatusResult, type StatusToolArgs, type StatusView, type SubscribeOptions, Supervisor, type SupervisorClientOptions, type SupervisorOptions, THINKING_LEVELS, type ThinkingLevel, type ThinkingOutcome, ToolError, type WorkflowCancelArgs, type WorkflowCancelResult, type WorkflowCompleteParams, type WorkflowCompleteResult, type WorkflowCompleteToolArgs, type WorkflowControllerCreateParams, type WorkflowControllerStatusResult, type WorkflowControllerStatusToolArgs, type WorkflowEventsResult, type WorkflowEventsToolArgs, type WorkflowGateOperation, type WorkflowGateParams, type WorkflowGateResult, type WorkflowGateToolArgs, type WorkflowHeartbeatParams, type WorkflowInspectResult, type WorkflowInspectToolArgs, type WorkflowReadyResult, type WorkflowReadyToolArgs, type WorkflowStatusResult, type WorkflowStatusToolArgs, type WorkflowWaitResult, type WorkflowWaitToolArgs, answerPermissionTool, assertMessageInput, assertPeersInput, attachOwner, boundFinalOutput, brokerReceiveTool, createChildMessageProvider, createHostMessageProvider, createMessageTool, createPeersTool, createRunSnapshot, createWorkflowCancelTool, createWorkflowCompleteTool, createWorkflowControllerStatusTool, createWorkflowEventsTool, createWorkflowGateTool, createWorkflowInspectTool, createWorkflowReadyTool, createWorkflowStatusTool, createWorkflowWaitTool, dial, evaluateThinkingPolicy, eventsTool, executeMessage, executePeers, extractEventText, extractReplyMessage, extractTurnText, findAvenorBinary, getInstallDir, getSupervisorClient, getVersion, inspectTool, installAskClaims, installerBinaryPath, isGenerationMismatchError, isThinkingLevel, killTool, messageTool, newMsgID, normalizeAskTimeoutMs, normalizeRunEvent, normalizeTurnStopReason, observeRun, peersDetails, peersTool, quote, quoteList, reduceRunSnapshot, renderAskFailure, renderLast, renderOutcome, renderPeerList, repair, resultOutput, resultTool, sanitize, shutdownTool, socketsRoot, spawnTool, statusTool, validateSpawnSelection, validateThinking, validateThinkingForBackend, validateThinkingForBackendResume, workflowCancelTool, workflowCompleteTool, workflowControllerStatusTool, workflowEventsTool, workflowGateTool, workflowInspectTool, workflowReadyTool, workflowStatusTool, workflowWaitTool };