@agent-phonon/protocol 0.9.1 → 0.10.0

package/src/schemas/schedule.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import {SkillSelection} from "./skill.js";
 import { AgentId, ProjectId, SessionId, TenantId } from "./common.js";
 import { WorkflowId, WorkflowPlan } from "./workflow.js";
 
@@ -72,9 +73,17 @@ export type ScheduleTrigger = z.infer<typeof ScheduleTrigger>;
 // Target（到点后要发起的 run 的「配方」）
 // ---------------------------------------------------------------------------
 
+export const ScheduleDispatch = z.object({
+  key: z.string().min(1).max(255),
+  revision: z.number().int().positive(),
+  contentHash: z.string().regex(/^[a-f0-9]{64}$/),
+  expiresAt: z.string().datetime({ offset: true }).optional(),
+});
+export type ScheduleDispatch = z.infer<typeof ScheduleDispatch>;
+
 export const ScheduleTarget = z.object({
   /** 复用 L1 session 还是 L3 workflow。 */
-  runKind: z.enum(["session", "workflow"]).default("session"),
+  runKind: z.enum(["session", "workflow", "dispatch"]).default("session"),
   /** 必须绑定 project（与 session.create 一致）。 */
   project: ProjectId,
   /** runKind=session：用哪个 agent。 */
@@ -85,8 +94,11 @@ export const ScheduleTarget = z.object({
   /** runKind=workflow：L3 plan。 */
   plan: WorkflowPlan.optional(),
   agentConfig: z.record(z.unknown()).optional(),
-  skills: z.array(z.string()).optional(),
-});
+  skills: z.array(SkillSelection).max(16).optional(),
+  /** A durable handoff to an authorizing controller; never launches a model. */
+  dispatch: ScheduleDispatch.optional(),
+}).refine(value => value.runKind === "dispatch" ? !!value.dispatch && !value.agent && !value.plan && !value.agentConfig : !value.dispatch,
+  { message: "dispatch targets require a dispatch identity and cannot contain executable agent configuration" });
 export type ScheduleTarget = z.infer<typeof ScheduleTarget>;
 
 // ---------------------------------------------------------------------------
@@ -161,12 +173,26 @@ export type RunStatus = z.infer<typeof RunStatus>;
 export const RunTriggerSource = z.enum(["cron", "webhook", "manual"]);
 export type RunTriggerSource = z.infer<typeof RunTriggerSource>;
 
