@agen-ai/agent-orchestration 0.0.0-stage → 0.4.0

package/dist/tasks/types.d.ts

@@ -0,0 +1,192 @@
+import type { AgentFailureCategory, AgentRecoveryHint, AgentTurnInputContent } from "@agen-ai/agent-protocol";
+import type { DelegationTargetReference } from "../catalog/types.js";
+import type { DelegationCommitReceipt } from "../store/types.js";
+export type DelegationPersistence = "volatile" | "durable";
+export type DelegationTaskState = "active" | "settled" | "recovery_required" | "retired";
+export type DelegationRunPhase = "queued" | "preparing" | "running" | "waiting" | "settled";
+export type DelegationCompletionPolicy = "collect" | "next_turn" | "automatic";
+export interface DelegationParentScope {
+    readonly parentId: string;
+    readonly scopeId: string;
+    readonly revision: number;
+}
+export interface DelegationOwnerToken {
+    readonly storeId: string;
+    readonly epoch: number;
+    readonly nonce: string;
+}
+export interface DelegationPolicyCeiling {
+    readonly ceilingId: string;
+    readonly origin: DelegationParentScope;
+    readonly targets: readonly DelegationTargetReference[];
+}
+export interface DelegationTaskRecord {
+    readonly storeId: string;
+    readonly taskId: string;
+    readonly parent: DelegationParentScope;
+    readonly ancestorTaskId?: string;
+    readonly depth: number;
+    readonly policyCeilingRef: string;
+    readonly completionPolicy: DelegationCompletionPolicy;
+    readonly state: DelegationTaskState;
+    readonly revision: number;
+    readonly latestRunId: string;
+    readonly runCount: number;
+    readonly createdAt: string;
+    readonly retiredAt?: string;
+    readonly retirement?: Readonly<{
+        operationId: string;
+        inputDigest: string;
+        reason: string;
+    }>;
+}
+export interface DelegationHistoricalRequest {
+    readonly requestId: string;
+    readonly requestKind: "approval" | "elicitation";
+    readonly openedAt: string;
+    readonly expiresAt?: string;
+    readonly state: "waiting" | "resolution_intended" | "resolved" | "unavailable";
+}
+export interface DelegationResultReference {
+    readonly id: string;
+    readonly kind: "artifact" | "host_result";
+    readonly digest?: string;
+}
+export interface DelegationResultSummary {
+    readonly text: string;
+    readonly truncated: boolean;
+    readonly references: readonly DelegationResultReference[];
+}
+export interface DelegationPublicFailure {
+    readonly category: AgentFailureCategory;
+    readonly code: string;
+    readonly message: string;
+    readonly recovery: Exclude<AgentRecoveryHint, {
+        kind: "wait_for_quota";
+    }> | Readonly<{
+        kind: "wait_for_quota";
+    }>;
+}
+export type DelegationRunOutcome = Readonly<{
+    kind: "succeeded";
+    result: DelegationResultSummary;
+}> | Readonly<{
+    kind: "failed";
+    error: DelegationPublicFailure;
+}> | Readonly<{
+    kind: "canceled";
+    confirmation: "not_dispatched" | "provider_terminal";
+}> | Readonly<{
+    kind: "recovery_required";
+    reason: "executor_lost" | "dispatch_uncertain" | "request_executor_lost" | "steering_uncertain" | "cancellation_uncertain" | "storage_failed";
+}>;
+export interface DelegationRunRecord {
+    readonly taskId: string;
+    readonly runId: string;
+    readonly ordinal: number;
+    readonly previousRunId?: string;
+    readonly continuationMode?: "next_turn" | "follow_up";
+    readonly admissionOperationId: string;
+    readonly admittedTarget: DelegationTargetReference;
+    readonly appliedTarget?: DelegationTargetReference;
+    readonly admittedPolicyRevision: number;
+    readonly admittedOriginPolicyRevision: number;
+    readonly input: AgentTurnInputContent;
+    readonly ownerEpoch: number;
+    readonly phase: DelegationRunPhase;
+    readonly revision: number;
+    readonly createdAt: string;
+    readonly deadlineAt: string;
+    readonly queuedStartDeadlineAt: string;
+    readonly dispatch: "none" | "intended" | "delegated";
+    readonly preparation: "none" | "intended" | "completed" | "uncertain";
+    readonly cancelRequested: boolean;
+    readonly pendingRequest?: DelegationHistoricalRequest;
+    readonly outcome?: DelegationRunOutcome;
+    readonly settledAt?: string;
+    readonly observationIndex: number;
+    readonly observationCount: number;
+    readonly observationBytes: number;
+    readonly omittedObservations: number;
+    readonly lastObservationDigest?: string;
+    readonly ordinaryOperationCount: number;
+    readonly recoveryReason?: Extract<DelegationRunOutcome, {
+        kind: "recovery_required";
+    }>["reason"];
+    readonly finalization?: Readonly<{
+        operationId: string;
+        inputDigest: string;
+        taskRevision: number;
+        runRevision: number;
+    }>;
+}
+export interface DelegationTaskObservation {
+    readonly storeId: string;
+    readonly taskId: string;
+    readonly runId: string;
+    readonly index: number;
+    readonly at: string;
+    readonly kind: "state" | "text" | "request" | "omitted";
+    readonly phase?: DelegationRunPhase;
+    readonly text?: string;
+    readonly request?: DelegationHistoricalRequest;
+    readonly omitted?: number;
+}
+export interface DelegationObservationGap {
+    readonly kind: "gap";
+    readonly storeId: string;
+    readonly taskId: string;
+    readonly runId: string;
+    readonly cursor: string;
+}
+export type DelegationObservedTaskObservation = DelegationTaskObservation & Readonly<{
+    cursor: string;
+}>;
+export interface DelegationCompletionEnvelope {
+    readonly storeId: string;
+    readonly notificationId: string;
+    readonly taskId: string;
+    readonly runId: string;
+    readonly parent: DelegationParentScope;
+    readonly policy: DelegationCompletionPolicy;
+    readonly settledAt: string;
+    readonly expiresAt: string;
+    readonly outcome: DelegationRunOutcome;
+}
+export interface DelegationDeliveryCommitRecord {
+    readonly operationId: string;
+    readonly inputDigest: string;
+    readonly commandDigest: string;
+    readonly attemptId: string;
+    readonly attempt: number;
+    readonly ownerEpoch: number;
+    readonly receipt: DelegationCommitReceipt;
+}
+export interface DelegationNotificationRecord {
+    readonly envelope: DelegationCompletionEnvelope;
+    readonly revision: number;
+    readonly state: "collectible" | "pending" | "claimed" | "accepted" | "rejected" | "expired" | "dismissed";
+    readonly claim?: Readonly<{
+        ownerEpoch: number;
+        attemptId: string;
+    }>;
+    readonly attempts: number;
+    readonly retryAt?: string;
+    readonly inboxId?: string;
+    readonly acceptedAt?: string;
+    readonly reason?: string;
+    readonly delivery?: Readonly<{
+        claim?: DelegationDeliveryCommitRecord;
+        receipt?: DelegationDeliveryCommitRecord;
+    }>;
+}
+export interface DelegationPage<Value> {
+    readonly items: readonly Value[];
+    readonly cursor?: string;
+}
+export interface DelegationTaskView {
+    readonly task: DelegationTaskRecord;
+    readonly runs: DelegationPage<DelegationRunSummary>;
+}
+export type DelegationRunSummary = Omit<DelegationRunRecord, "input">;
+//# sourceMappingURL=types.d.ts.map

