@cleocode/contracts 2026.5.134 → 2026.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (67) hide show
  1. package/dist/__tests__/operations-registry.test.js +13 -0
  2. package/dist/__tests__/operations-registry.test.js.map +1 -1
  3. package/dist/__tests__/skill-executor-contract.test.d.ts +14 -0
  4. package/dist/__tests__/skill-executor-contract.test.d.ts.map +1 -0
  5. package/dist/__tests__/skill-executor-contract.test.js +85 -0
  6. package/dist/__tests__/skill-executor-contract.test.js.map +1 -0
  7. package/dist/agent-registry.d.ts +1 -3
  8. package/dist/agent-registry.d.ts.map +1 -1
  9. package/dist/backup-manifest.d.ts +1 -1
  10. package/dist/brain-graph.d.ts +2 -2
  11. package/dist/brain-graph.d.ts.map +1 -1
  12. package/dist/config.d.ts +71 -1
  13. package/dist/config.d.ts.map +1 -1
  14. package/dist/db-inventory.json +4 -4
  15. package/dist/dispatch/operations-registry.d.ts.map +1 -1
  16. package/dist/dispatch/operations-registry.js +44 -0
  17. package/dist/dispatch/operations-registry.js.map +1 -1
  18. package/dist/exit-codes.d.ts +20 -1
  19. package/dist/exit-codes.d.ts.map +1 -1
  20. package/dist/exit-codes.js +19 -0
  21. package/dist/exit-codes.js.map +1 -1
  22. package/dist/index.d.ts +4 -2
  23. package/dist/index.d.ts.map +1 -1
  24. package/dist/index.js +2 -0
  25. package/dist/index.js.map +1 -1
  26. package/dist/migration-parity.d.ts +174 -0
  27. package/dist/migration-parity.d.ts.map +1 -0
  28. package/dist/migration-parity.js +39 -0
  29. package/dist/migration-parity.js.map +1 -0
  30. package/dist/operations/admin.d.ts +4 -2
  31. package/dist/operations/admin.d.ts.map +1 -1
  32. package/dist/operations/brain.d.ts +2 -2
  33. package/dist/operations/brain.d.ts.map +1 -1
  34. package/dist/operations/llm.d.ts +6 -3
  35. package/dist/operations/llm.d.ts.map +1 -1
  36. package/dist/operations/session.d.ts +17 -0
  37. package/dist/operations/session.d.ts.map +1 -1
  38. package/dist/operations/tasks.d.ts +10 -0
  39. package/dist/operations/tasks.d.ts.map +1 -1
  40. package/dist/operations/tasks.js.map +1 -1
  41. package/dist/sub-accessors.d.ts +4 -4
  42. package/dist/sub-accessors.d.ts.map +1 -1
  43. package/dist/sub-accessors.js +1 -1
  44. package/dist/tools/skill-executor.d.ts +156 -0
  45. package/dist/tools/skill-executor.d.ts.map +1 -0
  46. package/dist/tools/skill-executor.js +47 -0
  47. package/dist/tools/skill-executor.js.map +1 -0
  48. package/package.json +6 -2
  49. package/src/__tests__/__snapshots__/operations-registry.test.ts.snap +1 -1
  50. package/src/__tests__/operations-registry.test.ts +14 -0
  51. package/src/__tests__/skill-executor-contract.test.ts +104 -0
  52. package/src/agent-registry.ts +1 -3
  53. package/src/backup-manifest.ts +1 -1
  54. package/src/brain-graph.ts +2 -2
  55. package/src/config.ts +73 -1
  56. package/src/db-inventory.json +4 -4
  57. package/src/dispatch/operations-registry.ts +45 -0
  58. package/src/exit-codes.ts +20 -0
  59. package/src/index.ts +11 -1
  60. package/src/migration-parity.ts +178 -0
  61. package/src/operations/admin.ts +4 -2
  62. package/src/operations/brain.ts +2 -2
  63. package/src/operations/llm.ts +12 -4
  64. package/src/operations/session.ts +17 -0
  65. package/src/operations/tasks.ts +10 -0
  66. package/src/sub-accessors.ts +5 -5
  67. package/src/tools/skill-executor.ts +183 -0