+export const RunRetryAttempt = z.object({
+  /** 失败的是第几次尝试（从 1 开始）。 */
+  attempt: z.number().int().positive(),
+  at: z.string(),
+  phase: z.enum(["launch", "runtime"]),
+  error: z.string(),
+});
+export type RunRetryAttempt = z.infer<typeof RunRetryAttempt>;
+
 export const Run = z.object({
   id: RunId,
   scheduleId: ScheduleId,
   tenantId: TenantId,
   triggerSource: RunTriggerSource,
   status: RunStatus,
+  /** Non-sensitive execution-kind marker, retained even in status-only pushes. */
+  controllerDispatch: z.literal(true).optional(),
+  dispatch: ScheduleDispatch.optional(),
+  /** Frozen trigger data for controller dispatch; never an instruction/approval. */
+  input: z.union([z.string(), z.record(z.unknown())]).optional(),
   /** runKind=session：对应的 L1 session。 */
   sessionId: SessionId.optional(),
   /** runKind=workflow：对应的 L3 workflow。 */
@@ -180,6 +206,11 @@ export const Run = z.object({
   /** 终态产物文本（summary 推送用）。 */
   resultText: z.string().optional(),
   usage: z.record(z.unknown()).optional(),
+  /** 当前/最终尝试序号；总尝试次数上限恒为 1 + policy.maxRetries。 */
+  attempt: z.number().int().nonnegative().optional(),
+  maxAttempts: z.number().int().positive().optional(),
+  /** 每次触发重试的失败审计。 */
+  retryHistory: z.array(RunRetryAttempt).optional(),
 });
 export type Run = z.infer<typeof Run>;
 
@@ -275,8 +306,12 @@ export const ScheduleTriggerParams = z.object({
   scheduleId: ScheduleId,
   /** 触发来源标记（manual / 测试 cron / 重放 webhook）。默认 manual。 */
   source: RunTriggerSource.optional(),
-  /** 可选：注入到 target.prompt 的输入变量（webhook body 等）。 */
-  input: z.record(z.unknown()).optional(),
+  /**
+   * 可选触发输入。字符串直接注入；对象 JSON 序列化后注入。
+   * session 追加到 target.prompt，workflow 传给 workflow.run.input。
+   * record 形态保留，兼容既有 webhook/manual API。
+   */
+  input: z.union([z.string(), z.record(z.unknown())]).optional(),
   clientRequestId: z.string().optional(),
 });
 export type ScheduleTriggerParams = z.infer<typeof ScheduleTriggerParams>;
@@ -293,6 +328,8 @@ export const ScheduleRunsListParams = z.object({
   scheduleId: ScheduleId,
   status: RunStatus.optional(),
   limit: z.number().int().positive().optional(),
+  /** Drain oldest unacknowledged occurrences without losing an offline backlog. */
+  unackedOnly: z.boolean().optional(),
 });
 export type ScheduleRunsListParams = z.infer<typeof ScheduleRunsListParams>;
 
@@ -310,6 +347,18 @@ export type RunGetParams = z.infer<typeof RunGetParams>;
 export const RunGetResult = z.object({ run: Run });
 export type RunGetResult = z.infer<typeof RunGetResult>;
 
+export const RunResolveParams = z.object({
+  runId: RunId,
+  dispatch: ScheduleDispatch,
+  status: z.enum(["success", "failed", "cancelled", "skipped", "timeout"]),
+  resultText: z.string().max(65536).optional(),
+  error: z.string().max(4000).optional(),
+  clientRequestId: z.string().optional(),
+});
+export type RunResolveParams = z.infer<typeof RunResolveParams>;
+export const RunResolveResult = z.object({ run: Run });
+export type RunResolveResult = z.infer<typeof RunResolveResult>;
+
 // ---- run.events.subscribe / unsubscribe ----
 export const RunEventsSubscribeParams = z.object({
   runId: RunId,

package/src/schemas/session.ts

@@ -1,5 +1,9 @@
 import { z } from "zod";
 import { AgentId, ProjectId, SessionId, Timestamp, Verbosity } from "./common.js";
+import { SessionCompressionControls, CompressionReceipt } from "./compression.js";
+import { TurnReasoning } from "./reasoning.js";
+import { NativeStopTarget } from "./native-stop.js";
+import { SkillSelection } from "./skill.js";
 
 /**
  * L1 Session 协议原语（design §4）。
@@ -82,6 +86,7 @@ export type WhenBusy = z.infer<typeof WhenBusy>;
 
 export const SessionSendParams = z.object({
   sessionId: SessionId,
+  reasoning: TurnReasoning.optional(),
   /** 用户输入 / 任务内容。 */
   input: z.string(),
   /**
@@ -95,19 +100,7 @@ export const SessionSendParams = z.object({
    * phonon 保证：(1) skill 在 agent 能访问到的位置；(2) 上下文注入强制加载指令。
    * 优先级：send 指定 > project skill > global skill。
    */
-  skills: z
-    .array(
-      z.union([
-        z.string(),
-        z.object({
-          name: z.string().min(1),
-          version: z.string().optional(),
-          scope: z.enum(["global", "project"]).optional(),
-          force: z.boolean().optional(),
-        }),
-      ]),
-    )
-    .optional(),
+  skills: z.array(SkillSelection).max(16).optional(),
   /** 可选：覆盖本轮详细度。 */
   verbosity: Verbosity.optional(),
   /**
@@ -123,6 +116,7 @@ export const SessionSendParams = z.object({
   /**
    * 可选：本轮关联 id。phonon 会把该轮所有 stream.event 标上同一 turnId，
    * 调用方据此聚合流式输出。缺省由 phonon 生成并在 ack 中返回。
+   * whenBusy=inject 不创建新轮；如显式提供 turnId，必须等于当前 turn。
    */
   turnId: z.string().optional(),
 });
@@ -138,7 +132,8 @@ export const SessionSendAck = z.object({
    * - started   ：立即开始执行（session 空闲）
    * - queued    ：已排队（whenBusy=queue 且正忙）
    * - interrupted：已中断上一轮并开始本轮（whenBusy=interrupt）
-   * - injected  ：将在下一 tool call 边界插入（whenBusy=inject）
+   * - injected  ：已在当前 turn 的工具边界应用输入（whenBusy=inject），turnId 是当前 turn，不创建新轮。
+   *              未应用前不回 injected；窗口关闭必须拒绝，不能自动排队。
    */
   disposition: z.enum(["started", "queued", "interrupted", "injected"]),
   /** queued 时的队列位置（从 1 起）。 */
@@ -160,6 +155,7 @@ export const SessionInterruptParams = z.object({
 export type SessionInterruptParams = z.infer<typeof SessionInterruptParams>;
 
 export const SessionInterruptResult = z.object({
+  nativeStop:NativeStopTarget.optional(),
   sessionId: SessionId,
   /** 被中断的 turn（若当时有在跑的）。 */
   interruptedTurnId: z.string().optional(),
@@ -191,6 +187,8 @@ export type CompressMode = z.infer<typeof CompressMode>;
 
 export const SessionCompressParams = z.object({
   sessionId: SessionId,
+  clientRequestId: z.string().min(1).max(512).optional(),
+  background: z.boolean().optional(),
   /** native = 透传 agent 原生压缩；custom = phonon 自有压缩引擎。 */
   mode: CompressMode,
   /**
@@ -203,12 +201,11 @@ export const SessionCompressParams = z.object({
 });
 export type SessionCompressParams = z.infer<typeof SessionCompressParams>;
 
-export const SessionCompressResult = z.object({
+// Older devices return only sessionId/mode; receipt-capable devices retain the
+// complete proof through schema parsing, including identity and change counts.
+export const SessionCompressResult = CompressionReceipt.partial().extend({
   sessionId: SessionId,
   mode: CompressMode,
-  /** 压缩前后的 token 估算（若可得）。 */
-  tokensBefore: z.number().int().nonnegative().optional(),
-  tokensAfter: z.number().int().nonnegative().optional(),
   /** 简短摘要/说明。 */
   summary: z.string().optional(),
 });
@@ -273,9 +270,18 @@ export type SessionSwitchModelResult = z.infer<typeof SessionSwitchModelResult>;
 // session.status / session.list  —— 始终携带 agent 身份
 // ---------------------------------------------------------------------------
 export const SessionMeta = z.object({
+  nativeStop:NativeStopTarget.optional(),
+  recovery:z.object({detached:z.boolean(),canAttempt:z.boolean(),reason:z.string().optional()}).strict().optional(),
+  streamNextSeq:z.number().int().nonnegative().safe().optional(),
+  proactive:z.object({supported:z.boolean(),ready:z.boolean(),errorCode:z.string().optional()}).strict().optional(),
+  compression: SessionCompressionControls.optional(),
+  employeeId:z.string().uuid().optional(),
+  employeeRevision:z.number().int().positive().optional(),
   sessionId: SessionId,
   /** 绑定的项目（一等身份，D23）。 */
   project: ProjectId,
+  /** Original worktree binding, retained through status/list/recover parsing. */
+  worktreeId: z.string().optional(),
   /** 绑定的 agent 身份，全程携带。 */
   agent: AgentId,
   model: z.string(),
@@ -316,6 +322,12 @@ export type SessionStatusParams = z.infer<typeof SessionStatusParams>;
 export const SessionStatusResult = SessionMeta;
 export type SessionStatusResult = z.infer<typeof SessionStatusResult>;
 
+/** Reopen a verified, settled native Session. Never sends input or resumes a workflow. */
+export const SessionRecoverParams = z.object({sessionId:SessionId,project:ProjectId,agent:AgentId,model:z.string().min(1)}).strict();
+export type SessionRecoverParams = z.infer<typeof SessionRecoverParams>;
+export const SessionRecoverResult = SessionMeta;
+export type SessionRecoverResult = z.infer<typeof SessionRecoverResult>;
+
 export const SessionListParams = z.object({
   /** 可选：按项目过滤。 */
   project: ProjectId.optional(),

package/src/schemas/skill.ts

@@ -14,6 +14,14 @@ import { AgentId, ProjectId, Timestamp } from "./common.js";
 export const SkillScope = z.enum(["global", "project"]);
 export type SkillScope = z.infer<typeof SkillScope>;
 
+const skillName = z.string().min(1).max(128).regex(/^[A-Za-z0-9._-]+$/).refine(value => value !== "." && value !== "..");
+export const SkillSelection = z.union([
+  skillName,
+  z.object({name:skillName,version:z.string().min(1).max(128).refine(value=>!/[\p{Cc}]/u.test(value)).optional(),scope:SkillScope.optional(),force:z.boolean().optional(),
+    revision:z.string().regex(/^[a-f0-9]{64}$/).optional(),installationId:z.string().uuid().optional()}).strict(),
+]);
+export type SkillSelection = z.infer<typeof SkillSelection>;
+
 /** skill 来源：内联内容、本地路径、或远端引用。 */
 export const SkillSource = z.union([
   z.object({ kind: z.literal("inline"), files: z.record(z.string()) }), // path → content
@@ -57,12 +65,16 @@ export const SkillDescriptor = z.object({
   /** 安装落地路径（设备本地）。 */
   installedPath: z.string().optional(),
   installedAt: Timestamp.optional(),
+  revision:z.string().regex(/^[a-f0-9]{64}$/).optional(),
+  publication:z.object({kind:z.literal("immutable"),versionId:z.string().uuid(),treeHash:z.string().regex(/^[a-f0-9]{64}$/)}).strict().optional(),
 });
 export type SkillDescriptor = z.infer<typeof SkillDescriptor>;
 
 // --- skill.install ---
 export const SkillInstallParams = z
   .object({
+    /** Exact parsed request identity; changed payloads cannot reuse a confirmed receipt. */
+    clientRequestId: z.string().min(1).max(512).optional(),
     /** 目标 agent。 */
     agent: AgentId,
     name: z.string().min(1),
@@ -82,9 +94,47 @@ export const SkillInstallResult = z.object({
 });
 export type SkillInstallResult = z.infer<typeof SkillInstallResult>;
 
+export const SkillPublishParams=z.object({clientRequestId:z.string().min(1).max(512),agent:AgentId,name:skillName,scope:z.literal("project").default("project"),projectId:ProjectId,
+  baseRevision:z.string().regex(/^[a-f0-9]{64}$/).nullable(),expectedReceiverID:z.string().uuid().optional(),source:z.union([SkillSource.options[0],SkillSource.options[1]])}).strict();
+export type SkillPublishParams=z.infer<typeof SkillPublishParams>;
+export const SkillUnpublishParams=z.object({clientRequestId:z.string().min(1).max(512),agent:AgentId,name:skillName,scope:z.literal("project").default("project"),projectId:ProjectId,
+  baseRevision:z.string().regex(/^[a-f0-9]{64}$/)}).strict();
+export type SkillUnpublishParams=z.infer<typeof SkillUnpublishParams>;
+export const SkillUnpublishResult=z.object({projectId:ProjectId,name:skillName,deactivated:z.literal(true),previousRevision:z.string().regex(/^[a-f0-9]{64}$/)}).strict();
+export type SkillUnpublishResult=z.infer<typeof SkillUnpublishResult>;
+
+export const SkillInstallStatusParams = z.object({
+  clientRequestId:z.string().min(1).max(512),agent:AgentId,name:z.string().min(1).max(255),scope:SkillScope,projectId:ProjectId.optional(),
+  includeReceiverIdentity:z.literal(true).optional(),
+  includeRecoveryContext:z.literal(true).optional(),
+}).strict().refine(value=>value.scope==="project"?!!value.projectId:value.projectId===undefined,{message:"Project scope requires projectId; global scope excludes it"});
+export type SkillInstallStatusParams = z.infer<typeof SkillInstallStatusParams>;
+export const SkillInstallRecoveryContext=z.object({revision:z.string().regex(/^[a-f0-9]{64}$/),receiverID:z.string().uuid(),originalReceiverID:z.string().uuid().nullable(),
+  fenced:z.boolean(),fenceID:z.string().uuid().optional()}).strict().refine(value=>value.fenced===!!value.fenceID);
+export type SkillInstallRecoveryContext=z.infer<typeof SkillInstallRecoveryContext>;
+const installStatusIdentity={clientRequestId:z.string().min(1).max(512),createdAt:Timestamp,updatedAt:Timestamp,receiverID:z.string().uuid().optional(),recovery:SkillInstallRecoveryContext.optional()};
+export const SkillInstallStatusResult = z.discriminatedUnion("state",[
+  z.object({clientRequestId:z.string().min(1).max(512),state:z.literal("not_found"),found:z.literal(false),outcomeKnown:z.literal(false)}).strict(),
+  z.object({...installStatusIdentity,state:z.literal("prepared"),found:z.literal(true),outcomeKnown:z.literal(false),dispatchClaimed:z.literal(false)}).strict(),
+  z.object({...installStatusIdentity,state:z.literal("dispatched"),found:z.literal(true),outcomeKnown:z.literal(false),dispatchClaimed:z.literal(true)}).strict(),
+  z.object({...installStatusIdentity,state:z.literal("unknown"),found:z.literal(true),outcomeKnown:z.literal(false),dispatchClaimed:z.literal(true),reasonCode:z.enum(["write_outcome_unconfirmed","controller_not_observed"])}).strict(),
+  z.object({...installStatusIdentity,state:z.literal("failed"),found:z.literal(true),outcomeKnown:z.literal(true),dispatchClaimed:z.literal(false),reasonCode:z.literal("preparation_failed")}).strict(),
+  z.object({...installStatusIdentity,state:z.literal("confirmed"),found:z.literal(true),outcomeKnown:z.literal(true),dispatchClaimed:z.literal(true),result:SkillInstallResult}).strict(),
+]);
+export type SkillInstallStatusResult = z.infer<typeof SkillInstallStatusResult>;
+
+export const SkillInstallFenceParams=z.object({clientRequestId:z.string().min(1).max(512),originalRequestId:z.string().min(1).max(512),agent:AgentId,
+  name:z.string().min(1).max(255),scope:z.literal("project").default("project"),projectId:ProjectId,expectedReceiverID:z.string().uuid(),baseRecoveryRevision:z.string().regex(/^[a-f0-9]{64}$/)}).strict();
+export type SkillInstallFenceParams=z.infer<typeof SkillInstallFenceParams>;
+export const SkillInstallFenceResult=z.object({clientRequestId:z.string().min(1).max(512),originalRequestId:z.string().min(1).max(512),agent:AgentId,
+  name:z.string().min(1).max(255),scope:z.literal("project"),projectId:ProjectId,receiverID:z.string().uuid(),originalReceiverID:z.string().uuid().nullable(),fenceID:z.string().uuid(),
+  disposition:z.literal("unconfirmed_metadata_fenced"),outcomeKnown:z.literal(false),targetLocked:z.literal(true),filesDeleted:z.literal(false),originalWritesMayContinue:z.literal(true),recordedAt:Timestamp}).strict();
+export type SkillInstallFenceResult=z.infer<typeof SkillInstallFenceResult>;
+
 // --- skill.uninstall ---
 export const SkillUninstallParams = z
   .object({
+    clientRequestId: z.string().optional(),
     agent: AgentId,
     name: z.string().min(1),
     scope: SkillScope,
@@ -142,6 +192,8 @@ export const SkillDirectoryDescriptor = z.object({
   /** skill 目录真实本机路径。 */
   path: z.string().min(1),
   exists: z.boolean(),
+  active:z.boolean().optional(),
+  publication:SkillDescriptor.shape.publication,
 });
 export type SkillDirectoryDescriptor = z.infer<typeof SkillDirectoryDescriptor>;
 

package/src/schemas/stream.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { SessionId, Timestamp } from "./common.js";
+import { ReasoningConfirmation } from "./reasoning.js";
 
 /**
  * 流式事件（design §4 / §6 / 订阅模型）——phonon → server 异步推送。
@@ -27,6 +28,7 @@ export type StreamOrigin = z.infer<typeof StreamOrigin>;
 
 /** 事件种类。 */
 export const StreamEventType = z.enum([
+  "runtime_settings",
   "message", // 一条完整/增量消息文本
   "thinking", // 思考过程（trace 档）
   "tool_call", // agent 发起工具调用
@@ -48,6 +50,10 @@ const StreamEventBase = z.object({
   origin: StreamOrigin.default("solicited"),
   /** unsolicited 时的冲泡来源标签，如 "cron" / "scheduled" / "heartbeat"。 */
   source: z.string().optional(),
+  /** Native harness output identity; not a caller-selected conversation or sender. */
+  sourceEventId:z.string().min(1).max(255).optional(),
+  nativeProactive:z.object({anchorRunId:z.string().uuid(),employeeId:z.string().uuid(),employeeRevision:z.number().int().positive(),
+    upstreamId:z.string().min(1).max(255),project:z.string().min(1).max(512),agent:z.string().min(1).max(255),model:z.string().min(1).max(255)}).strict().optional(),
   /** 单调递增序号（按 session），保证调用方可排序/去重。 */
   seq: z.number().int().nonnegative(),
   at: Timestamp,
@@ -60,6 +66,8 @@ const StreamEventBase = z.object({
   workflowId: z.string().optional(),
   nodeId: z.string().optional(),
   role: z.string().optional(),
+  /** Server-generated native conversation run correlation, stamped by core. */
+  nativeRunId: z.string().uuid().optional(),
 });
 
 export const StreamMessageEvent = StreamEventBase.extend({
@@ -99,6 +107,11 @@ export const StreamTokenEvent = StreamEventBase.extend({
   text: z.string(),
 });
 
+export const StreamRuntimeSettingsEvent = StreamEventBase.extend({
+  type: z.literal("runtime_settings"),
+  agent: z.string(), model: z.string(), reasoning: ReasoningConfirmation,
+});
+
 export const StreamResultEvent = StreamEventBase.extend({
   type: z.literal("result"),
   /** 本轮最终文本结果。 */
@@ -135,18 +148,24 @@ export const StreamErrorEvent = StreamEventBase.extend({
 
 // ---------------------------------------------------------------------------
 // stream.ack —— server → phonon，确认已收到 seq <= lastSeq（P0-4）
-// 让 phonon 能清理 outbox / 控制背压；可按 session 粒度或全局。
+// 让 phonon 能清理 outbox / 控制背压。seq 是 per-session，ACK 必须带 sessionId。
 // ---------------------------------------------------------------------------
 export const StreamAckParams = z.object({
-  /** 按 session 确认；缺省表示该连接全局。 */
-  sessionId: SessionId.optional(),
+  /** 必须按 session 确认；单一标量无法安全表达连接全局水位。 */
+  sessionId: SessionId,
   /** 已收到的最大连续 seq（含）；phonon 可清理 <= 此值的 outbox。 */
   lastSeq: z.number().int().nonnegative(),
 });
 export type StreamAckParams = z.infer<typeof StreamAckParams>;
 
+export const StreamReplayParams = z.object({ sessionId: SessionId, fromSeq: z.number().int().nonnegative().default(0), limit: z.number().int().min(1).max(1000).default(200) });
+export type StreamReplayParams = z.infer<typeof StreamReplayParams>;
+export const StreamReplayResult = z.object({ sessionId: SessionId, replayed: z.number().int().nonnegative(), nextSeq: z.number().int().nonnegative().optional() });
+export type StreamReplayResult = z.infer<typeof StreamReplayResult>;
+
 /** 流式事件联合体（phonon → server，方法名 stream.event）。 */
 export const StreamEvent = z.discriminatedUnion("type", [
+  StreamRuntimeSettingsEvent,
   StreamMessageEvent,
   StreamThinkingEvent,
   StreamToolCallEvent,

package/src/schemas/workflow.ts

@@ -1,5 +1,8 @@
 import { z } from "zod";
+import { NativeStopProof } from "./native-stop.js";
 import { AgentId, ProjectId, SessionId, Timestamp } from "./common.js";
+import { TurnReasoning } from "./reasoning.js";
+import { SkillSelection } from "./skill.js";
 
 /**
  * L3 Orchestration Protocol (workflow.*)
@@ -37,6 +40,8 @@ export const WorkflowNode = z.object({
   nodeId: WorkflowNodeId,
   agent: AgentId,
   model: ModelId,
+  reasoning: TurnReasoning.optional(),
+  skills: z.array(SkillSelection).max(16).optional(),
   /** 该节点在 workflow 中扮演的角色（由调用方定义，phonon 仅回显）。 */
   role: WorkflowRoleId.optional(),
   input: z.string().optional(),
@@ -154,6 +159,7 @@ export type WorkflowPlan = z.infer<typeof WorkflowPlan>;
 export const WorkflowStatus = z.enum([
   "queued",
   "running",
+  "paused",
   "completed",
   "failed",
   "cancelled",
@@ -165,6 +171,7 @@ export const WorkflowNodeStatus = z.enum([
   "pending",
   "ready",
   "running",
+  "paused",
   "completed",
   "failed",
   "skipped",
@@ -211,6 +218,8 @@ export type WorkflowSharedContext = z.infer<typeof WorkflowSharedContext>;
 export const WorkflowResumeFrom = z.object({
   /** 要恢复的 workflowId（必须先前 run 过，并有 checkpoint）。 */
   workflowId: WorkflowId,
+  /** Reject a fresh resume if the observed native event cursor has changed. */
+  expectedSeq:z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER).optional(),
   /**
    * 起点策略：
    * - "last_success_dependents" : 从最后成功节点的下游开始（DAG 默认）
@@ -218,6 +227,7 @@ export const WorkflowResumeFrom = z.object({
    * - "node:<nodeId>"            : 显式指定从某 node 开始
    */
   strategy: z.union([
+    z.literal("continue"),
     z.literal("last_success_dependents"),
     z.literal("failed_node"),
     z.string().regex(/^node:/),
@@ -234,6 +244,7 @@ export type WorkflowResumeFrom = z.infer<typeof WorkflowResumeFrom>;
 export const WorkflowResumeParams = z.object({
   workflowId: WorkflowId,
   strategy: z.union([
+    z.literal("continue"),
     z.literal("last_success_dependents"),
     z.literal("failed_node"),
     z.string().regex(/^node:/),
@@ -317,6 +328,17 @@ export const WorkflowNodeRuntime = z.object({
   result: WorkflowNodeResult.optional(),
   /** 该节点完成的轮次计数（discussion 用；DAG/Graph 一次执行 = 1）。 */
   iterations: z.number().int().nonnegative().optional(),
+  /** 每次执行的 session/turn 映射；用于崩溃恢复、审计和 late-event fencing。 */
+  attempts: z.array(z.object({
+    attempt: z.number().int().positive(),
+    iteration: z.number().int().positive().optional(),
+    sessionId: SessionId.optional(),
+    turnId: TurnId.optional(),
+    status: z.enum(["running", "completed", "failed", "interrupted", "timeout", "cancelled"]),
+    startedAt: Timestamp,
+    completedAt: Timestamp.optional(),
+    error: z.string().optional(),
+  })).optional(),
 });
 export type WorkflowNodeRuntime = z.infer<typeof WorkflowNodeRuntime>;
 
@@ -327,7 +349,24 @@ export type WorkflowNodeRuntime = z.infer<typeof WorkflowNodeRuntime>;
 export const WorkflowStatusParams = z.object({ workflowId: WorkflowId });
 export type WorkflowStatusParams = z.infer<typeof WorkflowStatusParams>;
 
+export const WorkflowInputParams=z.object({workflowId:WorkflowId.max(512),nodeId:WorkflowNodeId.max(512),
+  sessionId:SessionId,turnId:TurnId.max(512),inputId:ClientRequestId.max(255),input:z.string().min(1).max(16000).refine(value=>!!value.trim())}).strict();
+export type WorkflowInputParams=z.infer<typeof WorkflowInputParams>;
+export const WorkflowInputStatusParams=z.object({workflowId:WorkflowId.max(512),inputId:ClientRequestId.max(255)}).strict();
+export type WorkflowInputStatusParams=z.infer<typeof WorkflowInputStatusParams>;
+export const WorkflowInputReceipt=z.object({workflowId:WorkflowId,nodeId:WorkflowNodeId,sessionId:SessionId,turnId:TurnId,
+  inputId:ClientRequestId,contentHash:z.string().regex(/^[a-f0-9]{64}$/),state:z.enum(['inserting','inserted','unknown']),
+  createdAt:Timestamp,updatedAt:Timestamp,errorCode:z.string().max(120).optional()}).strict();
+export type WorkflowInputReceipt=z.infer<typeof WorkflowInputReceipt>;
+export const WorkflowInputStatusResult=z.discriminatedUnion('found',[
+  z.object({found:z.literal(false),workflowId:WorkflowId,inputId:ClientRequestId}).strict(),
+  z.object({found:z.literal(true),receipt:WorkflowInputReceipt}).strict(),
+]);
+export type WorkflowInputStatusResult=z.infer<typeof WorkflowInputStatusResult>;
+
 export const WorkflowStatusResult = z.object({
+  nativeStop:NativeStopProof.optional(),
+  dispatchKey: z.string().optional(),
   workflowId: WorkflowId,
   status: WorkflowStatus,
   /** workflow 默认 project；v0.6 起可选。 */
@@ -344,12 +383,51 @@ export const WorkflowStatusResult = z.object({
 });
 export type WorkflowStatusResult = z.infer<typeof WorkflowStatusResult>;
 
+const ResultVersion = z.string().regex(/^[a-f0-9]{64}$/);
+export const WorkflowResultParams = z.object({
+  workflowId: WorkflowId,
+  nodeId: WorkflowNodeId.optional(),
+  offset: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER).default(0),
+  version: ResultVersion.optional(),
+  knownVersion: ResultVersion.optional(),
+}).strict();
+export type WorkflowResultParams = z.infer<typeof WorkflowResultParams>;
+export const WorkflowResultPage = z.object({
+  workflowId: WorkflowId,
+  project: ProjectId.optional(),
+  nodeId: WorkflowNodeId.optional(),
+  status: WorkflowStatus,
+  version: ResultVersion,
+  offset: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
+  end: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
+  totalLength: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
+  text: z.string().max(16000).optional(),
+  omitted: z.literal(true).optional(),
+}).strict().superRefine((value, ctx) => {
+  if (value.end < value.offset || value.end > value.totalLength || value.end - value.offset > 16000
+    || value.end < value.totalLength && value.end === value.offset
+    || (value.omitted === true ? value.text !== undefined : value.text === undefined || value.text.length !== value.end - value.offset)) {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Invalid workflow result page' });
+  }
+});
+export type WorkflowResultPage = z.infer<typeof WorkflowResultPage>;
+
 export const WorkflowCancelParams = z.object({ workflowId: WorkflowId, reason: z.string().optional() });
 export type WorkflowCancelParams = z.infer<typeof WorkflowCancelParams>;
-export const WorkflowCancelResult = z.object({ workflowId: WorkflowId, status: z.literal("cancelled") });
+export const WorkflowDispatchCancelParams=z.object({ dispatchKey:z.string().min(1).max(255),project:ProjectId,reason:z.string().max(1000).optional() });
+export type WorkflowDispatchCancelParams=z.infer<typeof WorkflowDispatchCancelParams>;
+export const WorkflowDispatchCancelResult=z.object({ dispatchKey:z.string(),workflowId:WorkflowId.optional(),status:WorkflowStatus,cancelledBeforeStart:z.boolean(),nativeStop:NativeStopProof.optional() });
+export type WorkflowDispatchCancelResult=z.infer<typeof WorkflowDispatchCancelResult>;
+export const WorkflowCancelResult = z.object({ workflowId: WorkflowId, status: WorkflowStatus,nativeStop:NativeStopProof.optional() });
 export type WorkflowCancelResult = z.infer<typeof WorkflowCancelResult>;
 
+export const WorkflowPauseParams = z.object({ workflowId: WorkflowId, reason: z.string().optional() });
+export type WorkflowPauseParams = z.infer<typeof WorkflowPauseParams>;
+export const WorkflowPauseResult = z.object({ workflowId: WorkflowId, status: z.literal("paused") });
+export type WorkflowPauseResult = z.infer<typeof WorkflowPauseResult>;
+
 export const WorkflowListParams = z.object({
+  dispatchKey: z.string().optional(),
   status: WorkflowStatus.optional(),
   projectId: ProjectId.optional(),
   since: Timestamp.optional(),
@@ -371,6 +449,7 @@ export type WorkflowListResult = z.infer<typeof WorkflowListResult>;
 // ---------------------------------------------------------------------------
 
 export const WorkflowEvent = z.object({
+  nativeStop:NativeStopProof.optional(),
   workflowId: WorkflowId,
   seq: z.number().int().nonnegative(),
   type: z.enum([
@@ -392,6 +471,8 @@ export const WorkflowEvent = z.object({
   agent: AgentId.optional(),
   model: ModelId.optional(),
   role: WorkflowRoleId.optional(),
+  /** Scheduling/orchestration correlation metadata. */
+  metadata: z.record(z.unknown()).optional(),
   status: z.union([WorkflowStatus, WorkflowNodeStatus]).optional(),
   result: WorkflowNodeResult.optional(),
   /** 自由载荷。常见字段：iteration, from, to, reason, terminationReason 等。 */