package/dist/tools/create.d.ts

@@ -0,0 +1,4 @@
+import { type AgentSessionHostBinding } from "@agen-ai/agent-runtime";
+import type { CreateDelegationHostBindingOptions } from "./types.js";
+export declare function createDelegationHostBinding(options: CreateDelegationHostBindingOptions): Promise<AgentSessionHostBinding | undefined>;
+//# sourceMappingURL=create.d.ts.map

package/dist/tools/create.js

@@ -0,0 +1,69 @@
+import {
+  validateAgentHostToolInvocation,
+  validateAgentHostToolResult,
+  validateAgentSessionHostBinding
+} from "@agen-ai/agent-runtime";
+import { createDelegationId } from "../shared/identity.js";
+import { delegationToolError, sanitizeDelegationToolError } from "./errors.js";
+import { delegationGuidance, validateNativeToolNames } from "./guidance.js";
+import { handleDelegationTool } from "./handlers.js";
+import { delegationToolDefinitions } from "./schemas.js";
+async function createDelegationHostBinding(options) {
+  const client = options.client;
+  const snapshot = await client.bindingSnapshot();
+  if (!snapshot.enabled) return void 0;
+  const nativeTools = validateNativeToolNames(options.nativeToolNames);
+  const lifetime = new AbortController();
+  const active = /* @__PURE__ */ new Map();
+  let releasePromise;
+  const invoke = (raw) => {
+    if (lifetime.signal.aborted) return Promise.resolve(delegationToolError("tool_unavailable", "This managed tool binding has been released."));
+    let invocation;
+    try {
+      invocation = validateAgentHostToolInvocation({ binding, invocation: raw });
+    } catch {
+      return Promise.resolve(delegationToolError("invalid_tool_input", "The managed tool invocation or arguments are invalid."));
+    }
+    if (invocation.signal?.aborted) return Promise.resolve(delegationToolError("operation_aborted", "The tool invocation was canceled before dispatch."));
+    if (active.has(invocation.invocationId)) return Promise.resolve(delegationToolError("invalid_tool_input", "This tool invocation ID is already active."));
+    if (active.size >= 16) return Promise.resolve(delegationToolError("capacity_exceeded", "This managed binding has reached its callback limit."));
+    const signal = invocation.signal === void 0 ? lifetime.signal : AbortSignal.any([lifetime.signal, invocation.signal]);
+    const work = Promise.resolve().then(async () => {
+      let value;
+      try {
+        value = await handleDelegationTool(client, snapshot, { ...invocation, signal });
+      } catch (error) {
+        if (signal.aborted && error === signal.reason) {
+          return delegationToolError("operation_aborted", "The tool invocation was canceled. Any admitted child work remains independent.");
+        }
+        return sanitizeDelegationToolError(error);
+      }
+      try {
+        return validateAgentHostToolResult({ kind: "success", value });
+      } catch {
+        return delegationToolError("internal_error", "The managed action did not produce a portable result. Inspect retained state before retrying.");
+      }
+    }).finally(() => {
+      active.delete(invocation.invocationId);
+    });
+    active.set(invocation.invocationId, work);
+    return work;
+  };
+  const binding = validateAgentSessionHostBinding({ binding: {
+    bindingId: options.bindingId ?? createDelegationId(),
+    tools: delegationToolDefinitions(snapshot),
+    instructions: { placement: options.instructionPlacement ?? "tool_context", text: delegationGuidance(snapshot, nativeTools) },
+    invoke,
+    release() {
+      if (!releasePromise) {
+        lifetime.abort(new DOMException("The managed tool binding was released.", "AbortError"));
+        releasePromise = Promise.allSettled(active.values()).then(() => void 0);
+      }
+      return releasePromise;
+    }
+  }, support: { kind: "supported", toolTransport: "callback", instructionPlacements: ["system", "developer", "tool_context"] } });
+  return binding;
+}
+export {
+  createDelegationHostBinding
+};

