@linnlabs/linnkit 0.8.0

package/dist/contracts.js

@@ -0,0 +1,1214 @@
+import { z } from 'zod';
+
+// src/contracts/messages.ts
+var ProviderReasoningDetails = z.array(z.unknown());
+var ToolCallExtraContent = z.object({
+  google: z.object({
+    thought_signature: z.string().optional()
+  }).passthrough().optional()
+}).passthrough();
+var ToolCallWire = z.object({
+  id: z.string(),
+  type: z.literal("function"),
+  function: z.object({
+    name: z.string(),
+    arguments: z.string()
+  }),
+  extra_content: ToolCallExtraContent.optional()
+}).passthrough();
+var HistorySummaryMeta = z.object({
+  messageType: z.literal("summary"),
+  originalMessageCount: z.number().int().positive(),
+  compressionRatio: z.number().min(0).max(1).optional(),
+  includedOldSummary: z.boolean(),
+  replacedMessageIds: z.array(z.string()),
+  summarySeq: z.number().int().nonnegative()
+});
+var ToolCallsMeta = z.object({
+  tool_calls: z.array(ToolCallWire),
+  reasoning_details: ProviderReasoningDetails.optional()
+});
+var ToolOutputMeta = z.object({
+  tool_name: z.string(),
+  args: z.record(z.unknown()).optional(),
+  tool_call_id: z.string()
+});
+var ImageInfoMeta = z.object({
+  url: z.string().optional(),
+  width: z.number().int().positive().optional(),
+  height: z.number().int().positive().optional(),
+  format: z.string().optional(),
+  size: z.number().int().nonnegative().optional()
+});
+var TaskTrackingMeta = z.object({
+  taskType: z.string().optional(),
+  taskId: z.string().optional(),
+  taskStatus: z.enum(["requested", "in_progress", "completed", "failed"]).optional(),
+  taskTrackingInfo: z.object({
+    startTime: z.number().optional(),
+    endTime: z.number().optional(),
+    duration: z.number().optional(),
+    retryCount: z.number().int().nonnegative().optional(),
+    lastError: z.string().optional()
+  }).optional()
+});
+var PersistentMetadata = z.object({
+  messageType: z.literal("summary").optional(),
+  originalMessageCount: z.number().int().positive().optional(),
+  compressionRatio: z.number().min(0).max(1).optional(),
+  includedOldSummary: z.boolean().optional(),
+  replacedMessageIds: z.array(z.string()).optional(),
+  summarySeq: z.number().int().nonnegative().optional(),
+  tool_calls: z.array(ToolCallWire).optional(),
+  reasoning_details: ProviderReasoningDetails.optional(),
+  tool_name: z.string().optional(),
+  args: z.record(z.unknown()).optional(),
+  tool_call_id: z.string().optional(),
+  raw_output: z.string().optional(),
+  image_info: ImageInfoMeta.optional(),
+  taskType: z.string().optional(),
+  taskId: z.string().optional(),
+  taskStatus: z.enum(["requested", "in_progress", "completed", "failed"]).optional(),
+  taskTrackingInfo: z.object({
+    startTime: z.number().optional(),
+    endTime: z.number().optional(),
+    duration: z.number().optional(),
+    retryCount: z.number().int().nonnegative().optional(),
+    lastError: z.string().optional()
+  }).optional(),
+  fenceKind: z.string().optional(),
+  fenceAttrs: z.record(z.unknown()).optional(),
+  fencePlacement: z.string().optional()
+}).passthrough();
+var BaseMessage = z.object({
+  id: z.string(),
+  content: z.string(),
+  timestamp: z.number().int().nonnegative(),
+  metadata: PersistentMetadata.optional()
+});
+var SystemMessage = BaseMessage.extend({
+  role: z.literal("system"),
+  type: z.enum(["system_prompt", "history_summary", "context_injection"])
+});
+var UserMessage = BaseMessage.extend({
+  role: z.literal("user"),
+  type: z.enum([
+    "user_input",
+    "context_injection",
+    "context_before",
+    "context_after",
+    "document_fragment",
+    "task_request",
+    "image"
+  ])
+});
+var AssistantMessage = BaseMessage.extend({
+  role: z.literal("assistant"),
+  type: z.enum([
+    "thought",
+    "final_answer",
+    "tool_code",
+    "tool_calls",
+    "task_completion"
+  ])
+});
+var ToolMessage = BaseMessage.extend({
+  role: z.literal("tool"),
+  type: z.literal("tool_output")
+});
+var AiMessage = z.discriminatedUnion("role", [
+  SystemMessage,
+  UserMessage,
+  AssistantMessage,
+  ToolMessage
+]);
+function createSystemMessage(type, content, metadata) {
+  return {
+    id: crypto.randomUUID(),
+    role: "system",
+    type,
+    content,
+    timestamp: Date.now(),
+    metadata
+  };
+}
+function createUserMessage(type, content, metadata) {
+  return {
+    id: crypto.randomUUID(),
+    role: "user",
+    type,
+    content,
+    timestamp: Date.now(),
+    metadata
+  };
+}
+function createAssistantMessage(type, content, metadata) {
+  return {
+    id: crypto.randomUUID(),
+    role: "assistant",
+    type,
+    content,
+    timestamp: Date.now(),
+    metadata
+  };
+}
+function createToolMessage(content, toolCallId, toolName, metadata) {
+  return {
+    id: crypto.randomUUID(),
+    role: "tool",
+    type: "tool_output",
+    content,
+    timestamp: Date.now(),
+    metadata: {
+      ...metadata,
+      tool_call_id: toolCallId,
+      tool_name: toolName
+    }
+  };
+}
+function createHistorySummaryMessage(content, summaryMeta) {
+  return {
+    id: crypto.randomUUID(),
+    role: "system",
+    type: "history_summary",
+    content,
+    timestamp: Date.now(),
+    metadata: summaryMeta
+  };
+}
+function validateAiMessage(data) {
+  return AiMessage.safeParse(data);
+}
+function validateHistorySummaryMeta(data) {
+  return HistorySummaryMeta.safeParse(data);
+}
+function isSystemMessage(message) {
+  return message.role === "system";
+}
+function isUserMessage(message) {
+  return message.role === "user";
+}
+function isAssistantMessage(message) {
+  return message.role === "assistant";
+}
+function isToolMessage(message) {
+  return message.role === "tool";
+}
+function isHistorySummaryMessage(message) {
+  return message.role === "system" && message.type === "history_summary" && message.metadata?.messageType === "summary";
+}
+function hasToolCalls(message) {
+  return message.role === "assistant" && Array.isArray(message.metadata?.tool_calls) && message.metadata.tool_calls.length > 0;
+}
+var SerializableJsonValueSchema = z.lazy(
+  () => z.union([
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.null(),
+    z.array(SerializableJsonValueSchema),
+    z.record(z.string(), SerializableJsonValueSchema)
+  ])
+);
+var SerializableJsonRecord = z.record(z.string(), SerializableJsonValueSchema);
+var AgentSpecMessageType = z.enum([
+  "system_prompt",
+  "history_summary",
+  "context_injection",
+  "user_input",
+  "context_before",
+  "context_after",
+  "document_fragment",
+  "task_request",
+  "image",
+  "thought",
+  "final_answer",
+  "tool_code",
+  "tool_calls",
+  "task_completion",
+  "tool_output"
+]);
+var AgentSpecBudgetPolicy = z.object({
+  maxTokens: z.number().int().positive().optional(),
+  reservedForResponse: z.number().int().nonnegative().optional(),
+  workingMemoryBudgetPercentage: z.number().min(0).max(1).optional()
+});
+var AgentSpecToolHistoryPolicy = z.object({
+  strategy: z.enum(["per-pair", "per-run", "none"]).optional(),
+  keepLatestToolPairs: z.number().int().nonnegative().optional(),
+  keepLatestRuns: z.number().int().nonnegative().optional(),
+  maxInteractionGroups: z.number().int().nonnegative().optional(),
+  overflowStrategy: z.enum(["keep-latest", "fail-fast"]).optional(),
+  maxPairTokens: z.number().int().nonnegative().optional(),
+  maxOutputSummaryTokens: z.number().int().nonnegative().optional()
+});
+var AgentSpecToolObservationGovernancePolicy = z.object({
+  enabled: z.boolean().optional(),
+  maxChars: z.number().int().positive().optional(),
+  maxLines: z.number().int().positive().optional()
+});
+var AgentSpecToolOutputPolicy = z.object({
+  observationGovernance: AgentSpecToolObservationGovernancePolicy.optional()
+});
+var AgentSpecProviderReplayPolicy = z.object({
+  provider: z.string().min(1).optional(),
+  requiresReasoningDetailsForToolReplay: z.boolean().optional(),
+  missingSidecarBehavior: z.enum(["allow", "degrade_to_text", "provider_empty_replay_field"]).optional()
+});
+var AgentSpecSummarizationPolicy = z.object({
+  triggerThreshold: z.number().min(0).max(1).optional(),
+  budgetPercentage: z.number().min(0).max(1).optional(),
+  oldestMessagesPercentage: z.number().min(0).max(1).optional(),
+  agentId: z.string().min(1).optional(),
+  failureBehavior: z.enum(["fail-fast", "continue-if-within-budget"]).optional()
+});
+var AgentSpecMustKeepTruncationRule = z.object({
+  fenceKind: z.string().min(1),
+  maxBudgetFraction: z.number().gt(0).max(1),
+  strategyName: z.string().min(1)
+});
+var AgentSpecMustKeepPolicy = z.object({
+  alwaysKeepTypes: z.array(AgentSpecMessageType).optional(),
+  alwaysKeepFenceKinds: z.array(z.string().min(1)).optional(),
+  truncationRules: z.array(AgentSpecMustKeepTruncationRule).optional()
+});
+var AgentSpecWorkingMemoryPolicy = z.object({
+  maxRecentToolInteractions: z.number().int().nonnegative().optional(),
+  minToolInteractionsToKeep: z.number().int().nonnegative().optional(),
+  toolPairingSearchRange: z.number().int().positive().optional()
+});
+var AgentSpecCheckpointPolicy = z.object({
+  keepPairsBefore: z.number().int().nonnegative().optional(),
+  triggerToolName: z.string().min(1).optional()
+});
+var AgentSpecReasoningRetentionPolicy = z.object({
+  keepLatestThoughts: z.number().int().nonnegative().optional()
+});
+var AgentSpecTokenEstimationPolicy = z.object({
+  encoding: z.string().min(1).optional(),
+  avgCharsPerToken: z.number().positive().optional(),
+  toolCallOverhead: z.number().int().nonnegative().optional()
+});
+var SYSTEM_REMINDER_BUILTIN_TRIGGER_KINDS = [
+  "phase-equals",
+  "remaining-steps-leq",
+  "step-count-modulo",
+  "tool-call-streak",
+  "budget-warning",
+  "agent-has-tool"
+];
+var AgentSpecSystemReminderTrigger = z.object({
+  kind: z.string().min(1),
+  threshold: z.number().nonnegative().optional(),
+  value: z.union([z.string(), z.number(), z.boolean()]).optional(),
+  moduloStep: z.boolean().optional(),
+  toolName: z.string().min(1).optional(),
+  period: z.number().int().positive().optional(),
+  minStep: z.number().int().nonnegative().optional(),
+  ratio: z.number().min(0).max(1).optional(),
+  config: SerializableJsonRecord.optional()
+});
+var AgentSpecSystemReminderExtraRule = z.object({
+  id: z.string().min(1),
+  trigger: AgentSpecSystemReminderTrigger,
+  contentTemplate: z.string().min(1),
+  contentArgs: SerializableJsonRecord.optional()
+});
+var AgentSpecSystemReminderPolicy = z.object({
+  enabledRuleIds: z.array(z.string().min(1)).nullable().optional(),
+  disabledRuleIds: z.array(z.string().min(1)).optional(),
+  thresholds: z.object({
+    toolCallStreak: z.number().int().nonnegative().optional(),
+    taskstateReflectionPeriod: z.number().int().positive().optional(),
+    budgetWarningRatio: z.number().min(0).max(1).optional(),
+    lastStepsHintThreshold: z.number().int().nonnegative().optional()
+  }).optional(),
+  extraRules: z.array(AgentSpecSystemReminderExtraRule).optional()
+}).superRefine((value, ctx) => {
+  if (value.enabledRuleIds !== void 0 && value.enabledRuleIds !== null && value.disabledRuleIds?.length) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["disabledRuleIds"],
+      message: "enabledRuleIds and disabledRuleIds cannot be configured at the same time"
+    });
+  }
+});
+var AgentSpecContextTracePolicy = z.object({
+  enabled: z.boolean().optional(),
+  includeMessageIds: z.boolean().optional(),
+  includeTokenBreakdown: z.boolean().optional(),
+  maxTraceEvents: z.number().int().positive().optional()
+});
+var AgentSpecContextPolicy = z.object({
+  profileId: z.string().min(1),
+  budget: AgentSpecBudgetPolicy.optional(),
+  toolHistory: AgentSpecToolHistoryPolicy.optional(),
+  toolOutput: AgentSpecToolOutputPolicy.optional(),
+  providerReplay: AgentSpecProviderReplayPolicy.optional(),
+  summarization: AgentSpecSummarizationPolicy.optional(),
+  mustKeep: AgentSpecMustKeepPolicy.optional(),
+  workingMemory: AgentSpecWorkingMemoryPolicy.optional(),
+  checkpoint: AgentSpecCheckpointPolicy.optional(),
+  reasoningRetention: AgentSpecReasoningRetentionPolicy.optional(),
+  tokenEstimation: AgentSpecTokenEstimationPolicy.optional(),
+  systemReminder: AgentSpecSystemReminderPolicy.optional(),
+  contextTrace: AgentSpecContextTracePolicy.optional()
+});
+var DEFAULT_CONTEXT_POLICY = {
+  profileId: "agent",
+  budget: {
+    maxTokens: 12e4,
+    reservedForResponse: 2400,
+    workingMemoryBudgetPercentage: 0.7
+  },
+  toolHistory: {
+    strategy: "per-run",
+    keepLatestToolPairs: 2,
+    keepLatestRuns: 1,
+    maxInteractionGroups: 12,
+    overflowStrategy: "keep-latest",
+    maxPairTokens: 6e3,
+    maxOutputSummaryTokens: 1e3
+  },
+  toolOutput: {
+    observationGovernance: {
+      enabled: true,
+      maxChars: 2e4,
+      maxLines: 1200
+    }
+  },
+  providerReplay: {},
+  summarization: {
+    triggerThreshold: 0.7,
+    budgetPercentage: 0.12,
+    oldestMessagesPercentage: 0.75,
+    failureBehavior: "fail-fast"
+  },
+  mustKeep: {
+    alwaysKeepTypes: ["system_prompt", "user_input"],
+    alwaysKeepFenceKinds: [],
+    truncationRules: []
+  },
+  workingMemory: {
+    maxRecentToolInteractions: 2,
+    minToolInteractionsToKeep: 2,
+    toolPairingSearchRange: 10
+  },
+  checkpoint: {
+    keepPairsBefore: 2,
+    triggerToolName: "context_checkpoint"
+  },
+  reasoningRetention: {
+    keepLatestThoughts: 1
+  },
+  tokenEstimation: {
+    encoding: "cl100k_base",
+    avgCharsPerToken: 2,
+    toolCallOverhead: 50
+  },
+  systemReminder: {
+    enabledRuleIds: null,
+    disabledRuleIds: [],
+    thresholds: {
+      toolCallStreak: 10,
+      taskstateReflectionPeriod: 30,
+      budgetWarningRatio: 0.9,
+      lastStepsHintThreshold: 0
+    },
+    extraRules: []
+  },
+  contextTrace: {
+    enabled: false,
+    includeMessageIds: true,
+    includeTokenBreakdown: true,
+    maxTraceEvents: 200
+  }
+};
+function defineContextPolicy(input = {}) {
+  const merged = {
+    profileId: input.profileId ?? DEFAULT_CONTEXT_POLICY.profileId,
+    budget: { ...DEFAULT_CONTEXT_POLICY.budget, ...input.budget },
+    toolHistory: { ...DEFAULT_CONTEXT_POLICY.toolHistory, ...input.toolHistory },
+    toolOutput: {
+      ...DEFAULT_CONTEXT_POLICY.toolOutput,
+      ...input.toolOutput,
+      observationGovernance: {
+        ...DEFAULT_CONTEXT_POLICY.toolOutput.observationGovernance,
+        ...input.toolOutput?.observationGovernance
+      }
+    },
+    providerReplay: { ...DEFAULT_CONTEXT_POLICY.providerReplay, ...input.providerReplay },
+    summarization: { ...DEFAULT_CONTEXT_POLICY.summarization, ...input.summarization },
+    mustKeep: { ...DEFAULT_CONTEXT_POLICY.mustKeep, ...input.mustKeep },
+    workingMemory: { ...DEFAULT_CONTEXT_POLICY.workingMemory, ...input.workingMemory },
+    checkpoint: { ...DEFAULT_CONTEXT_POLICY.checkpoint, ...input.checkpoint },
+    reasoningRetention: { ...DEFAULT_CONTEXT_POLICY.reasoningRetention, ...input.reasoningRetention },
+    tokenEstimation: { ...DEFAULT_CONTEXT_POLICY.tokenEstimation, ...input.tokenEstimation },
+    systemReminder: {
+      ...DEFAULT_CONTEXT_POLICY.systemReminder,
+      ...input.systemReminder,
+      thresholds: {
+        ...DEFAULT_CONTEXT_POLICY.systemReminder.thresholds,
+        ...input.systemReminder?.thresholds
+      },
+      extraRules: input.systemReminder?.extraRules ?? DEFAULT_CONTEXT_POLICY.systemReminder.extraRules
+    },
+    contextTrace: { ...DEFAULT_CONTEXT_POLICY.contextTrace, ...input.contextTrace }
+  };
+  return AgentSpecContextPolicy.parse(merged);
+}
+var JsonRecord = z.record(z.string(), z.unknown());
+var ToolArgsSchemaSpec = JsonRecord.superRefine((value, ctx) => {
+  const parse = value["parse"];
+  const safeParse = value["safeParse"];
+  const definition = value["_def"];
+  if (typeof parse === "function" && typeof safeParse === "function" && definition !== void 0) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "argsSchema must be a serializable record, not a runtime zod schema"
+    });
+  }
+});
+var AgentCapability = z.string().min(1);
+var ToolBindingSpec = z.object({
+  toolId: z.string().min(1),
+  bindingId: z.string().min(1).optional(),
+  argsSchema: ToolArgsSchemaSpec.optional(),
+  config: JsonRecord.optional(),
+  metadata: JsonRecord.optional()
+});
+var AgentSpecModelHints = z.object({
+  preferredProviders: z.array(z.string().min(1)).optional(),
+  preferredModels: z.array(z.string().min(1)).optional(),
+  fallbackChain: z.array(z.string().min(1)).optional()
+});
+var AgentSpecAuditConfig = z.object({
+  redactionLevel: z.enum(["none", "standard", "strict"]).optional(),
+  pii: z.boolean().optional()
+});
+var AgentSpec = z.object({
+  id: z.string().min(1),
+  version: z.string().min(1),
+  role: z.string().optional(),
+  description: z.string().optional(),
+  capabilities: z.array(AgentCapability),
+  tools: z.array(ToolBindingSpec),
+  contextPolicy: AgentSpecContextPolicy,
+  modelHints: AgentSpecModelHints.optional(),
+  audit: AgentSpecAuditConfig.optional(),
+  metadata: JsonRecord.optional()
+});
+var JsonRecord2 = z.record(z.string(), z.unknown());
+var AUDIT_ACTIONS = [
+  "model.select",
+  "model.fallback",
+  "tool.allow",
+  "tool.deny",
+  "wait_user.request",
+  "sandbox.decide",
+  "run.cancel",
+  "run.pause",
+  "run.resume",
+  "memory.write"
+];
+var AUDIT_DECISION_OUTCOMES = [
+  "allowed",
+  "denied",
+  "fallback",
+  "retry",
+  "cancelled",
+  "paused",
+  "resumed",
+  "requested",
+  "recorded"
+];
+var AuditActor = z.object({
+  kind: z.enum(["system", "host", "agent", "model", "tool", "user"]),
+  id: z.string().min(1).optional(),
+  name: z.string().min(1).optional()
+});
+var AuditDecision = z.object({
+  outcome: z.enum(AUDIT_DECISION_OUTCOMES),
+  reason: z.string().optional(),
+  policy: z.string().optional(),
+  metadata: JsonRecord2.optional()
+});
+var AuditEvidence = z.object({
+  kind: z.string().min(1),
+  ref: z.string().min(1).optional(),
+  summary: z.string().optional(),
+  metadata: JsonRecord2.optional()
+});
+var AuditCostDelta = z.object({
+  tokensInput: z.number().int().nonnegative().optional(),
+  tokensOutput: z.number().int().nonnegative().optional(),
+  totalCostUsd: z.number().nonnegative().optional(),
+  latencyMs: z.number().nonnegative().optional()
+});
+var AuditScope = z.object({
+  conversationId: z.string().min(1).optional(),
+  runId: z.string().min(1).optional(),
+  parentRunId: z.string().min(1).optional(),
+  turnId: z.string().min(1).optional(),
+  traceId: z.string().min(1).optional(),
+  agentSpecId: z.string().min(1).optional(),
+  toolCallId: z.string().min(1).optional(),
+  toolName: z.string().min(1).optional(),
+  modelId: z.string().min(1).optional(),
+  nodeId: z.string().min(1).optional(),
+  metadata: JsonRecord2.optional()
+});
+var AuditEnvelope = z.object({
+  envelopeId: z.string().min(1),
+  runId: z.string().min(1),
+  parentRunId: z.string().min(1).optional(),
+  ts: z.number().int().nonnegative(),
+  actor: AuditActor,
+  action: z.string().min(1),
+  decision: AuditDecision.optional(),
+  evidence: z.array(AuditEvidence).optional(),
+  costDelta: AuditCostDelta.optional(),
+  scope: AuditScope.optional()
+});
+var BaseEvent = z.object({
+  id: z.string(),
+  conversation_id: z.string(),
+  timestamp: z.number(),
+  metadata: z.record(z.unknown()).optional(),
+  version: z.literal(1).default(1),
+  turn_id: z.string(),
+  ephemeral: z.boolean().optional()
+});
+var ToolCallPhase = z.enum(["start", "update", "complete", "error"]);
+var Status = z.enum(["loading", "success", "error"]);
+var AgentTodoStatus = z.enum(["pending", "in_progress", "completed", "cancelled"]);
+var AgentTodoItem = z.object({
+  id: z.string(),
+  content: z.string(),
+  status: AgentTodoStatus
+});
+var ProviderReasoningDetailsPayload = z.array(z.unknown());
+var ToolCallDecisionPayload = z.object({
+  args: z.record(z.any()).optional(),
+  tool_calls: z.array(z.unknown()).optional(),
+  /**
+   * 不透明 provider reasoning replay blocks。
+   *
+      * RuntimeEvent 层的标准位置是 assistant 产出事件携带 reasoning_details；
+      * context-manager 会把它回放到 AiMessage.metadata.reasoning_details。
+   */
+  reasoning_details: ProviderReasoningDetailsPayload.optional()
+}).passthrough();
+var RuntimeEvent = z.discriminatedUnion("type", [
+  BaseEvent.extend({
+    type: z.literal("user_input"),
+    content: z.string(),
+    raw_content: z.string().optional(),
+    source: z.enum(["user", "editor", "system"]).default("user")
+  }),
+  BaseEvent.extend({
+    type: z.literal("thought"),
+    content: z.string(),
+    thought_message_id: z.string().optional(),
+    delta: z.string().optional(),
+    is_complete: z.boolean().default(false)
+  }),
+  BaseEvent.extend({
+    type: z.literal("tool_call_decision"),
+    tool_name: z.string(),
+    tool_call_id: z.string(),
+    phase: ToolCallPhase,
+    status: Status,
+    args: z.record(z.any()).optional(),
+    payload: ToolCallDecisionPayload.optional(),
+    parent_tool_call_id: z.string().optional(),
+    meta: z.record(z.any()).optional()
+  }),
+  BaseEvent.extend({
+    type: z.literal("tool_process"),
+    tool_name: z.string(),
+    tool_call_id: z.string(),
+    phase: ToolCallPhase,
+    status: Status,
+    args: z.record(z.any()).optional(),
+    payload: z.record(z.any()).optional(),
+    parent_tool_call_id: z.string().optional(),
+    meta: z.record(z.any()).optional()
+  }),
+  BaseEvent.extend({
+    type: z.literal("tool_output"),
+    tool_name: z.string(),
+    tool_call_id: z.string(),
+    status: z.enum(["success", "error"]),
+    output: z.any().optional(),
+    payload: z.record(z.any()).optional(),
+    error: z.string().optional(),
+    duration_ms: z.number().optional()
+  }),
+  BaseEvent.extend({
+    type: z.literal("todo_updated"),
+    todo_list_id: z.string(),
+    todo_list_version: z.number().int().nonnegative(),
+    items: z.array(AgentTodoItem)
+  }),
+  BaseEvent.extend({
+    type: z.literal("subrun_trace"),
+    parent_tool_call_id: z.string(),
+    subrun_id: z.string(),
+    subrun_parent_id: z.string().optional(),
+    kind: z.enum([
+      "thought_delta",
+      "thought_complete",
+      "tool_call_decision",
+      "tool_process",
+      "tool_output",
+      "final_answer_chunk",
+      "final_answer"
+    ]),
+    delta: z.string().optional(),
+    content: z.string().optional(),
+    tool_name: z.string().optional(),
+    tool_call_id: z.string().optional(),
+    phase: ToolCallPhase.optional(),
+    status: Status.optional(),
+    args: z.unknown().optional(),
+    output: z.unknown().optional(),
+    duration_ms: z.number().optional(),
+    meta: z.record(z.unknown()).optional()
+  }),
+  BaseEvent.extend({
+    type: z.literal("requires_user_interaction"),
+    form: z.any().optional(),
+    interaction_type: z.string().optional(),
+    prompt: z.string().optional()
+  }),
+  BaseEvent.extend({
+    type: z.literal("audit_envelope"),
+    envelope: AuditEnvelope
+  }),
+  BaseEvent.extend({
+    type: z.literal("final_answer"),
+    answer_id: z.string(),
+    content: z.string(),
+    is_complete: z.boolean().default(true),
+    reasoning_details: ProviderReasoningDetailsPayload.optional(),
+    meta: z.record(z.any()).optional()
+  }),
+  BaseEvent.extend({
+    type: z.literal("final_answer_chunk"),
+    answer_id: z.string(),
+    seq: z.number().int().nonnegative(),
+    content: z.string(),
+    is_last: z.boolean().optional()
+  }),
+  BaseEvent.extend({
+    type: z.literal("history_summary"),
+    content: z.string(),
+    replaced_message_ids: z.array(z.string()),
+    summary_seq: z.number().int().nonnegative(),
+    original_message_count: z.number().int().nonnegative().optional(),
+    compression_ratio: z.number().min(0).max(1).optional(),
+    included_old_summary: z.boolean().optional()
+  }),
+  BaseEvent.extend({
+    type: z.literal("error"),
+    error: z.string(),
+    details: z.any().optional(),
+    error_code: z.string().optional(),
+    retryable: z.boolean().optional()
+  }),
+  BaseEvent.extend({
+    type: z.literal("control"),
+    op: z.enum(["truncate_after", "replace", "redo", "branch"]),
+    target_id: z.string().optional(),
+    reason: z.string().optional(),
+    meta: z.any().optional()
+  }),
+  BaseEvent.extend({
+    type: z.literal("stream_end"),
+    reason: z.enum(["complete", "error", "interrupted", "timeout"]).optional(),
+    reason_message: z.string().optional(),
+    stats: z.object({
+      total_events: z.number().optional(),
+      duration_ms: z.number().optional(),
+      error_count: z.number().optional()
+    }).optional()
+  })
+]);
+var validateRuntimeEvent = (event) => RuntimeEvent.safeParse(event);
+var validateRuntimeEvents = (events) => z.array(RuntimeEvent).safeParse(events);
+var createUserInputEvent = (id, conversationId, turnId, content, options = {}) => ({
+  type: "user_input",
+  id,
+  conversation_id: conversationId,
+  turn_id: turnId,
+  timestamp: Date.now(),
+  version: 1,
+  content,
+  source: "user",
+  ...options
+});
+var createThoughtEvent = (id, conversationId, turnId, content, options = {}) => ({
+  type: "thought",
+  id,
+  conversation_id: conversationId,
+  turn_id: turnId,
+  timestamp: Date.now(),
+  version: 1,
+  content,
+  is_complete: false,
+  ...options
+});
+var createToolCallDecisionEvent = (id, conversationId, turnId, toolName, toolCallId, options = {}) => ({
+  type: "tool_call_decision",
+  id,
+  conversation_id: conversationId,
+  turn_id: turnId,
+  timestamp: Date.now(),
+  version: 1,
+  tool_name: toolName,
+  tool_call_id: toolCallId,
+  phase: "start",
+  status: "loading",
+  ...options
+});
+var createToolProcessEvent = (id, conversationId, turnId, toolName, toolCallId, options = {}) => ({
+  type: "tool_process",
+  id,
+  conversation_id: conversationId,
+  turn_id: turnId,
+  timestamp: Date.now(),
+  version: 1,
+  tool_name: toolName,
+  tool_call_id: toolCallId,
+  phase: "start",
+  status: "loading",
+  ...options
+});
+var createSubRunTraceEvent = (id, conversationId, turnId, parentToolCallId, subrunId, kind, options = {}) => ({
+  type: "subrun_trace",
+  id,
+  conversation_id: conversationId,
+  turn_id: turnId,
+  timestamp: Date.now(),
+  version: 1,
+  ephemeral: true,
+  parent_tool_call_id: parentToolCallId,
+  subrun_id: subrunId,
+  kind,
+  ...options
+});
+var createToolOutputEvent = (id, conversationId, turnId, toolName, toolCallId, output, status = "success", options = {}) => ({
+  type: "tool_output",
+  id,
+  conversation_id: conversationId,
+  turn_id: turnId,
+  timestamp: Date.now(),
+  version: 1,
+  tool_name: toolName,
+  tool_call_id: toolCallId,
+  status,
+  output,
+  ...options
+});
+var createTodoUpdatedEvent = (id, conversationId, turnId, todoListId, todoListVersion, items, options = {}) => ({
+  type: "todo_updated",
+  id,
+  conversation_id: conversationId,
+  turn_id: turnId,
+  timestamp: Date.now(),
+  version: 1,
+  todo_list_id: todoListId,
+  todo_list_version: todoListVersion,
+  items,
+  ...options
+});
+var createFinalAnswerEvent = (id, conversationId, turnId, answerId, content, options = {}) => ({
+  type: "final_answer",
+  id,
+  conversation_id: conversationId,
+  turn_id: turnId,
+  timestamp: Date.now(),
+  version: 1,
+  answer_id: answerId,
+  content,
+  is_complete: true,
+  ...options
+});
+var createAuditEnvelopeEvent = (id, conversationId, turnId, envelope, options = {}) => ({
+  type: "audit_envelope",
+  id,
+  conversation_id: conversationId,
+  turn_id: turnId,
+  timestamp: envelope.ts,
+  version: 1,
+  envelope,
+  metadata: {
+    audit_action: envelope.action,
+    run_context: {
+      runId: envelope.runId,
+      parentId: envelope.parentRunId,
+      traceId: envelope.scope?.traceId
+    }
+  },
+  ...options
+});
+var createFinalAnswerChunkEvent = (id, conversationId, turnId, answerId, seq, content, options = {}) => ({
+  type: "final_answer_chunk",
+  id,
+  conversation_id: conversationId,
+  turn_id: turnId,
+  timestamp: Date.now(),
+  version: 1,
+  answer_id: answerId,
+  seq,
+  content,
+  ...options
+});
+var createHistorySummaryEvent = (id, conversationId, turnId, content, replacedMessageIds, summarySeq, options = {}) => ({
+  type: "history_summary",
+  id,
+  conversation_id: conversationId,
+  turn_id: turnId,
+  timestamp: Date.now(),
+  version: 1,
+  content,
+  replaced_message_ids: replacedMessageIds,
+  summary_seq: summarySeq,
+  ...options
+});
+var createErrorEvent = (id, conversationId, turnId, error, options = {}) => ({
+  type: "error",
+  id,
+  conversation_id: conversationId,
+  turn_id: turnId,
+  timestamp: Date.now(),
+  version: 1,
+  error,
+  ...options
+});
+var createStreamEndEvent = (id, conversationId, turnId, options = {}) => ({
+  type: "stream_end",
+  id,
+  conversation_id: conversationId,
+  turn_id: turnId,
+  timestamp: Date.now(),
+  version: 1,
+  ...options
+});
+
+// src/contracts/constants.ts
+var DEFAULT_MAX_STEPS = 80;
+var ExecutionTraceContext = z.object({
+  execution_id: z.string().describe("The unique identifier for a single, complete execution flow."),
+  trace_id: z.string().optional().describe("An optional trace ID for correlating logs in an APM system.")
+});
+var EventEnvelopeSchema = z.object({
+  seq: z.number().int().nonnegative().describe("A monotonically increasing sequence number within a single execution."),
+  timestamp: z.number().describe("The high-precision timestamp of when the event occurred."),
+  trace: ExecutionTraceContext,
+  source: z.string().describe("The origin of the event, e.g., 'ai', 'tool:file_reader', 'system:summary'."),
+  payload: z.unknown(),
+  render_hint: z.object({
+    card: z.enum(["normal", "collapsible", "none", "image", "interactive"]).optional().describe("Hint for how the UI card should be rendered."),
+    content: z.enum(["markdown", "text", "json", "image_url", "code"]).default("text").describe("Hint for how the content itself should be interpreted.")
+  }).optional(),
+  run_location: z.enum(["frontend", "backend"]).optional().describe("Specifies where a tool action should be or was executed.")
+});
+var EventEnvelope = EventEnvelopeSchema;
+var BaseSSEEvent = z.object({
+  id: z.string(),
+  timestamp: z.number(),
+  conversation_id: z.string(),
+  turn_id: z.string(),
+  metadata: z.record(z.unknown()).optional()
+});
+var SSEThoughtEvent = BaseSSEEvent.extend({
+  type: z.literal("thought"),
+  thought_message_id: z.string().optional(),
+  delta: z.string().optional(),
+  content: z.string().optional(),
+  is_complete: z.boolean().default(false)
+});
+var SSEFinalAnswerChunkEvent = BaseSSEEvent.extend({
+  type: z.literal("final_answer_chunk"),
+  answer_id: z.string(),
+  seq: z.number().int().nonnegative(),
+  chunk: z.string(),
+  is_last: z.boolean().optional()
+});
+var SSEFinalAnswerEvent = BaseSSEEvent.extend({
+  type: z.literal("final_answer"),
+  answer_id: z.string(),
+  content: z.string(),
+  meta: z.record(z.any()).optional()
+});
+var SSEMarkdownChunkEvent = BaseSSEEvent.extend({
+  type: z.literal("markdown_chunk"),
+  content_type: z.enum(["text", "code", "table", "image"]).default("text"),
+  text: z.string(),
+  seq: z.number().optional()
+});
+var BaseSSEToolLifecycleEvent = BaseSSEEvent.extend({
+  tool_name: z.string(),
+  tool_call_id: z.string(),
+  phase: z.enum(["start", "update", "complete", "error"]),
+  status: z.enum(["loading", "success", "error"]),
+  args: z.any().optional(),
+  payload: z.any().optional(),
+  meta: z.record(z.any()).optional()
+});
+var SSEToolCallDecisionEvent = BaseSSEToolLifecycleEvent.extend({
+  type: z.literal("tool_call_decision")
+});
+var SSEToolProcessEvent = BaseSSEToolLifecycleEvent.extend({
+  type: z.literal("tool_process")
+});
+var SSEToolOutputEvent = BaseSSEEvent.extend({
+  type: z.literal("tool_output"),
+  tool_name: z.string(),
+  tool_call_id: z.string(),
+  status: z.enum(["success", "error"]),
+  output: z.any().optional(),
+  payload: z.record(z.any()).optional(),
+  duration_ms: z.number().optional()
+});
+var SSETodoUpdatedEvent = BaseSSEEvent.extend({
+  type: z.literal("todo_updated"),
+  todo_list_id: z.string(),
+  todo_list_version: z.number().int().nonnegative(),
+  items: z.array(z.object({
+    id: z.string(),
+    content: z.string(),
+    status: z.enum(["pending", "in_progress", "completed", "cancelled"])
+  }))
+});
+var SSESubRunTraceEvent = BaseSSEEvent.extend({
+  type: z.literal("subrun_trace"),
+  parent_tool_call_id: z.string(),
+  subrun_id: z.string(),
+  subrun_parent_id: z.string().optional(),
+  kind: z.enum([
+    "thought_delta",
+    "thought_complete",
+    "tool_call_decision",
+    "tool_process",
+    "tool_output",
+    "final_answer_chunk",
+    "final_answer"
+  ]),
+  delta: z.string().optional(),
+  content: z.string().optional(),
+  tool_name: z.string().optional(),
+  tool_call_id: z.string().optional(),
+  phase: z.enum(["start", "update", "complete", "error"]).optional(),
+  status: z.enum(["loading", "success", "error"]).optional(),
+  args: z.unknown().optional(),
+  output: z.unknown().optional(),
+  duration_ms: z.number().optional(),
+  meta: z.record(z.unknown()).optional()
+});
+var SSERequiresUserInteractionEvent = BaseSSEEvent.extend({
+  type: z.literal("requires_user_interaction"),
+  form: z.any().optional(),
+  interaction_type: z.string().optional(),
+  prompt: z.string().optional()
+});
+var SSEErrorEvent = BaseSSEEvent.extend({
+  type: z.literal("error"),
+  error: z.string(),
+  details: z.any().optional(),
+  error_code: z.string().optional(),
+  retryable: z.boolean().optional()
+});
+var SSEStreamEndEvent = BaseSSEEvent.extend({
+  type: z.literal("stream_end"),
+  reason: z.enum(["complete", "error", "interrupted", "timeout"]).optional(),
+  reason_message: z.string().optional(),
+  stats: z.object({
+    total_events: z.number().optional(),
+    duration_ms: z.number().optional(),
+    error_count: z.number().optional(),
+    benchmark: z.record(z.unknown()).optional()
+  }).optional()
+});
+var SSEHistorySummaryEvent = BaseSSEEvent.extend({
+  type: z.literal("history_summary"),
+  summary_id: z.string(),
+  content: z.string(),
+  original_message_count: z.number().int().nonnegative(),
+  summary_seq: z.number().int().nonnegative()
+});
+var SSESummarizationStartEvent = BaseSSEEvent.extend({
+  type: z.literal("summarization_start"),
+  originalMessages: z.number().optional()
+});
+var SSESummarizationEndEvent = BaseSSEEvent.extend({
+  type: z.literal("summarization_end"),
+  originalMessages: z.number().optional(),
+  compressedMessages: z.number().optional(),
+  compressionRatio: z.string().optional(),
+  timeSaved: z.string().optional()
+});
+var SSESummarizationErrorEvent = BaseSSEEvent.extend({
+  type: z.literal("summarization_error"),
+  error: z.string()
+});
+var SSEEvent = z.discriminatedUnion("type", [
+  SSEThoughtEvent,
+  SSEFinalAnswerChunkEvent,
+  SSEFinalAnswerEvent,
+  SSEMarkdownChunkEvent,
+  SSEToolCallDecisionEvent,
+  SSEToolProcessEvent,
+  SSEToolOutputEvent,
+  SSETodoUpdatedEvent,
+  SSESubRunTraceEvent,
+  SSERequiresUserInteractionEvent,
+  SSEErrorEvent,
+  SSEStreamEndEvent,
+  SSEHistorySummaryEvent,
+  SSESummarizationStartEvent,
+  SSESummarizationEndEvent,
+  SSESummarizationErrorEvent
+]);
+var validateSSEEvent = (event) => SSEEvent.safeParse(event);
+var createSSEThoughtEvent = (id, conversationId, turnId, options = {}) => ({
+  type: "thought",
+  id,
+  timestamp: Date.now(),
+  conversation_id: conversationId,
+  turn_id: turnId,
+  is_complete: false,
+  ...options
+});
+var createSSEFinalAnswerChunkEvent = (id, conversationId, turnId, answerId, seq, chunk, options = {}) => ({
+  type: "final_answer_chunk",
+  id,
+  timestamp: Date.now(),
+  conversation_id: conversationId,
+  turn_id: turnId,
+  answer_id: answerId,
+  seq,
+  chunk,
+  ...options
+});
+var createSSEFinalAnswerEvent = (id, conversationId, turnId, answerId, content, options = {}) => ({
+  type: "final_answer",
+  id,
+  timestamp: Date.now(),
+  conversation_id: conversationId,
+  turn_id: turnId,
+  answer_id: answerId,
+  content,
+  ...options
+});
+var createSSEMarkdownChunkEvent = (id, conversationId, turnId, text, options = {}) => ({
+  type: "markdown_chunk",
+  id,
+  timestamp: Date.now(),
+  conversation_id: conversationId,
+  turn_id: turnId,
+  text,
+  content_type: "text",
+  ...options
+});
+var createSSEToolCallDecisionEvent = (id, conversationId, turnId, toolName, toolCallId, phase, status, options = {}) => ({
+  type: "tool_call_decision",
+  id,
+  timestamp: Date.now(),
+  conversation_id: conversationId,
+  turn_id: turnId,
+  tool_name: toolName,
+  tool_call_id: toolCallId,
+  phase,
+  status,
+  ...options
+});
+var createSSEToolProcessEvent = (id, conversationId, turnId, toolName, toolCallId, phase, status, options = {}) => ({
+  type: "tool_process",
+  id,
+  timestamp: Date.now(),
+  conversation_id: conversationId,
+  turn_id: turnId,
+  tool_name: toolName,
+  tool_call_id: toolCallId,
+  phase,
+  status,
+  ...options
+});
+var createSSEToolOutputEvent = (id, conversationId, turnId, toolName, toolCallId, status, output, options = {}) => ({
+  type: "tool_output",
+  id,
+  timestamp: Date.now(),
+  conversation_id: conversationId,
+  turn_id: turnId,
+  tool_name: toolName,
+  tool_call_id: toolCallId,
+  status,
+  output,
+  ...options
+});
+var createSSETodoUpdatedEvent = (id, conversationId, turnId, todoListId, todoListVersion, items, options = {}) => ({
+  type: "todo_updated",
+  id,
+  timestamp: Date.now(),
+  conversation_id: conversationId,
+  turn_id: turnId,
+  todo_list_id: todoListId,
+  todo_list_version: todoListVersion,
+  items,
+  ...options
+});
+var createSSESubRunTraceEvent = (id, conversationId, turnId, parentToolCallId, subrunId, kind, options = {}) => ({
+  type: "subrun_trace",
+  id,
+  timestamp: Date.now(),
+  conversation_id: conversationId,
+  turn_id: turnId,
+  parent_tool_call_id: parentToolCallId,
+  subrun_id: subrunId,
+  kind,
+  ...options
+});
+var createSSERequiresUserInteractionEvent = (id, conversationId, turnId, options = {}) => ({
+  type: "requires_user_interaction",
+  id,
+  timestamp: Date.now(),
+  conversation_id: conversationId,
+  turn_id: turnId,
+  ...options
+});
+var createSSEErrorEvent = (id, conversationId, turnId, error, options = {}) => ({
+  type: "error",
+  id,
+  timestamp: Date.now(),
+  conversation_id: conversationId,
+  turn_id: turnId,
+  error,
+  ...options
+});
+var createSSEStreamEndEvent = (id, conversationId, turnId, options = {}) => ({
+  type: "stream_end",
+  id,
+  timestamp: Date.now(),
+  conversation_id: conversationId,
+  turn_id: turnId,
+  ...options
+});
+var createSSEHistorySummaryEvent = (id, conversationId, turnId, summaryId, content, originalMessageCount, summarySeq, options = {}) => ({
+  type: "history_summary",
+  id,
+  timestamp: Date.now(),
+  conversation_id: conversationId,
+  turn_id: turnId,
+  summary_id: summaryId,
+  content,
+  original_message_count: originalMessageCount,
+  summary_seq: summarySeq,
+  ...options
+});
+
+export { AUDIT_ACTIONS, AUDIT_DECISION_OUTCOMES, AgentCapability, AgentSpec, AgentSpecAuditConfig, AgentSpecBudgetPolicy, AgentSpecCheckpointPolicy, AgentSpecContextPolicy, AgentSpecContextTracePolicy, AgentSpecMessageType, AgentSpecModelHints, AgentSpecMustKeepPolicy, AgentSpecMustKeepTruncationRule, AgentSpecProviderReplayPolicy, AgentSpecReasoningRetentionPolicy, AgentSpecSummarizationPolicy, AgentSpecSystemReminderExtraRule, AgentSpecSystemReminderPolicy, AgentSpecSystemReminderTrigger, AgentSpecTokenEstimationPolicy, AgentSpecToolHistoryPolicy, AgentSpecToolObservationGovernancePolicy, AgentSpecToolOutputPolicy, AgentSpecWorkingMemoryPolicy, AgentTodoItem, AgentTodoStatus, AiMessage, AssistantMessage, AuditActor, AuditCostDelta, AuditDecision, AuditEnvelope, AuditEvidence, AuditScope, BaseEvent, BaseSSEEvent, DEFAULT_MAX_STEPS, EventEnvelope, ExecutionTraceContext, HistorySummaryMeta, ImageInfoMeta, PersistentMetadata, ProviderReasoningDetails, ProviderReasoningDetailsPayload, RuntimeEvent, SSEErrorEvent, SSEEvent, SSEFinalAnswerChunkEvent, SSEFinalAnswerEvent, SSEHistorySummaryEvent, SSEMarkdownChunkEvent, SSERequiresUserInteractionEvent, SSEStreamEndEvent, SSESubRunTraceEvent, SSESummarizationEndEvent, SSESummarizationErrorEvent, SSESummarizationStartEvent, SSEThoughtEvent, SSETodoUpdatedEvent, SSEToolCallDecisionEvent, SSEToolOutputEvent, SSEToolProcessEvent, SYSTEM_REMINDER_BUILTIN_TRIGGER_KINDS, Status, SystemMessage, TaskTrackingMeta, ToolBindingSpec, ToolCallDecisionPayload, ToolCallExtraContent, ToolCallPhase, ToolCallWire, ToolCallsMeta, ToolMessage, ToolOutputMeta, UserMessage, createAssistantMessage, createAuditEnvelopeEvent, createErrorEvent, createFinalAnswerChunkEvent, createFinalAnswerEvent, createHistorySummaryEvent, createHistorySummaryMessage, createSSEErrorEvent, createSSEFinalAnswerChunkEvent, createSSEFinalAnswerEvent, createSSEHistorySummaryEvent, createSSEMarkdownChunkEvent, createSSERequiresUserInteractionEvent, createSSEStreamEndEvent, createSSESubRunTraceEvent, createSSEThoughtEvent, createSSETodoUpdatedEvent, createSSEToolCallDecisionEvent, createSSEToolOutputEvent, createSSEToolProcessEvent, createStreamEndEvent, createSubRunTraceEvent, createSystemMessage, createThoughtEvent, createTodoUpdatedEvent, createToolCallDecisionEvent, createToolMessage, createToolOutputEvent, createToolProcessEvent, createUserInputEvent, createUserMessage, defineContextPolicy, hasToolCalls, isAssistantMessage, isHistorySummaryMessage, isSystemMessage, isToolMessage, isUserMessage, validateAiMessage, validateHistorySummaryMeta, validateRuntimeEvent, validateRuntimeEvents, validateSSEEvent };
+//# sourceMappingURL=contracts.js.map
+//# sourceMappingURL=contracts.js.map