@@ -1 +1 @@
1
- {"version":3,"file":"sub-accessors.d.ts","sourceRoot":"","sources":["../src/sub-accessors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAMH;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gCAAgC;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+DAA+D;IAC/D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,uBAAuB;IACvB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,kBAAkB;IAClB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mBAAmB;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,kBAAkB;IAClB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;OAMG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,IAAI,CAAC,kBAAkB,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAElF;;;;;;OAMG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IAE/D;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAMD;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExD;;;;OAIG;IACH,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAEzB;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAMD;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAEzB;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAMD;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAEzB;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAMD;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAErE;;;;OAIG;IACH,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAEzB;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB"}
1
+ {"version":3,"file":"sub-accessors.d.ts","sourceRoot":"","sources":["../src/sub-accessors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAMH;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gCAAgC;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+DAA+D;IAC/D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,uBAAuB;IACvB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,kBAAkB;IAClB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mBAAmB;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,kBAAkB;IAClB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;OAMG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,IAAI,CAAC,kBAAkB,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAElF;;;;;;OAMG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IAE/D;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAMD;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExD;;;;OAIG;IACH,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAEzB;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAMD;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAEzB;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAMD;;;;;;;GAOG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;;OAIG;IACH,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAEzB;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAMD;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAErE;;;;OAIG;IACH,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAEzB;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB"}
@@ -8,7 +8,7 @@
8
8
  * - BrainAccessor → brain.db (memory observations, semantic graph)
9
9
  * - ConduitAccessor → conduit.db (project-scoped messaging)
10
10
  * - NexusAccessor → nexus.db (code intelligence graph)
11
- * - SignaldockAccessor → signaldock.db (global agent identity)
11
+ * - AgentRegistrySubAccessor → signaldock.db (global agent identity)
12
12
  * - TelemetryAccessor → (future — telemetry collection)
13
13
  *
14
14
  * See DocsAccessor in docs-accessor.ts for the docs/llmtxt sub-accessor.
@@ -0,0 +1,156 @@
1
+ /**
2
+ * `SkillExecutor` — the Dependency-Inversion (DIP) seam for the GenKit-phase
3
+ * skill dispatcher (P1 · T11476 · E-SKILL-EXECUTOR-CONTRACT · epic T11391).
4
+ *
5
+ * A **skill** is a multi-step capability composed from the atomic tool
6
+ * primitives ({@link ./atomic.js}) — read/write/search/shell/etc. The atomic
7
+ * tool layer is pure side-effect plumbing; the SKILLS layer is where those
8
+ * primitives are sequenced into a unit of agent work (run a lint, scaffold a
9
+ * file, summarize a tree). This module declares the ABSTRACTION the dispatcher
10
+ * depends on so the concrete in-process implementation
11
+ * (`SkillExecutorAdapter`, T11477) can be INJECTED rather than imported. That is
12
+ * the classic DIP move: high-level dispatch policy and low-level execution
13
+ * mechanism both depend on this contract, not on each other.
14
+ *
15
+ * ## Why it lives in `@cleocode/contracts`
16
+ *
17
+ * The skill dispatcher (a high-level orchestration concern) and the executor
18
+ * adapter (a low-level mechanism wiring an LLM/GenKit flow over the guarded
19
+ * tools) must agree on ONE shape without either importing the other. Putting the
20
+ * interface here — alongside the atomic-tool I/O shapes it builds on — lets
21
+ * `core`, `mcp-adapter`, `caamp`, and `cleo-os` bind to a single seam and lets
22
+ * tests substitute a fake executor with no runtime dependency.
23
+ *
24
+ * ## Boundary contract (T11476 acceptance)
25
+ *
26
+ * - **AC1** — `execute({ skillId, context, tools }) -> Promise<{ status, output,
27
+ * error }>`. The result envelope intentionally mirrors the playbook runtime's
28
+ * `AgentDispatcher.dispatch()` result so a `SkillExecutor` reads as an
29
+ * in-process `AgentDispatcher` specialization (NOT a clone of it).
30
+ * - **AC2** — depends ONLY on the guarded-tool surface ({@link GuardedToolSurface},
31
+ * itself derived purely from {@link ./atomic.js} I/O shapes) and contract-local
32
+ * types. ZERO `@cleocode/*` runtime coupling: the `tools` dependency is the
33
+ * structural shape of `@cleocode/core`'s `createToolGuard()` result, declared
34
+ * here so neither contracts nor the dispatcher import `core`.
35
+ * - **AC3** — deliberately NOT named `SessionEngine` (that collides with
36
+ * `core/src/sessions/`). A `SkillExecutor` is an in-process
37
+ * `AgentDispatcher`-shaped executor, not a session lifecycle owner.
38
+ *
39
+ * Types-only — no runtime logic (Gate 10 `contracts-purity`).
40
+ *
41
+ * @epic T11391
42
+ * @task T11476
43
+ * @saga T11387
44
+ * @see ./atomic.js — the tool I/O shapes this seam composes over
45
+ */
46
+ import type { ExecuteShellInput, ExecuteShellResult, PathExistsInput, PathExistsResult, ReadFileInput, ReadFileResult, RunGitInput, WriteFileInput, WriteFileResult } from './atomic.js';
47
+ /**
48
+ * The deny-first guarded primitive surface a {@link SkillExecutor} is handed to
49
+ * perform side-effecting work. Every method is built purely from the atomic-tool
50
+ * I/O shapes in {@link ./atomic.js}, so this interface carries ZERO coupling to
51
+ * any `@cleocode/*` runtime package.
52
+ *
53
+ * This is the contract-pure SHAPE of `@cleocode/core`'s `createToolGuard()`
54
+ * result (`ToolGuard` in `packages/core/src/tools/guard.ts`). It is declared
55
+ * here — not imported from `core` — so the skill dispatcher depends on an
56
+ * abstraction (DIP) and the concrete guard is injected. The `core` `ToolGuard`
57
+ * remains structurally assignable to this surface.
58
+ *
59
+ * @remarks Mirrors `ToolGuard` member-for-member. When a new atomic primitive is
60
+ * added to the guard chokepoint, add it here too so the surfaces stay in sync.
61
+ */
62
+ export interface GuardedToolSurface {
63
+ /** Read a file as text through the guard. */
64
+ readFileText(input: ReadFileInput): Promise<ReadFileResult>;
65
+ /** Read + parse a JSON file through the guard. */
66
+ readJson<T>(path: string): Promise<T>;
67
+ /** Atomically write a file (tmp-then-rename) through the guard. */
68
+ writeFileAtomic(input: WriteFileInput): Promise<WriteFileResult>;
69
+ /** Test path existence + kind through the guard. */
70
+ pathExists(input: PathExistsInput): Promise<PathExistsResult>;
71
+ /** Run a command with explicit cwd/env/timeout through the guard. */
72
+ executeShell(input: ExecuteShellInput): Promise<ExecuteShellResult>;
73
+ /** Run a git subcommand through the guard. */
74
+ runGit(input: RunGitInput): Promise<ExecuteShellResult>;
75
+ }
76
+ /**
77
+ * Terminal status of a single skill execution. Mirrors the playbook runtime's
78
+ * `DispatchResult.status` so a {@link SkillExecutor} envelope is structurally
79
+ * compatible with an `AgentDispatcher` result.
80
+ */
81
+ export type SkillExecuteStatus = 'success' | 'failure';
82
+ /**
83
+ * Input envelope for a single skill execution (AC1: `{ skillId, context, tools }`).
84
+ *
85
+ * The executor receives the skill identity, an opaque accumulated context, and
86
+ * the guarded tool surface it is permitted to use. It MUST NOT reach for
87
+ * ambient/global tools — all side effects flow through {@link SkillExecuteInput.tools}.
88
+ */
89
+ export interface SkillExecuteInput {
90
+ /** Stable identifier of the skill to execute (registry slug / id). */
91
+ readonly skillId: string;
92
+ /**
93
+ * Accumulated bindings / inputs for this execution. Opaque key-value map so
94
+ * the contract stays decoupled from any concrete skill's parameter schema;
95
+ * each skill validates its own slice of this at the adapter boundary.
96
+ */
97
+ readonly context: Readonly<Record<string, unknown>>;
98
+ /**
99
+ * The deny-first guarded tool surface the executor may use. Injected by the
100
+ * caller (DIP) — the executor never constructs its own guard.
101
+ */
102
+ readonly tools: GuardedToolSurface;
103
+ }
104
+ /**
105
+ * Terminal result envelope of a single skill execution (AC1: `{ status, output,
106
+ * error }`). Mirrors the playbook runtime's `DispatchResult` shape so callers
107
+ * that already consume `AgentDispatcher` results can consume a `SkillExecutor`
108
+ * result without a wrapper.
109
+ */
110
+ export interface SkillExecuteResult {
111
+ /** Whether the skill execution succeeded or failed. */
112
+ readonly status: SkillExecuteStatus;
113
+ /**
114
+ * Key-value pairs produced by the skill, merged into the caller's context on
115
+ * success. Empty (not absent) when a skill produces no bindings.
116
+ */
117
+ readonly output: Readonly<Record<string, unknown>>;
118
+ /**
119
+ * Human-readable failure reason. Present iff
120
+ * `status === 'failure'`; omitted on success.
121
+ */
122
+ readonly error?: string;
123
+ }
124
+ /**
125
+ * Dependency-Inversion abstraction for the in-process skill executor.
126
+ *
127
+ * The skill dispatcher depends on THIS interface; the concrete
128
+ * `SkillExecutorAdapter` (T11477) — which wires a GenKit/LLM flow over the
129
+ * injected {@link GuardedToolSurface} — is supplied by injection. A
130
+ * `SkillExecutor` is an in-process `AgentDispatcher`-shaped executor: it
131
+ * resolves and runs a single skill and returns a success/failure envelope; it
132
+ * is NOT a session lifecycle owner (deliberately NOT `SessionEngine`, AC3).
133
+ *
134
+ * @example
135
+ * ```ts
136
+ * // High-level dispatch policy depends on the abstraction, not the adapter.
137
+ * async function runOneSkill(
138
+ * executor: SkillExecutor,
139
+ * skillId: string,
140
+ * tools: GuardedToolSurface,
141
+ * ): Promise<SkillExecuteResult> {
142
+ * return executor.execute({ skillId, context: {}, tools });
143
+ * }
144
+ * ```
145
+ */
146
+ export interface SkillExecutor {
147
+ /**
148
+ * Execute a single skill and return a terminal success/failure envelope.
149
+ *
150
+ * @param input - Skill identity, accumulated context, and the guarded tool
151
+ * surface the skill is permitted to use.
152
+ * @returns The terminal {@link SkillExecuteResult} for this execution.
153
+ */
154
+ execute(input: SkillExecuteInput): Promise<SkillExecuteResult>;
155
+ }
156
+ //# sourceMappingURL=skill-executor.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"skill-executor.d.ts","sourceRoot":"","sources":["../../src/tools/skill-executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,OAAO,KAAK,EACV,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,WAAW,EACX,cAAc,EACd,eAAe,EAChB,MAAM,aAAa,CAAC;AAMrB;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,kBAAkB;IACjC,6CAA6C;IAC7C,YAAY,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAC5D,kDAAkD;IAClD,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACtC,mEAAmE;IACnE,eAAe,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IACjE,oDAAoD;IACpD,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC9D,qEAAqE;IACrE,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACpE,8CAA8C;IAC9C,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;CACzD;AAMD;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,SAAS,CAAC;AAEvD;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,sEAAsE;IACtE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACpD;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAC;CACpC;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,uDAAuD;IACvD,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACnD;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAMD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;OAMG;IACH,OAAO,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;CAChE"}
@@ -0,0 +1,47 @@
1
+ /**
2
+ * `SkillExecutor` — the Dependency-Inversion (DIP) seam for the GenKit-phase
3
+ * skill dispatcher (P1 · T11476 · E-SKILL-EXECUTOR-CONTRACT · epic T11391).
4
+ *
5
+ * A **skill** is a multi-step capability composed from the atomic tool
6
+ * primitives ({@link ./atomic.js}) — read/write/search/shell/etc. The atomic
7
+ * tool layer is pure side-effect plumbing; the SKILLS layer is where those
8
+ * primitives are sequenced into a unit of agent work (run a lint, scaffold a
9
+ * file, summarize a tree). This module declares the ABSTRACTION the dispatcher
10
+ * depends on so the concrete in-process implementation
11
+ * (`SkillExecutorAdapter`, T11477) can be INJECTED rather than imported. That is
12
+ * the classic DIP move: high-level dispatch policy and low-level execution
13
+ * mechanism both depend on this contract, not on each other.
14
+ *
15
+ * ## Why it lives in `@cleocode/contracts`
16
+ *
17
+ * The skill dispatcher (a high-level orchestration concern) and the executor
18
+ * adapter (a low-level mechanism wiring an LLM/GenKit flow over the guarded
19
+ * tools) must agree on ONE shape without either importing the other. Putting the
20
+ * interface here — alongside the atomic-tool I/O shapes it builds on — lets
21
+ * `core`, `mcp-adapter`, `caamp`, and `cleo-os` bind to a single seam and lets
22
+ * tests substitute a fake executor with no runtime dependency.
23
+ *
24
+ * ## Boundary contract (T11476 acceptance)
25
+ *
26
+ * - **AC1** — `execute({ skillId, context, tools }) -> Promise<{ status, output,
27
+ * error }>`. The result envelope intentionally mirrors the playbook runtime's
28
+ * `AgentDispatcher.dispatch()` result so a `SkillExecutor` reads as an
29
+ * in-process `AgentDispatcher` specialization (NOT a clone of it).
30
+ * - **AC2** — depends ONLY on the guarded-tool surface ({@link GuardedToolSurface},
31
+ * itself derived purely from {@link ./atomic.js} I/O shapes) and contract-local
32
+ * types. ZERO `@cleocode/*` runtime coupling: the `tools` dependency is the
33
+ * structural shape of `@cleocode/core`'s `createToolGuard()` result, declared
34
+ * here so neither contracts nor the dispatcher import `core`.
35
+ * - **AC3** — deliberately NOT named `SessionEngine` (that collides with
36
+ * `core/src/sessions/`). A `SkillExecutor` is an in-process
37
+ * `AgentDispatcher`-shaped executor, not a session lifecycle owner.
38
+ *
39
+ * Types-only — no runtime logic (Gate 10 `contracts-purity`).
40
+ *
41
+ * @epic T11391
42
+ * @task T11476
43
+ * @saga T11387
44
+ * @see ./atomic.js — the tool I/O shapes this seam composes over
45
+ */
46
+ export {};
47
+ //# sourceMappingURL=skill-executor.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"skill-executor.js","sourceRoot":"","sources":["../../src/tools/skill-executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cleocode/contracts",
3
- "version": "2026.5.134",
3
+ "version": "2026.6.1",
4
4
  "description": "Domain types, interfaces, and contracts for the CLEO ecosystem",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
@@ -26,6 +26,10 @@
26
26
  "types": "./dist/tools/composite.d.ts",
27
27
  "import": "./dist/tools/composite.js"
28
28
  },
29
+ "./tools/skill-executor": {
30
+ "types": "./dist/tools/skill-executor.d.ts",
31
+ "import": "./dist/tools/skill-executor.js"
32
+ },
29
33
  "./gateway.js": {
30
34
  "types": "./dist/gateway.d.ts",
31
35
  "import": "./dist/gateway.js"
@@ -178,7 +182,7 @@
178
182
  "dependencies": {
179
183
  "zod": "^4.3.6",
180
184
  "zod-to-json-schema": "^3.25.2",
181
- "@cleocode/lafs": "2026.5.134"
185
+ "@cleocode/lafs": "2026.6.1"
182
186
  },
183
187
  "scripts": {
184
188
  "build": "tsc -b --force && node scripts/copy-assets.mjs && node scripts/emit-schemas.mjs",