package/dist/tools/errors.d.ts

@@ -0,0 +1,4 @@
+import type { AgentHostToolResult } from "@agen-ai/agent-runtime";
+export declare function delegationToolError(code: string, message: string): AgentHostToolResult;
+export declare function sanitizeDelegationToolError(error: unknown): AgentHostToolResult;
+//# sourceMappingURL=errors.d.ts.map

package/dist/tools/errors.js

@@ -0,0 +1,35 @@
+import { AgentProtocolValidationError } from "@agen-ai/agent-protocol";
+import { DelegationValidationError } from "../shared/errors.js";
+import { DelegationOperationError } from "../shared/operational-errors.js";
+const messages = {
+  delegation_disabled: "Managed delegation is currently disabled.",
+  policy_denied: "Current authority does not permit this managed action.",
+  target_unavailable: "The selected managed target is unavailable.",
+  stale_target: "The exact target or source revision is stale. Refresh delegation_targets.",
+  unsupported_operation: "This managed operation or completion policy is unsupported.",
+  capacity_exceeded: "This managed action exceeds a configured capacity or content limit.",
+  operation_conflict: "The operation ID conflicts with retained work. Retry only the canonical accepted ID with identical arguments.",
+  stale_revision: "The policy, scope, or page revision changed. Refresh the relevant managed view.",
+  owner_lost: "The managed executor is unavailable. Inspect retained task history.",
+  request_unavailable: "The requested managed task or request is unavailable to this parent.",
+  delivery_uncertain: "Delivery is uncertain. Inspect retained task state and do not automatically replay.",
+  recovery_required: "The managed task requires host recovery. Do not replay uncertain work.",
+  store_failed: "Managed storage is unavailable. Retained work may require host recovery."
+};
+function delegationToolError(code, message) {
+  return Object.freeze({ kind: "error", error: Object.freeze({ code, message, category: "unknown", recovery: Object.freeze({ kind: "unknown" }) }) });
+}
+function sanitizeDelegationToolError(error) {
+  if (error instanceof DelegationOperationError) return delegationToolError(error.code, messages[error.code]);
+  if (error instanceof DelegationValidationError || error instanceof AgentProtocolValidationError) {
+    return delegationToolError("invalid_tool_input", "The managed tool arguments are invalid.");
+  }
+  if (error instanceof DOMException && error.name === "AbortError") {
+    return delegationToolError("operation_aborted", "The tool invocation was canceled. Any admitted child work remains independent.");
+  }
+  return delegationToolError("internal_error", "The managed tool could not return a result. Inspect retained state before retrying an action.");
+}
+export {
+  delegationToolError,
+  sanitizeDelegationToolError
+};

