@agent-phonon/protocol 0.9.1 → 0.10.0

package/src/schemas/conversation-message.ts

@@ -0,0 +1,46 @@
+import { z } from "zod";
+import { SessionId } from "./common.js";
+
+const id = z.string().uuid().transform(value => value.toLowerCase());
+const members = z.object({ operation: z.literal("members") }).strict();
+const order=z.string().regex(/^(0|[1-9][0-9]{0,18})$/).refine(value=>/^(0|[1-9][0-9]{0,18})$/.test(value)&&BigInt(value)<=9223372036854775807n);
+const history=z.object({operation:z.literal("history"),beforeOrder:order.optional(),throughOrder:order.optional(),limit:z.number().int().min(1).max(40).optional()}).strict();
+const read=z.object({operation:z.literal("read"),messageID:id,offset:z.number().int().min(0).max(2147483646).optional()}).strict();
+const send = z.object({ operation: z.literal("send"), requestId: id,
+  text: z.string().max(4000),
+  mentionIDs: z.array(id).min(1).max(8), mode: z.enum(["insert", "wait", "queue"]),
+  attachmentIDs:z.array(z.string().regex(/^native-file:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/)).max(5).optional()
+    .describe("Explicit immutable files already published in this conversation/project. At most five files and 25 MiB. Use serverRef, never device paths or URLs. Recorded does not prove recipient file delivery."),
+}).strict();
+const status = z.object({ operation: z.literal("status"), requestId: id }).strict();
+const distinct = (value: { operation: string; text?:string;mentionIDs?: string[];attachmentIDs?:string[] }) =>
+  value.operation !== "send" || new Set(value.mentionIDs).size === value.mentionIDs?.length
+    &&new Set(value.attachmentIDs).size===(value.attachmentIDs?.length??0)
+    &&(!!value.text?.trim()||!!value.attachmentIDs?.length);
+/** Agent-authored content only; current conversation and sender are controller-owned. */
+export const AgentMessageInput = z.discriminatedUnion("operation", [members, history, read, send, status]).refine(distinct);
+export type AgentMessageInput = z.infer<typeof AgentMessageInput>;
+const lineage = { nativeRunId: id, workflowId: z.string().min(1).max(512), sessionId: SessionId, turnId: z.string().min(1).max(512) };
+export const ConversationMessageParams = z.discriminatedUnion("operation", [
+  members.extend(lineage).strict(), history.extend(lineage).strict(),read.extend(lineage).strict(),send.extend(lineage).strict(), status.extend(lineage).strict(),
+]).refine(distinct);
+export type ConversationMessageParams = z.infer<typeof ConversationMessageParams>;
+const receipt = z.object({ personID: id, state: z.enum(["recorded", "sending", "pendingInsert", "waiting", "queued", "accepted", "running", "succeeded", "removed", "unsupported", "notAccepted", "offline", "failed", "unknown", "cancelled"]), errorCode: z.string().max(128).optional() }).strict();
+const historyMessage=z.object({id,historyOrder:order,author:z.enum(["human","assistant","system"]),senderID:z.string().max(512),senderName:z.string().max(240),
+  createdAt:z.string().datetime({offset:true}),text:z.string().max(12000),textLength:z.number().int().nonnegative(),isExcerpt:z.boolean(),mentionIDs:z.array(id).max(32),
+  originKind:z.string().max(128).optional(),attachmentIDs:z.array(z.string().regex(/^native-(file|result):[0-9a-f-]{36}$/)).max(5),
+  runID:id.optional(),workflowID:id.optional(),requestID:id.optional()}).strict();
+export const ConversationMessageResult = z.discriminatedUnion("status", [
+  z.object({status:z.literal("history"),conversationID:id,projectID:id,throughOrder:order,messages:z.array(historyMessage).max(40),nextBeforeOrder:order.optional()}).strict(),
+  z.object({status:z.literal("message"),conversationID:id,projectID:id,message:historyMessage,offset:z.number().int().nonnegative(),nextOffset:z.number().int().positive().optional()}).strict(),
+  z.object({ status: z.literal("members"), conversationID: id, projectID: id, senderID: id, enabled: z.boolean(),
+    members: z.array(z.object({ id, name: z.string().max(120) }).strict()).max(32),
+    limits: z.object({ maxHops: z.number().int().positive(), maxDeliveries: z.number().int().positive(), maxRecipients: z.number().int().positive(), maxRoots: z.number().int().positive() }).strict(),
+  }).strict(),
+  z.object({ status: z.literal("recorded"), requestId: id, messageID: id, chainID: id, rootMessageID: id,
+    depth: z.number().int().positive().max(12), receipts: z.array(receipt).max(8), replayed: z.boolean().optional(),
+  }).strict(),
+  z.object({ status: z.literal("not_found"), requestId: id }).strict(),
+  z.object({ status: z.literal("not_accepted"), requestId: id, errorCode: z.string().min(1).max(128) }).strict(),
+]);
+export type ConversationMessageResult = z.infer<typeof ConversationMessageResult>;

