@x-otto/orchestration-contracts 0.0.1-alpha.0

package/README.md

@@ -0,0 +1,72 @@
+# @x-otto/orchestration-contracts
+
+> orchestrator↔tools pure type contracts. Zero runtime — `export type` only, compiled output is empty.
+
+`@x-otto/orchestration-contracts` defines the callback port types between the orchestrator execution kernel (`@x-otto/orchestrator`) and the tools adapter layer (`@x-otto/tools`). It provides `TaskStatus`, `Result<T>`, `TodoItem`, 8 callback function signatures (TaskDispatch, CallAgent, WriteTodos, etc.), and the MODEL_SLOTS constant. Both sides `import type`, avoiding a circular dependency.
+
+## Installation
+
+```bash
+pnpm add @x-otto/orchestration-contracts
+```
+
+## Usage
+
+```ts
+import type {
+  TaskStatus,
+  Result,
+  TodoItem,
+  TaskDispatch,
+  CallAgent,
+  WriteTodos,
+} from '@x-otto/orchestration-contracts'
+import { MODEL_SLOTS } from '@x-otto/orchestration-contracts'
+
+// Result<T> discriminant union
+function handleResult<T>(result: Result<T>) {
+  if (result.ok) {
+    console.log('Success:', result.value)
+  } else {
+    console.error('Error:', result.error)
+  }
+}
+
+// Task status
+const status: TaskStatus = 'running' // 'pending' | 'running' | 'completed' | 'failed' | 'cancelled'
+```
+
+## API
+
+### Primitives
+- `Result<T>` — `{ ok: true; value: T } | { ok: false; error: string }`
+- `TaskStatus` — `'pending' | 'running' | 'completed' | 'failed' | 'cancelled'`
+- `ModelSlotName` — `'normal' | 'thinking' | 'compact' | 'critique' | 'vision'`
+- `SessionMode` — `'ephemeral' | 'sticky'`
+- `TaskMode` — `'sync' | 'background'`
+- `TodoStatus` / `TodoItem` — todo list types
+- `MODEL_SLOTS` — constant array of 5 slot names
+
+### Callback Ports
+- `TaskDispatch` — delegate task (sync/background)
+- `CallAgent` — synchronous isolated agent call
+- `GetTask` / `GetTaskData` — task querying
+- `ListTasks` — list tasks by status
+- `UpdateTask` — cancel/retry a task
+- `GetBackgroundOutput` — read background task output
+- `CancelBackground` — cancel background task
+- `WriteTodos` — write todo list
+- `WorkflowOptions` — delegation depth, max retries, etc.
+
+### Utilities
+- `checkDelegationDepth(args, maxDepth)` — delegation depth guard
+- `createTodoStore()` — lightweight in-memory todo store
+
+## Dependencies
+
+- Internal: `@x-otto/interchange` (type-only)
+- External: none
+
+## Related
+
+- [Architecture](./ARCHITECTURE.md)

package/dist/index.d.ts