package/dist/tools/guidance.d.ts

@@ -0,0 +1,4 @@
+import type { DelegationBindingSnapshot } from "../coordinator/types.js";
+export declare function validateNativeToolNames(input: readonly string[] | undefined): readonly string[];
+export declare function delegationGuidance(snapshot: DelegationBindingSnapshot, nativeTools: readonly string[]): string;
+//# sourceMappingURL=guidance.d.ts.map

package/dist/tools/guidance.js

@@ -0,0 +1,28 @@
+import { DELEGATION_TOOL_NAMES } from "./schemas.js";
+function validateNativeToolNames(input) {
+  if (input === void 0) return [];
+  if (!Array.isArray(input) || input.length > 32) throw new TypeError("Native tool names require a bounded array.");
+  const names = [...input];
+  if (new Set(names).size !== names.length || names.some((name) => typeof name !== "string" || !/^[A-Za-z][A-Za-z0-9_]{0,63}$/u.test(name) || DELEGATION_TOOL_NAMES.includes(name))) {
+    throw new TypeError("Native tool names must be bounded, unique, and distinct from managed tool names.");
+  }
+  return names;
+}
+function delegationGuidance(snapshot, nativeTools) {
+  return [
+    "Managed delegation is optional and governed by current host and user policy. These instructions do not grant execution or approval authority.",
+    "Use delegation_targets to obtain currently permitted exact target references and policyRevision. An emptyReason of delegation_disabled means delegation is disabled; no_permitted_targets means it is enabled but current policy permits no targets. Unknown semantics remain unknown; do not infer capability from a label. Fast execution requires explicit selection.",
+    "Use delegate_task for independent child work. Required operationId is a caller-chosen UUID: choose it once for an action, retain it, and reuse it only with identical arguments for an exact retry. Never invent a fresh operation ID to retry an uncertain result.",
+    `Task text is bounded to ${snapshot.limits.maxInputBytes} serialized input bytes and ${snapshot.limits.maxInputTextCharacters} characters in total; prompt, message, and context each allow at most 16 KiB UTF-8. Context is ordinary task input.`,
+    `Completion defaults to collect. Available completion policies: ${snapshot.completionPolicies.join(", ")}. Collect results with task_status; next_turn and automatic, when available, only enqueue through the host inbox and do not prove parent consumption or start a parent model turn.`,
+    `task_status may wait at most ${snapshot.limits.maxWaitMs} ms. A timeout or canceled tool invocation does not cancel the child. Follow returned cursors for complete target and run history; a truncated result summary is explicitly marked and references remain available.`,
+    "task_send steer applies only to a supported active turn and never falls back to a queue. next_turn reserves a later run; follow_up requires a definitive settled, safely resumable conversation. delivered, queued, rejected, and delivery_uncertain have distinct meanings. Inspect delivery_uncertain or recovery_required; do not replay uncertain work.",
+    "A waiting approval or elicitation requires the host's live request channel. These tools cannot approve, authenticate, choose executable commands, change policy, or resolve a request handle.",
+    "task_cancel requests interruption. requested does not mean stopped; confirmed requires terminal evidence, and recovery_required means stop is unproven. Retain the canonical accepted cancellation operation ID for retries. Existing status and cancellation access can remain available after delegation is disabled.",
+    nativeTools.length === 0 ? "No native collaboration tool names were certified for this binding. These managed tools make no claim about native tool availability." : `The host certifies these independent native tools in this session: ${nativeTools.join(", ")}. Use their native descriptions for native collaboration; managed tools do not replace or alter them.`
+  ].join("\n\n");
+}
+export {
+  delegationGuidance,
+  validateNativeToolNames
+};