package/src/schemas/conversation-workflow.ts

@@ -0,0 +1,62 @@
+import { z } from "zod";
+import { TurnReasoning } from "./reasoning.js";
+import { SessionId } from "./common.js";
+import { SkillSelection } from "./skill.js";
+
+export const ConversationWorkflowSkill=SkillSelection.options[1].pick({name:true,version:true,revision:true,installationId:true})
+  .required({revision:true,installationId:true});
+export const ConversationWorkflowSkills=z.array(ConversationWorkflowSkill).min(1).max(16)
+  .refine(values=>new Set(values.map(value=>value.name)).size===values.length,"Duplicate skill name");
+const skillTarget=z.object({agentID:z.string().uuid(),bindingID:z.string().uuid()}).strict();
+const canvasSkill=z.object({productID:z.string().regex(/^[A-Za-z0-9_-]{1,128}$/),deviceBindingID:z.string().regex(/^[A-Za-z0-9_-]{1,128}$/),
+  baseBindingRevision:z.string().uuid(),operationID:z.string().uuid()}).strict();
+
+export const ConversationWorkflowNode=z.object({
+  id:z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/),title:z.string().min(1).max(240),
+  agentID:z.string().uuid(),roleID:z.string().uuid().optional(),bindingID:z.string().uuid(),
+  input:z.string().min(1).max(12000),dependsOn:z.array(z.string().max(64)).max(16).default([]),
+  attachmentIDs:z.array(z.string().regex(/^native-file:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/)).max(5).optional().describe("Explicit existing input file IDs from this conversation and execution project, never device paths. Files are verified on the actual worker device before dispatch."),
+  artifactSources:z.array(z.string().max(64)).max(16).optional().describe("Direct dependency node IDs whose published files must be transferred to this worker. No implicit forwarding. Combined inputs are capped at five files and 25 MiB."),
+  reasoning:TurnReasoning.optional(),
+  skills:ConversationWorkflowSkills.optional().describe("Exact immutable Project skill selections from catalog skillTarget. No global scope, device path or permission override. Pins are part of the frozen plan and human review."),
+  canvasSkill:canvasSkill.optional().describe("Current Canvas product/association and recorded installation references. Uses the post-install binding revision. The controller checks fresh business authority and receipt/source identity; no credentials, source paths or approvals are accepted."),
+}).strict();
+export const ConversationWorkflowPlan=z.object({
+  projectID:z.string().uuid(),title:z.string().min(1).max(240),goal:z.string().min(1).max(4000),
+  review:z.enum(["request","not_requested"]),maxParallel:z.number().int().min(1).max(4).default(2),
+  nodes:z.array(ConversationWorkflowNode).min(1).max(16),
+}).strict().superRefine((plan,ctx)=>{
+  const nodes=new Map(plan.nodes.map(node=>[node.id,node]));
+  if(nodes.size!==plan.nodes.length){ctx.addIssue({code:"custom",message:"Duplicate node"});return;}
+  const visited=new Set<string>(),active=new Set<string>();
+  const visit=(id:string):boolean=>{
+    if(active.has(id)||!nodes.has(id))return false;
+    if(visited.has(id))return true;
+    active.add(id);
+    const node=nodes.get(id)!;
+    if(node.canvasSkill&&(node.skills?.length===16||node.skills?.some(skill=>skill.name==="product-intent-canvas")))return false;
+    if(new Set(node.attachmentIDs).size!==(node.attachmentIDs?.length??0)||new Set(node.artifactSources).size!==(node.artifactSources?.length??0)||node.artifactSources?.some(source=>!node.dependsOn.includes(source)))return false;
+    if(new Set(node.dependsOn).size!==node.dependsOn.length||node.dependsOn.some(dependency=>!visit(dependency)))return false;
+    active.delete(id);visited.add(id);return true;
+  };
+  if(plan.nodes.some(node=>!visit(node.id)))ctx.addIssue({code:"custom",message:"Dependencies must form a DAG"});
+});
+export type ConversationWorkflowPlan=z.infer<typeof ConversationWorkflowPlan>;
+export const AgentWorkflowInput=z.discriminatedUnion("operation",[
+  z.object({operation:z.literal("catalog"),projectID:z.string().uuid().optional(),offset:z.number().int().nonnegative().safe().optional(),skillTarget:skillTarget.optional()}).strict(),
+  z.object({operation:z.literal("execute"),requestId:z.string().uuid(),replacesRequestId:z.string().uuid().optional(),delivery:z.enum(["wait","detached"]).optional(),plan:ConversationWorkflowPlan}).strict(),
+  z.object({operation:z.literal("status"),requestId:z.string().uuid(),nodeID:z.string().max(64).optional(),offset:z.number().int().nonnegative().safe().optional()}).strict(),
+]);
+export type AgentWorkflowInput=z.infer<typeof AgentWorkflowInput>;
+const source={nativeRunId:z.string().uuid(),workflowId:z.string().min(1).max(255),sessionId:SessionId,turnId:z.string().min(1).max(255)};
+export const ConversationWorkflowParams=z.discriminatedUnion("operation",[
+  AgentWorkflowInput.options[0].extend(source),AgentWorkflowInput.options[1].extend(source),AgentWorkflowInput.options[2].extend(source),
+]);
+export type ConversationWorkflowParams=AgentWorkflowInput & {nativeRunId:string;workflowId:string;sessionId:string;turnId:string};
+export const ConversationWorkflowResult=z.object({
+  status:z.enum(["catalog","status","finished","unknown"]),
+  // Resource catalogs and execution results are control-plane-owned JSON, not
+  // a caller-selected RPC method or device path.
+  data:z.record(z.unknown()),
+}).strict();
+export type ConversationWorkflowResult=z.infer<typeof ConversationWorkflowResult>;