@@ -0,0 +1,115 @@
+import { TodoItem, TodoStatus } from "@x-otto/interchange";
+
+//#region src/primitives.d.ts
+type TaskStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+/** 模型槽位词表（单一真源）——`ai.WORKFLOW_SLOTS` 从此派生、`setting` 直取，消 split-brain。 */
+declare const MODEL_SLOTS: readonly ["normal", "thinking", "compact", "critique", "vision"];
+type ModelSlotName = (typeof MODEL_SLOTS)[number];
+type SessionMode = 'ephemeral' | 'sticky';
+type TaskMode = 'sync' | 'background';
+/**
+ * 领域结果判别联合（RFC-004 D36 §4-15）。
+ * 跨包契约不再泄漏 `{success,output,error}` UI 软字典：成功携领域值 `value`，失败携人读 `error`。
+ * 软字典只允许出现在面向 LLM 的 tools 适配层（把 Result 投影为 ToolResult 文案/isError）。
+ */
+type Result<T> = {
+  ok: true;
+  value: T;
+} | {
+  ok: false;
+  error: string;
+};
+interface DispatchOutcome {
+  id: string;
+  status: TaskStatus;
+  output?: string;
+}
+interface TaskBrief {
+  id: string;
+  prompt: string;
+  status: TaskStatus;
+}
+interface BackgroundOutput {
+  status: TaskStatus;
+  output?: string;
+}
+/** 编排工作流配置（M-B3 单源——consumed by orchestrator & setting）。 */
+interface WorkflowOptions {
+  retry?: {
+    enabled?: boolean;
+    maxAttempts?: number;
+  };
+  circuitBreaker?: {
+    enabled?: boolean;
+    failureThreshold?: number;
+    timeoutMs?: number;
+  };
+}
+//#endregion
+//#region src/callbacks.d.ts
+type TaskDispatch = (args: {
+  prompt: string;
+  subagent?: string;
+  category?: string;
+  mode: TaskMode;
+  sessionId?: string;
+  sessionMode?: SessionMode;
+  slot?: ModelSlotName; /** 显式模型 id（subagent 按能力选型）——优先于 slot。 */
+  model?: string; /** 调用方(caller)委托深度（root=0）；orchestrator 据此算 childDepth 护栏。 */
+  depth?: number; /** 父工具的 AbortSignal——abort 主会话时串联中断 in-flight 子会话（sync 路径；background 故意不串）。 */
+  signal?: AbortSignal;
+}) => Promise<Result<DispatchOutcome>>;
+type CallAgent = (agent: string, prompt: string, /** signal 为父工具 AbortSignal——abort 主会话时串联中断 in-flight 子会话。 */
+
+options?: {
+  slot?: ModelSlotName;
+  model?: string;
+  depth?: number;
+  signal?: AbortSignal;
+}) => Promise<Result<string>>;
+type GetTaskData = {
+  id: string;
+  status: TaskStatus;
+  prompt?: string;
+  output?: string;
+  error?: string;
+};
+type GetTask = (id: string) => Promise<Result<GetTaskData>>;
+type ListTasks = (status?: TaskStatus | 'all') => Promise<Result<TaskBrief[]>>;
+type UpdateTask = (id: string, action: 'cancel' | 'retry') => Promise<Result<string>>;
+type GetBackgroundOutput = (id: string) => Promise<Result<BackgroundOutput>>;
+type CancelBackground = (id: string) => Promise<Result<void>>;
+/** 写入 Todo 列表 — 对齐 write_todos 工具。成功携合并后的 todo 列表。 */
+type WriteTodos = (args: {
+  title?: string;
+  action: 'set' | 'update';
+  todos: TodoItem[];
+  sessionId?: string;
+}) => Promise<Result<TodoItem[]>>;
+//#endregion
+//#region src/delegation.d.ts
+/**
+ * 委派深度护栏单源（RFC-057 M90-01 / §6 规则 5 / §10 C14）。
+ *
+ * `childDepth = (depth ?? 0) + 1`；`exceeded = childDepth > max`。
+ * 三处调用点共用，消字节级重复：
+ *   - orchestrator `dispatchTask`（task_delegate sync/background）
+ *   - orchestrator `callAgent`（agent_call 轻量旁路）
+ *   - tools `fork_call`（字节继承旁路）
+ *
+ * 注意（§10 C14）：本轴是「跨委派深度」（一个 agent 能向子 agent 委派多少层，默认 max=1），
+ * 与 swarm `MAX_NESTING_DEPTH=5`（team 内部嵌套递归轴）是**同名不同概念**，不得并入。
+ */
+interface DelegationDepthCheck {
+  /** 子委派的深度（父 depth + 1），传给被委派会话。 */
+  childDepth: number;
+  /** childDepth 是否越过 max（越过则应拒绝委派）。 */
+  exceeded: boolean;
+}
+declare function checkDelegationDepth(depth: number | undefined, max: number): DelegationDepthCheck;
+//#endregion
+//#region src/todo-store.d.ts
+declare function createTodoStore(): WriteTodos;
+//#endregion
+export { type BackgroundOutput, type CallAgent, type CancelBackground, type DelegationDepthCheck, type DispatchOutcome, type GetBackgroundOutput, type GetTask, type GetTaskData, type ListTasks, MODEL_SLOTS, type ModelSlotName, type Result, type SessionMode, type TaskBrief, type TaskDispatch, type TaskMode, type TaskStatus, type TodoItem, type TodoStatus, type UpdateTask, type WorkflowOptions, type WriteTodos, checkDelegationDepth, createTodoStore };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/primitives.ts","../src/callbacks.ts","../src/delegation.ts","../src/todo-store.ts"],"mappings":";;;KAEY,UAAA;;cAGC,WAAA;AAAA,KACD,aAAA,WAAwB,WAAA;AAAA,KAExB,WAAA;AAAA,KAEA,QAAA;;AALZ;;;;KAYY,MAAA;EAAc,EAAA;EAAU,KAAA,EAAO,CAAA;AAAA;EAAQ,EAAA;EAAW,KAAA;AAAA;AAAA,UAE7C,eAAA;EACf,EAAA;EACA,MAAA,EAAQ,UAAA;EACR,MAAA;AAAA;AAAA,UAGe,SAAA;EACf,EAAA;EACA,MAAA;EACA,MAAA,EAAQ,UAAA;AAAA;AAAA,UAGO,gBAAA;EACf,MAAA,EAAQ,UAAA;EACR,MAAA;AAAA;;UAIe,eAAA;EACf,KAAA;IAAU,OAAA;IAAmB,WAAA;EAAA;EAC7B,cAAA;IAAmB,OAAA;IAAmB,gBAAA;IAA2B,SAAA;EAAA;AAAA;;;KC3BvD,YAAA,IAAgB,IAAA;EAC1B,MAAA;EACA,QAAA;EACA,QAAA;EACA,IAAA,EAAM,QAAA;EACN,SAAA;EACA,WAAA,GAAc,WAAA;EACd,IAAA,GAAO,aAAA,EDdkF;ECgBzF,KAAA,WDhByF;ECkBzF,KAAA,WDjBU;ECmBV,MAAA,GAAS,WAAA;AAAA,MACL,OAAA,CAAQ,MAAA,CAAO,eAAA;AAAA,KAET,SAAA,IACV,KAAA,UACA,MAAA;;AAEA,OAAA;EAAY,IAAA,GAAO,aAAA;EAAe,KAAA;EAAgB,KAAA;EAAgB,MAAA,GAAS,WAAA;AAAA,MACxE,OAAA,CAAQ,MAAA;AAAA,KAED,WAAA;EACV,EAAA;EACA,MAAA,EAAQ,UAAA;EACR,MAAA;EACA,MAAA;EACA,KAAA;AAAA;AAAA,KAGU,OAAA,IAAW,EAAA,aAAe,OAAA,CAAQ,MAAA,CAAO,WAAA;AAAA,KAEzC,SAAA,IAAa,MAAA,GAAS,UAAA,aAAuB,OAAA,CAAQ,MAAA,CAAO,SAAA;AAAA,KAE5D,UAAA,IAAc,EAAA,UAAY,MAAA,yBAA+B,OAAA,CAAQ,MAAA;AAAA,KAEjE,mBAAA,IAAuB,EAAA,aAAe,OAAA,CAAQ,MAAA,CAAO,gBAAA;AAAA,KAErD,gBAAA,IAAoB,EAAA,aAAe,OAAA,CAAQ,MAAA;;KAG3C,UAAA,IAAc,IAAA;EACxB,KAAA;EACA,MAAA;EACA,KAAA,EAAO,QAAA;EACP,SAAA;AAAA,MACI,OAAA,CAAQ,MAAA,CAAO,QAAA;;;;;;ADzDrB;;;;;AAGA;;;;UEOiB,oBAAA;EFNL;EEQV,UAAA;;EAEA,QAAA;AAAA;AAAA,iBAGc,oBAAA,CAAqB,KAAA,sBAA2B,GAAA,WAAc,oBAAA;;;iBCd9D,eAAA,CAAA,GAAmB,UAAA"}