package/dist/tools/handlers.d.ts

@@ -0,0 +1,4 @@
+import type { AgentHostToolInvocation } from "@agen-ai/agent-runtime";
+import type { DelegationBindingSnapshot, DelegationClient } from "../coordinator/types.js";
+export declare function handleDelegationTool(client: DelegationClient, snapshot: DelegationBindingSnapshot, invocation: AgentHostToolInvocation): Promise<unknown>;
+//# sourceMappingURL=handlers.d.ts.map

package/dist/tools/handlers.js

@@ -0,0 +1,84 @@
+import { AGENT_PROTOCOL_TEXT_MAX_LENGTH } from "@agen-ai/agent-protocol";
+import { failDelegation } from "../shared/operational-errors.js";
+import { projectTargetPage, projectTaskPage } from "./projection.js";
+function taskContent(text, context) {
+  for (const field of [text, ...context === void 0 ? [] : [context]]) {
+    if (new TextEncoder().encode(field).byteLength > 16384) {
+      failDelegation("capacity_exceeded", "A task text field exceeds its UTF-8 byte limit.");
+    }
+  }
+  const contents = context === void 0 ? text : `${text}
+
+Context:
+${context}`;
+  const parts = [];
+  let position = 0;
+  while (position < contents.length) {
+    let end = Math.min(position + AGENT_PROTOCOL_TEXT_MAX_LENGTH, contents.length);
+    if (end < contents.length && /[\uD800-\uDBFF]/u.test(contents[end - 1])) end--;
+    parts.push({ type: "text", text: contents.slice(position, end) });
+    position = end;
+  }
+  return { parts };
+}
+async function handleDelegationTool(client, snapshot, invocation) {
+  const args = invocation.arguments;
+  invocation.signal?.throwIfAborted();
+  switch (invocation.toolName) {
+    case "delegation_targets": {
+      const input = args;
+      return projectTargetPage(client, {
+        ...input.cursor === void 0 ? {} : { cursor: input.cursor },
+        limit: input.limit ?? Math.min(20, snapshot.limits.maxPageRecords)
+      });
+    }
+    case "delegate_task": {
+      const input = args;
+      return client.spawn({
+        operationId: input.operationId,
+        target: input.target,
+        expectedPolicyRevision: input.expectedPolicyRevision,
+        input: taskContent(input.prompt, input.context),
+        ...input.completionPolicy === void 0 ? {} : { completionPolicy: input.completionPolicy },
+        ...input.timeoutMs === void 0 ? {} : { timeoutMs: input.timeoutMs }
+      });
+    }
+    case "task_status": {
+      const input = args;
+      let waitStatus;
+      if (input.waitMs !== void 0 && input.waitMs > 0) {
+        waitStatus = (await client.wait({
+          taskId: input.taskId,
+          timeoutMs: input.waitMs,
+          ...invocation.signal === void 0 ? {} : { signal: invocation.signal }
+        })).status;
+        invocation.signal?.throwIfAborted();
+      }
+      return projectTaskPage(client, {
+        taskId: input.taskId,
+        ...input.runsCursor === void 0 ? {} : { runsCursor: input.runsCursor },
+        limit: input.limit ?? Math.min(20, snapshot.limits.maxPageRecords)
+      }, waitStatus);
+    }
+    case "task_send": {
+      const input = args;
+      return client.send({
+        operationId: input.operationId,
+        taskId: input.taskId,
+        mode: input.mode,
+        target: input.target,
+        expectedPolicyRevision: input.expectedPolicyRevision,
+        input: taskContent(input.message, input.context)
+      });
+    }
+    case "task_cancel": {
+      const input = args;
+      return client.cancel({ operationId: input.operationId, taskId: input.taskId });
+    }
+    default:
+      return failDelegation("unsupported_operation", "The managed tool is unavailable.");
+  }
+}
+export {
+  handleDelegationTool
+};