package/src/schemas/device.ts

@@ -13,6 +13,20 @@ export type DeviceFsRoot = z.infer<typeof DeviceFsRoot>;
 export const DeviceInfoParams = z.object({}).default({});
 export type DeviceInfoParams = z.infer<typeof DeviceInfoParams>;
 
+export const DeviceSSHAddress = z.object({
+  address: z.string().ip(),
+  kind: z.enum(["public", "private", "tailscale"]),
+  family: z.enum(["IPv4", "IPv6"]),
+  interface: z.string().max(120).optional(),
+});
+export type DeviceSSHAddress = z.infer<typeof DeviceSSHAddress>;
+export const DeviceSSHHints = z.object({
+  username: z.string().min(1).max(255).optional(),
+  port: z.number().int().min(1).max(65535),
+  addresses: z.array(DeviceSSHAddress).max(64),
+});
+export type DeviceSSHHints = z.infer<typeof DeviceSSHHints>;
+
 export const DeviceInfoResult = z.object({
   at: z.string().datetime({ offset: true }),
   hostname: z.string(),
@@ -25,7 +39,17 @@ export const DeviceInfoResult = z.object({
   runtime: z.object({
     node: z.string().optional(),
   }).optional(),
+  /** Connection hints only, not proof that sshd or an address is reachable. No credentials. */
+  ssh: DeviceSSHHints.optional(),
+  /** Persistent namespace-scoped receiver identity, not a credential or grant. */
+  skillReceiverID:z.string().uuid().optional(),
+  projectProvisionReceiverID:z.string().uuid().optional(),
+  worktreeProvisionReceiverID:z.string().uuid().optional(),
   /** 便于 server 做粗粒度任务路由：ios-development/windows-desktop-development/nvidia-gpu 等。 */
+  /** current_turn_input_v1 confirms strict no-fallback and applied-input ACK semantics;
+   * the selected adapter must additionally advertise injectMidTurn.
+   * native_interaction_receipts_v1 provides durable response-consumption proofs,
+   * not proof that a task/side effect completed or that every harness has a tool. */
   capabilities: z.array(z.string()).default([]),
 });
 export type DeviceInfoResult = z.infer<typeof DeviceInfoResult>;
@@ -91,7 +115,9 @@ export const DeviceFsListParams = z.object({
   absolutePath: z.string().optional(),
   includeHidden: z.boolean().default(false).optional(),
   limit: z.number().int().positive().max(1000).default(200).optional(),
-});
+  projectCandidates:z.boolean().optional(),
+  directoryInput:z.string().max(4096).refine(value=>!/[\x00-\x1f\x7f]/.test(value)).optional(),
+}).refine(value=>value.projectCandidates===true?value.root===undefined&&value.path===undefined&&value.absolutePath===undefined:value.directoryInput===undefined,"Directory candidates use only device-native directoryInput");
 export type DeviceFsListParams = z.infer<typeof DeviceFsListParams>;
 
 export const DeviceFsEntry = z.object({
@@ -101,6 +127,8 @@ export const DeviceFsEntry = z.object({
   kind: z.enum(["file", "directory", "symlink", "other"]),
   size: z.number().int().nonnegative().optional(),
   mtimeMs: z.number().nonnegative().optional(),
+  directoryIdentity:z.string().regex(/^dir:[a-f0-9]+:[a-f0-9]+$/).max(96).optional(),
+  selectable:z.boolean().optional(),
 });
 export type DeviceFsEntry = z.infer<typeof DeviceFsEntry>;
 
@@ -111,5 +139,8 @@ export const DeviceFsListResult = z.object({
   realPath: z.string(),
   entries: z.array(DeviceFsEntry),
   truncated: z.boolean().default(false),
+  input:z.string().max(4096).optional(),
+  pathStyle:z.enum(["posix","windows"]).optional(),
+  directoryMatch:z.object({path:z.string().min(1).max(4096),directoryIdentity:z.string().regex(/^dir:[a-f0-9]+:[a-f0-9]+$/).max(96),selectable:z.boolean()}).optional(),
 });
 export type DeviceFsListResult = z.infer<typeof DeviceFsListResult>;

package/src/schemas/discovery.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { AgentId, Timestamp } from "./common.js";
 import { AgentCapabilities } from "./capabilities.js";
+import { ReasoningLevel } from "./reasoning.js";
 
 /**
  * Agent / 模型发现（design §5 / D14）。
@@ -20,6 +21,7 @@ export const ModelInfo = z.object({
   contextWindow: z.number().int().positive().optional(),
   /** 该模型当前是否可用（如鉴权过期会变 false）。 */
   available: z.boolean().default(true),
+  reasoningLevels: z.array(ReasoningLevel).max(5).optional(),
 });
 export type ModelInfo = z.infer<typeof ModelInfo>;
 