package/dist/index.js

@@ -0,0 +1,2 @@
+const e=[`normal`,`thinking`,`compact`,`critique`,`vision`];function t(e,t){let n=(e??0)+1;return{childDepth:n,exceeded:n>t}}function n(){let e=new Map;return async({action:t,todos:n,sessionId:r})=>{let i=r?.trim()||`__default__`,a=e.get(i)??[];if(t===`set`)a=[...n];else{let e=new Map(a.map(e=>[e.id,e]));for(let t of n)e.set(t.id,t);a=[...e.values()]}return e.set(i,a),{ok:!0,value:a}}}export{e as MODEL_SLOTS,t as checkDelegationDepth,n as createTodoStore};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/primitives.ts","../src/delegation.ts","../src/todo-store.ts"],"sourcesContent":["export type { TodoStatus, TodoItem } from '@x-otto/interchange'\n\nexport type TaskStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled'\n\n/** 模型槽位词表（单一真源）——`ai.WORKFLOW_SLOTS` 从此派生、`setting` 直取，消 split-brain。 */\nexport const MODEL_SLOTS = ['normal', 'thinking', 'compact', 'critique', 'vision'] as const\nexport type ModelSlotName = (typeof MODEL_SLOTS)[number]\n\nexport type SessionMode = 'ephemeral' | 'sticky'\n\nexport type TaskMode = 'sync' | 'background'\n\n/**\n * 领域结果判别联合（RFC-004 D36 §4-15）。\n * 跨包契约不再泄漏 `{success,output,error}` UI 软字典：成功携领域值 `value`，失败携人读 `error`。\n * 软字典只允许出现在面向 LLM 的 tools 适配层（把 Result 投影为 ToolResult 文案/isError）。\n */\nexport type Result<T> = { ok: true; value: T } | { ok: false; error: string }\n\nexport interface DispatchOutcome {\n  id: string\n  status: TaskStatus\n  output?: string\n}\n\nexport interface TaskBrief {\n  id: string\n  prompt: string\n  status: TaskStatus\n}\n\nexport interface BackgroundOutput {\n  status: TaskStatus\n  output?: string\n}\n\n/** 编排工作流配置（M-B3 单源——consumed by orchestrator & setting）。 */\nexport interface WorkflowOptions {\n  retry?: { enabled?: boolean; maxAttempts?: number }\n  circuitBreaker?: { enabled?: boolean; failureThreshold?: number; timeoutMs?: number }\n}\n","/**\n * 委派深度护栏单源（RFC-057 M90-01 / §6 规则 5 / §10 C14）。\n *\n * `childDepth = (depth ?? 0) + 1`；`exceeded = childDepth > max`。\n * 三处调用点共用，消字节级重复：\n *   - orchestrator `dispatchTask`（task_delegate sync/background）\n *   - orchestrator `callAgent`（agent_call 轻量旁路）\n *   - tools `fork_call`（字节继承旁路）\n *\n * 注意（§10 C14）：本轴是「跨委派深度」（一个 agent 能向子 agent 委派多少层，默认 max=1），\n * 与 swarm `MAX_NESTING_DEPTH=5`（team 内部嵌套递归轴）是**同名不同概念**，不得并入。\n */\nexport interface DelegationDepthCheck {\n  /** 子委派的深度（父 depth + 1），传给被委派会话。 */\n  childDepth: number\n  /** childDepth 是否越过 max（越过则应拒绝委派）。 */\n  exceeded: boolean\n}\n\nexport function checkDelegationDepth(depth: number | undefined, max: number): DelegationDepthCheck {\n  const childDepth = (depth ?? 0) + 1\n  return { childDepth, exceeded: childDepth > max }\n}\n","import type { TodoItem } from './primitives'\nimport type { WriteTodos } from './callbacks'\n\n// orchestration-contracts/src/todo-store.ts — Session-level Todo store.\n// Extracted from orchestrator.ts (endgame architecture review O2).\nexport function createTodoStore(): WriteTodos {\n  const storeBySession = new Map<string, TodoItem[]>()\n\n  return async ({ action, todos, sessionId }) => {\n    const sessionKey = sessionId?.trim() || '__default__'\n    let store = storeBySession.get(sessionKey) ?? []\n\n    if (action === 'set') {\n      store = [...todos]\n    } else {\n      const map = new Map(store.map((t) => [t.id, t]))\n      for (const todo of todos) {\n        map.set(todo.id, todo)\n      }\n      store = [...map.values()]\n    }\n\n    storeBySession.set(sessionKey, store)\n    return { ok: true, value: store }\n  }\n}\n"],"mappings":"AAKA,MAAa,EAAc,CAAC,SAAU,WAAY,UAAW,WAAY,SAAS,CCclF,SAAgB,EAAqB,EAA2B,EAAmC,CACjG,IAAM,GAAc,GAAS,GAAK,EAClC,MAAO,CAAE,aAAY,SAAU,EAAa,EAAK,CChBnD,SAAgB,GAA8B,CAC5C,IAAM,EAAiB,IAAI,IAE3B,OAAO,MAAO,CAAE,SAAQ,QAAO,eAAgB,CAC7C,IAAM,EAAa,GAAW,MAAM,EAAI,cACpC,EAAQ,EAAe,IAAI,EAAW,EAAI,EAAE,CAEhD,GAAI,IAAW,MACb,EAAQ,CAAC,GAAG,EAAM,KACb,CACL,IAAM,EAAM,IAAI,IAAI,EAAM,IAAK,GAAM,CAAC,EAAE,GAAI,EAAE,CAAC,CAAC,CAChD,IAAK,IAAM,KAAQ,EACjB,EAAI,IAAI,EAAK,GAAI,EAAK,CAExB,EAAQ,CAAC,GAAG,EAAI,QAAQ,CAAC,CAI3B,OADA,EAAe,IAAI,EAAY,EAAM,CAC9B,CAAE,GAAI,GAAM,MAAO,EAAO"}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@x-otto/orchestration-contracts",
+  "version": "0.0.1-alpha.0",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org",
+    "tag": "alpha"
+  },
+  "dependencies": {
+    "@x-otto/interchange": "0.1.0-alpha.1"
+  },
+  "private": false,
+  "scripts": {
+    "build": "tsdown",
+    "typecheck:project": "tsc -p tsconfig.json --noEmit",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}