package/dist/tools/projection.d.ts

@@ -0,0 +1,13 @@
+import type { DelegationClient } from "../coordinator/types.js";
+import type { DelegationToolTargetPage, DelegationToolTaskStatus } from "./types.js";
+export declare const DELEGATION_TOOL_PAGE_BYTES = 24576;
+export declare function projectTargetPage(client: DelegationClient, input: Readonly<{
+    cursor?: string;
+    limit: number;
+}>): Promise<DelegationToolTargetPage>;
+export declare function projectTaskPage(client: DelegationClient, input: Readonly<{
+    taskId: string;
+    runsCursor?: string;
+    limit: number;
+}>, waitStatus?: "settled" | "timeout"): Promise<DelegationToolTaskStatus>;
+//# sourceMappingURL=projection.d.ts.map

package/dist/tools/projection.js

@@ -0,0 +1,72 @@
+import { agentProtocolSerializedJsonBytes } from "@agen-ai/agent-protocol";
+import { failDelegation } from "../shared/operational-errors.js";
+const DELEGATION_TOOL_PAGE_BYTES = 24576;
+function targetProjection(target) {
+  const { reference, providerKey, modelId, label, options, reasoning, executionMode, limitations } = target;
+  return { reference, providerKey, modelId, label, options, reasoning, executionMode, limitations };
+}
+function runProjection(run) {
+  const { runId, ordinal, phase, revision, dispatch, cancelRequested, createdAt, deadlineAt } = run;
+  const pending = run.pendingRequest;
+  return {
+    runId,
+    ordinal,
+    phase,
+    revision,
+    dispatch,
+    cancelRequested,
+    createdAt,
+    deadlineAt,
+    target: run.admittedTarget,
+    ...run.previousRunId === void 0 ? {} : { previousRunId: run.previousRunId },
+    ...run.continuationMode === void 0 ? {} : { continuationMode: run.continuationMode },
+    ...run.outcome === void 0 ? {} : { outcome: run.outcome },
+    ...run.settledAt === void 0 ? {} : { settledAt: run.settledAt },
+    ...pending === void 0 ? {} : { pendingRequest: {
+      requestKind: pending.requestKind,
+      state: pending.state,
+      openedAt: pending.openedAt,
+      ...pending.expiresAt === void 0 ? {} : { expiresAt: pending.expiresAt }
+    } }
+  };
+}
+function taskProjection(view, waitStatus) {
+  const { storeId, taskId, state, revision, latestRunId, runCount, completionPolicy } = view.task;
+  return {
+    task: { storeId, taskId, state, revision, latestRunId, runCount, completionPolicy },
+    runs: { items: view.runs.items.map(runProjection), ...view.runs.cursor === void 0 ? {} : { cursor: view.runs.cursor } },
+    ...waitStatus === void 0 ? {} : { waitStatus }
+  };
+}
+async function boundedPage(limit, read) {
+  let requested = limit;
+  for (; ; ) {
+    const page = await read(requested);
+    if (agentProtocolSerializedJsonBytes(page) <= DELEGATION_TOOL_PAGE_BYTES) return page;
+    if (requested === 1) return failDelegation("capacity_exceeded", "One projected record exceeds the tool result limit.");
+    requested = Math.max(1, Math.floor(requested / 2));
+  }
+}
+function projectTargetPage(client, input) {
+  return boundedPage(input.limit, async (limit) => {
+    const page = await client.targets({ ...input.cursor === void 0 ? {} : { cursor: input.cursor }, limit });
+    return {
+      policyRevision: page.policyRevision,
+      targets: page.targets.map(targetProjection),
+      ...page.cursor === void 0 ? {} : { cursor: page.cursor },
+      ...page.emptyReason === void 0 ? {} : { emptyReason: page.emptyReason }
+    };
+  });
+}
+function projectTaskPage(client, input, waitStatus) {
+  return boundedPage(input.limit, async (limit) => taskProjection(await client.inspect({
+    taskId: input.taskId,
+    ...input.runsCursor === void 0 ? {} : { runsCursor: input.runsCursor },
+    limit
+  }), waitStatus));
+}
+export {
+  DELEGATION_TOOL_PAGE_BYTES,
+  projectTargetPage,
+  projectTaskPage
+};