package/src/schemas/document.ts

@@ -47,6 +47,16 @@ export const DocumentDirective = z.object({
 });
 export type DocumentDirective = z.infer<typeof DocumentDirective>;
 
+export const NativeDocumentInput = z.object({
+  requestId: z.string().uuid().transform(value => value.toLowerCase()),
+  path: z.string().min(1).max(4096).refine(value => !value.startsWith("/") && !value.includes("\\") && !value.includes("\0") && !value.split("/").includes("..")),
+  name: z.string().min(1).max(240).refine(value => value !== "." && value !== ".." && !/[\\/\x00-\x1f\x7f]/.test(value)).optional(),
+  mimeType: z.string().max(120).regex(/^[a-zA-Z0-9!#$&^_.+-]+\/[a-zA-Z0-9!#$&^_.+-]+$/).optional(),
+  caption: z.string().max(2000).optional(),
+}).strict();
+export type NativeDocumentInput = z.infer<typeof NativeDocumentInput>;
+export const NATIVE_DOCUMENT_MAX_BYTES = 10 * 1024 * 1024;
+
 /** 单个文档的线上描述（phonon 读完本地文件后封装）。 */
 export const DocumentDescriptor = z.object({
   name: z.string().min(1),
@@ -64,6 +74,9 @@ export type DocumentDescriptor = z.infer<typeof DocumentDescriptor>;
 
 // --- document.send（phonon → server）---
 export const DocumentSendParams = z.object({
+  nativeRunId: z.string().uuid().optional(),
+  workflowId: z.string().min(1).max(512).optional(),
+  requestId: z.string().uuid().optional(),
   /** 关联会话（通常有；纯设备级发送可省）。 */
   sessionId: SessionId.optional(),
   /** 关联轮次（若在某轮对话内触发）。 */

package/src/schemas/employee.ts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+import { AgentId } from "./common.js";
+
+export const EmployeeSelection=z.object({id:z.string().uuid(),revision:z.number().int().positive()}).strict();
+export const EmployeeProfileApplyParams=z.object({
+  employeeId:z.string().uuid(),revision:z.number().int().positive(),agent:AgentId,model:z.string().min(1).max(240),
+  profileId:z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/),
+  name:z.string().min(1).max(120),responsibility:z.string().max(4000),
+  documents:z.object({soul:z.string().max(100000),agents:z.string().max(100000),user:z.string().max(100000),tools:z.string().max(100000)}).strict(),
+}).strict();
+export type EmployeeProfileApplyParams=z.infer<typeof EmployeeProfileApplyParams>;
+export const EmployeeProfileStatusParams=z.object({employeeId:z.string().uuid()});
+export const EmployeeProfileStatusResult=z.object({
+  employeeId:z.string().uuid(),revision:z.number().int().positive(),requestHash:z.string().regex(/^[a-f0-9]{64}$/),
+  state:z.enum(["provisioning","ready","failed"]),agent:AgentId,profileId:z.string(),provider:z.string(),
+  runtimeProfile:z.string(),privateWorkspace:z.object({projectId:z.string().min(1),path:z.string(),name:z.string(),employeeId:z.string().uuid()}).optional(),
+  documentHashes:z.record(z.string()).optional(),memoryBytes:z.number().int().nonnegative().optional(),errorCode:z.string().optional(),
+});
+export type EmployeeProfileStatusResult=z.infer<typeof EmployeeProfileStatusResult>;

package/src/schemas/env.ts

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { ProjectId, AgentId } from "./common.js";
 
-/** Skill / agent 执行环境变量配置。明文存储在设备本地，list 默认脱敏。 */
+/** Skill / agent 执行环境变量配置。值在设备本地以 AES-256-GCM 加密存储，list 默认脱敏。 */
 export const EnvScope = z.enum(["global", "project", "skill"]);
 export type EnvScope = z.infer<typeof EnvScope>;
 

package/src/schemas/interaction.ts

@@ -63,6 +63,12 @@ export const InteractionForm = z.object({
 });
 export type InteractionForm = z.infer<typeof InteractionForm>;
 
+export const InteractionPresentation = z.object({
+  kind: z.literal("approval"),
+  decisionField: z.string().min(1),
+  feedbackField: z.string().min(1).optional(),
+});
+
 /**
  * agent emit 的指令（skill 教）——和 interaction.request 结构基本一致，
  * 但不带 requestId（由 phonon 生成）。
@@ -80,9 +86,17 @@ export type InteractionDirective = z.infer<typeof InteractionDirective>;
 export const InteractionRequestParams = z.object({
   /** 本次交互唯一 id，response 用它配对。 */
   requestId: z.string().min(1),
+  /** Trusted workflow attribution supplied by the device controller, not parsed from form prose. */
+  workflowId: z.string().optional(),
+  /** Stamped by the controller from the current native Session/Workflow. */
+  nativeRunId: z.string().uuid().optional(),
+  /** Canonical Dev Run identity; mutually exclusive with nativeRunId. */
+  devRunId: z.string().uuid().optional(),
   sessionId: SessionId.optional(),
   turnId: z.string().optional(),
   form: InteractionForm,
+  /** Agent-selected rendering hint; never an app-selected approval policy. */
+  presentation: InteractionPresentation.optional(),
   blocking: z.boolean().default(true),
   /** 关联 hookId（HITL 场景）。 */
   hookId: z.string().optional(),
@@ -92,7 +106,7 @@ export const InteractionRequestParams = z.object({
    */
   timeoutSeconds: z.number().int().nonnegative().optional(),
   at: Timestamp,
-});
+}).refine(value=>!(value.nativeRunId&&value.devRunId),"interaction source domains cannot be mixed");
 export type InteractionRequestParams = z.infer<typeof InteractionRequestParams>;
 
 /** 人机交互的生命周期状态（P1-5）：pending → submitted | cancelled | timeout。 */
@@ -109,6 +123,23 @@ export const InteractionRequestResult = z.object({
 });
 export type InteractionRequestResult = z.infer<typeof InteractionRequestResult>;
 
+export const InteractionReceiptState = z.enum(["pending", "delivered", "applied", "cancelled", "timeout", "failed", "unknown"]);
+export const InteractionStatusParams = z.object({ requestId: z.string().min(1).max(512) });
+export const InteractionStatusResult = z.object({
+  requestId: z.string(), requestHash: z.string().regex(/^[a-f0-9]{64}$/), state: InteractionReceiptState,
+  nativeRunId: z.string().uuid().optional(), workflowId: z.string().optional(), sessionId: SessionId.optional(), turnId: z.string().optional(),
+  devRunId:z.string().uuid().optional(),
+  decisionHash: z.string().regex(/^[a-f0-9]{64}$/).optional(), updatedAt: Timestamp,
+}).refine(value=>!(value.nativeRunId&&value.devRunId),"interaction source domains cannot be mixed");
+export type InteractionStatusResult = z.infer<typeof InteractionStatusResult>;
+
+/** Timestamp-independent identity shared by durable request/replay consumers. */
+export function interactionRequestIdentity(params: InteractionRequestParams) {
+  return { requestId: params.requestId, nativeRunId: params.nativeRunId, devRunId:params.devRunId, workflowId: params.workflowId,
+    sessionId: params.sessionId, turnId: params.turnId, form: params.form, presentation: params.presentation,
+    blocking: params.blocking, timeoutSeconds: params.timeoutSeconds, hookId: params.hookId };
+}
+
 // --- interaction.cancel（server → phonon 或 phonon 内部）：主动取消一个 pending 交互 ---
 export const InteractionCancelParams = z.object({
   requestId: z.string().min(1),

package/src/schemas/maintenance.ts

@@ -0,0 +1,204 @@
+import { z } from "zod";
+import { Timestamp } from "./common.js";
+
+/**
+ * Deterministic host-maintenance plane.
+ *
+ * Requests address locally configured target/config/service ids; the server can
+ * never supply raw host paths, package names, service names, or shell strings.
+ * Device policy remains authoritative for every action.
+ */
+
+export const MaintenancePermission = z.object({
+  read: z.boolean(),
+  configWrite: z.boolean(),
+  packageUpdate: z.boolean(),
+  serviceRestart: z.boolean(),
+});
+export type MaintenancePermission = z.infer<typeof MaintenancePermission>;
+
+export const MaintenanceConfigFormat = z.enum(["json", "jsonc", "yaml", "toml", "text"]);
+export type MaintenanceConfigFormat = z.infer<typeof MaintenanceConfigFormat>;
+
+export const MaintenanceConfigDescriptor = z.object({
+  configId: z.string().min(1),
+  label: z.string().optional(),
+  format: MaintenanceConfigFormat,
+  textVisibility: z.enum(["hidden", "public"]).optional(),
+  wholeFileWritable: z.boolean().optional(),
+  allowedRootKeys: z.array(z.string()).optional(),
+  exists: z.boolean(),
+  writable: z.boolean(),
+});
+export type MaintenanceConfigDescriptor = z.infer<typeof MaintenanceConfigDescriptor>;
+
+export const MaintenanceServiceDescriptor = z.object({
+  serviceId: z.string().min(1),
+  label: z.string().optional(),
+  configured: z.boolean(),
+});
+export type MaintenanceServiceDescriptor = z.infer<typeof MaintenanceServiceDescriptor>;
+
+export const MaintenanceTargetDescriptor = z.object({
+  targetId: z.string().min(1),
+  label: z.string(),
+  command: z.string().optional(),
+  packageUpdateConfigured: z.boolean(),
+  configs: z.array(MaintenanceConfigDescriptor),
+  services: z.array(MaintenanceServiceDescriptor),
+});
+export type MaintenanceTargetDescriptor = z.infer<typeof MaintenanceTargetDescriptor>;
+
+export const MaintenanceTargetsParams = z.object({}).strict();
+export const MaintenanceTargetsResult = z.object({
+  permissions: MaintenancePermission,
+  targets: z.array(MaintenanceTargetDescriptor),
+});
+
+export const MaintenanceDiagnoseParams = z.object({
+  targetId: z.string().min(1).optional(),
+}).strict();
+export const MaintenanceDiagnostic = z.object({
+  targetId: z.string(),
+  available: z.boolean(),
+  version: z.string().optional(),
+  versionError: z.string().optional(),
+  configs: z.array(z.object({
+    configId: z.string(),
+    exists: z.boolean(),
+    valid: z.boolean().optional(),
+    sha256: z.string().optional(),
+    error: z.string().optional(),
+  })),
+  services: z.array(z.object({
+    serviceId: z.string(),
+    status: z.enum(["running", "stopped", "unknown", "not_configured"]),
+    detail: z.string().optional(),
+  })),
+});
+export const MaintenanceDiagnoseResult = z.object({
+  diagnostics: z.array(MaintenanceDiagnostic),
+  at: Timestamp,
+});
+
+export const MaintenanceConfigGetParams = z.object({
+  targetId: z.string().min(1),
+  configId: z.string().min(1),
+}).strict();
+export const MaintenanceConfigGetResult = z.object({
+  targetId: z.string(),
+  configId: z.string(),
+  exists: z.boolean(),
+  sha256: z.string().optional(),
+  format: MaintenanceConfigFormat.optional(),
+  text: z.string().optional(),
+  textWithheld: z.boolean().optional(),
+  /** Parsed value with secret-looking fields recursively redacted; TOML special types use tagged diagnostic projections. */
+  value: z.unknown().optional(),
+});
+
+export const MaintenanceConfigPatchParams = z.object({
+  targetId: z.string().min(1),
+  configId: z.string().min(1),
+  /** Optimistic lock from maintenance.config.get. Required to prevent stale overwrite. */
+  expectedSha256: z.string().min(1),
+  /** RFC 7396-style JSON merge patch. Arrays are replaced as a whole. */
+  patch: z.record(z.unknown()),
+  reason: z.string().max(500).optional(),
+  clientRequestId: z.string().optional(),
+}).strict();
+export const MaintenanceConfigPatchResult = z.object({
+  targetId: z.string(),
+  configId: z.string(),
+  format: MaintenanceConfigFormat.optional(),
+  changed: z.boolean(),
+  previousSha256: z.string(),
+  sha256: z.string(),
+  backupId: z.string().optional(),
+});
+
+export const MaintenanceConfigEditParams = z.object({
+  targetId: z.string().min(1),
+  configId: z.string().min(1),
+  expectedSha256: z.string().min(1),
+  edits: z.array(z.object({ oldText: z.string().min(1).max(1048576), newText: z.string().max(1048576) }).strict()).min(1).max(100),
+  reason: z.string().max(500).optional(),
+  clientRequestId: z.string().optional(),
+}).strict();
+export const MaintenanceConfigEditResult = MaintenanceConfigPatchResult;
+export type MaintenanceConfigEditParams = z.infer<typeof MaintenanceConfigEditParams>;
+export type MaintenanceConfigEditResult = z.infer<typeof MaintenanceConfigEditResult>;
+
+export const MaintenanceRollbackParams = z.object({
+  backupId: z.string().min(1).regex(/^[A-Za-z0-9._-]+$/),
+  /** Current config hash, preventing a stale rollback from clobbering later edits. */
+  expectedCurrentSha256: z.string().min(1),
+  reason: z.string().max(500).optional(),
+  clientRequestId: z.string().optional(),
+}).strict();
+export const MaintenanceRollbackResult = z.object({
+  backupId: z.string(),
+  targetId: z.string(),
+  configId: z.string(),
+  restored: z.literal(true),
+  sha256: z.string(),
+  /** Backup of the state replaced by rollback, allowing an immediate roll-forward. */
+  reversibleBackupId: z.string().optional(),
+});
+
+export const MaintenancePackageUpdateParams = z.object({
+  targetId: z.string().min(1),
+  version: z.string().min(1).max(100).optional(),
+  clientRequestId: z.string().optional(),
+}).strict();
+export const MaintenancePackageUpdateResult = z.object({
+  targetId: z.string(),
+  manager: z.enum(["npm", "pnpm"]),
+  packageName: z.string(),
+  requestedVersion: z.string(),
+  exitCode: z.number().int(),
+  stdout: z.string(),
+  stderr: z.string(),
+  versionAfter: z.string().optional(),
+});
+
+export const MaintenanceServiceStatusParams = z.object({
+  targetId: z.string().min(1),
+  serviceId: z.string().min(1),
+}).strict();
+export const MaintenanceServiceStatusResult = z.object({
+  targetId: z.string(),
+  serviceId: z.string(),
+  status: z.enum(["running", "stopped", "unknown", "not_configured"]),
+  detail: z.string().optional(),
+});
+
+export const MaintenanceServiceRestartParams = z.object({
+  targetId: z.string().min(1),
+  serviceId: z.string().min(1),
+  clientRequestId: z.string().optional(),
+}).strict();
+export const MaintenanceServiceRestartResult = z.object({
+  targetId: z.string(),
+  serviceId: z.string(),
+  restarted: z.boolean(),
+  status: z.enum(["running", "stopped", "unknown", "not_configured"]),
+  detail: z.string().optional(),
+});
+
+export type MaintenanceTargetsParams = z.infer<typeof MaintenanceTargetsParams>;
+export type MaintenanceTargetsResult = z.infer<typeof MaintenanceTargetsResult>;
+export type MaintenanceDiagnoseParams = z.infer<typeof MaintenanceDiagnoseParams>;
+export type MaintenanceDiagnoseResult = z.infer<typeof MaintenanceDiagnoseResult>;
+export type MaintenanceConfigGetParams = z.infer<typeof MaintenanceConfigGetParams>;
+export type MaintenanceConfigGetResult = z.infer<typeof MaintenanceConfigGetResult>;
+export type MaintenanceConfigPatchParams = z.infer<typeof MaintenanceConfigPatchParams>;
+export type MaintenanceConfigPatchResult = z.infer<typeof MaintenanceConfigPatchResult>;
+export type MaintenanceRollbackParams = z.infer<typeof MaintenanceRollbackParams>;
+export type MaintenanceRollbackResult = z.infer<typeof MaintenanceRollbackResult>;
+export type MaintenancePackageUpdateParams = z.infer<typeof MaintenancePackageUpdateParams>;
+export type MaintenancePackageUpdateResult = z.infer<typeof MaintenancePackageUpdateResult>;
+export type MaintenanceServiceStatusParams = z.infer<typeof MaintenanceServiceStatusParams>;
+export type MaintenanceServiceStatusResult = z.infer<typeof MaintenanceServiceStatusResult>;
+export type MaintenanceServiceRestartParams = z.infer<typeof MaintenanceServiceRestartParams>;
+export type MaintenanceServiceRestartResult = z.infer<typeof MaintenanceServiceRestartResult>;

package/src/schemas/managed-mcp.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+
+export const ManagedMcpBinding = z.object({
+  id: z.string().uuid(),
+  agentId: z.string().min(1).max(255),
+  enabled: z.boolean(),
+}).strict();
+export const ManagedMcpConfigureParams = z.object({
+  revision: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+  bindings: z.array(ManagedMcpBinding).max(50),
+}).strict().refine(value => new Set(value.bindings.map(item => item.id)).size === value.bindings.length
+  && new Set(value.bindings.map(item => item.agentId)).size === value.bindings.length, "duplicate MCP binding");
+export const ManagedMcpStatusParams = z.object({}).strict();
+export const ManagedMcpBindingStatus = z.object({
+  id: z.string().uuid(), agentId: z.string().min(1).max(255),
+  state: z.enum(["configured", "removed", "conflict", "unsupported", "local_consent_required", "error"]),
+  code: z.string().regex(/^[a-z0-9_]{1,100}$/).optional(),
+}).strict();
+export const ManagedMcpStatusResult = z.object({
+  revision: z.number().int().min(-1),
+  allowed: z.boolean(),
+  bindings: z.array(ManagedMcpBindingStatus).max(50),
+}).strict();
+export type ManagedMcpConfigureParams = z.infer<typeof ManagedMcpConfigureParams>;
+export type ManagedMcpStatusResult = z.infer<typeof ManagedMcpStatusResult>;