package/dist/tools/schemas.d.ts

@@ -0,0 +1,6 @@
+import type { AgentHostToolDefinition } from "@agen-ai/agent-runtime";
+import type { DelegationBindingSnapshot } from "../coordinator/types.js";
+export declare const DELEGATION_TOOL_NAMES: readonly ["delegation_targets", "delegate_task", "task_status", "task_send", "task_cancel"];
+export type DelegationToolName = typeof DELEGATION_TOOL_NAMES[number];
+export declare function delegationToolDefinitions(snapshot: DelegationBindingSnapshot): readonly AgentHostToolDefinition[];
+//# sourceMappingURL=schemas.d.ts.map

package/dist/tools/schemas.js

@@ -0,0 +1,93 @@
+const DELEGATION_TOOL_NAMES = ["delegation_targets", "delegate_task", "task_status", "task_send", "task_cancel"];
+const uuid = {
+  type: "string",
+  minLength: 36,
+  maxLength: 36,
+  description: "A UUID. For operations, choose it once and reuse it only for the exact same action and arguments."
+};
+const revision = { type: "integer", minimum: 1, maximum: Number.MAX_SAFE_INTEGER };
+const identifier = { type: "string", minLength: 1, maxLength: 256 };
+const cursor = { type: "string", minLength: 1, maxLength: 512 };
+const target = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    catalogId: identifier,
+    catalogRevision: revision,
+    targetId: identifier,
+    targetRevision: revision,
+    sourceId: identifier,
+    sourceRevision: revision
+  },
+  required: ["catalogId", "catalogRevision", "targetId", "targetRevision", "sourceId", "sourceRevision"]
+};
+function schema(properties, required = []) {
+  return { $schema: "https://json-schema.org/draft/2020-12/schema", type: "object", properties, required, additionalProperties: false };
+}
+function delegationToolDefinitions(snapshot) {
+  const text = {
+    type: "string",
+    minLength: 1,
+    maxLength: snapshot.limits.maxInputTextCharacters,
+    description: "Plain text, at most 16 KiB UTF-8 per field. Combined task content must fit the configured input byte and character limits."
+  };
+  const limit = { type: "integer", minimum: 1, maximum: snapshot.limits.maxPageRecords };
+  return [
+    {
+      name: "delegation_targets",
+      description: "List currently permitted managed targets and the policy revision. An emptyReason distinguishes delegation_disabled from no_permitted_targets. Follow the returned cursor for more choices; preserve the exact target reference for admission.",
+      inputSchema: schema({ cursor, limit })
+    },
+    {
+      name: "delegate_task",
+      description: "Admit one managed child task using an exact listed target and current policy revision. A queued receipt is admission only. Supply a stable UUID operationId; identical retries never create another task.",
+      inputSchema: schema(
+        {
+          operationId: uuid,
+          target,
+          expectedPolicyRevision: revision,
+          prompt: text,
+          context: text,
+          completionPolicy: { type: "string", enum: snapshot.completionPolicies, maxLength: 9 },
+          timeoutMs: { type: "integer", minimum: 1, maximum: snapshot.limits.runTimeoutMs }
+        },
+        ["operationId", "target", "expectedPolicyRevision", "prompt"]
+      )
+    },
+    {
+      name: "task_status",
+      description: "Inspect bounded managed run history and results. Optionally wait for a bounded interval; a wait timeout does not cancel work. Follow runs.cursor without discarding earlier run outcomes. Waiting approval or elicitation belongs to the host.",
+      inputSchema: schema({
+        taskId: uuid,
+        runsCursor: cursor,
+        limit,
+        waitMs: { type: "integer", minimum: 0, maximum: snapshot.limits.maxWaitMs }
+      }, ["taskId"])
+    },
+    {
+      name: "task_send",
+      description: "Send explicit steer, next_turn, or follow_up input with a stable UUID operationId. Steer never falls back to a queue. next_turn reserves a later run; follow_up requires a safe settled continuation. delivery_uncertain requires inspection, not automatic replay.",
+      inputSchema: schema(
+        {
+          operationId: uuid,
+          taskId: uuid,
+          mode: { type: "string", enum: ["steer", "next_turn", "follow_up"], maxLength: 9 },
+          target,
+          expectedPolicyRevision: revision,
+          message: text,
+          context: text
+        },
+        ["operationId", "taskId", "mode", "target", "expectedPolicyRevision", "message"]
+      )
+    },
+    {
+      name: "task_cancel",
+      description: "Request cancellation using a stable UUID operationId. requested does not mean stopped; inspect until confirmed or recovery_required. Retry the canonical accepted operation ID. Cancellation remains available after managed delegation is disabled.",
+      inputSchema: schema({ operationId: uuid, taskId: uuid }, ["operationId", "taskId"])
+    }
+  ];
+}
+export {
+  DELEGATION_TOOL_NAMES,
+  delegationToolDefinitions
+};

package/dist/tools/types.d.ts

@@ -0,0 +1,28 @@
+import type { AgentHostInstructionPlacement } from "@agen-ai/agent-runtime";
+import type { DelegationClient } from "../coordinator/types.js";
+import type { DelegationTarget } from "../catalog/types.js";
+import type { DelegationHistoricalRequest, DelegationPage, DelegationRunSummary, DelegationTaskRecord } from "../tasks/types.js";
+export interface CreateDelegationHostBindingOptions {
+    readonly client: DelegationClient;
+    readonly bindingId?: string;
+    readonly instructionPlacement?: AgentHostInstructionPlacement;
+    /** The host certifies that these native tools exist in this exact session. */
+    readonly nativeToolNames?: readonly string[];
+}
+export type DelegationToolTarget = Pick<DelegationTarget, "reference" | "providerKey" | "modelId" | "label" | "options" | "reasoning" | "executionMode" | "limitations">;
+export interface DelegationToolTargetPage {
+    readonly policyRevision: number;
+    readonly targets: readonly DelegationToolTarget[];
+    readonly cursor?: string;
+    readonly emptyReason?: "delegation_disabled" | "no_permitted_targets";
+}
+export type DelegationToolRunSummary = Pick<DelegationRunSummary, "runId" | "ordinal" | "previousRunId" | "continuationMode" | "phase" | "revision" | "dispatch" | "cancelRequested" | "outcome" | "createdAt" | "deadlineAt" | "settledAt"> & Readonly<{
+    target: DelegationTarget["reference"];
+    pendingRequest?: Omit<DelegationHistoricalRequest, "requestId">;
+}>;
+export interface DelegationToolTaskStatus {
+    readonly task: Pick<DelegationTaskRecord, "storeId" | "taskId" | "state" | "revision" | "latestRunId" | "runCount" | "completionPolicy">;
+    readonly runs: DelegationPage<DelegationToolRunSummary>;
+    readonly waitStatus?: "settled" | "timeout";
+}
+//# sourceMappingURL=types.d.ts.map