owenloop 0.5.9 → 0.5.10

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 (83) hide show
  1. package/CHANGELOG.md +44 -0
  2. package/README.md +77 -37
  3. package/bin/owenloop.mjs +16 -1
  4. package/dist/packages/work/src/agent/loop.js +7 -0
  5. package/dist/packages/work/src/bundle/pull.d.ts +21 -0
  6. package/dist/packages/work/src/bundle/pull.js +118 -0
  7. package/dist/packages/work/src/exec/instructions.d.ts +4 -1
  8. package/dist/packages/work/src/exec/instructions.js +3 -0
  9. package/dist/packages/work/src/exec/loop.d.ts +1 -1
  10. package/dist/packages/work/src/exec/loop.js +92 -14
  11. package/dist/packages/work/src/harness/claude.js +16 -0
  12. package/dist/packages/work/src/harness/codex.d.ts +8 -0
  13. package/dist/packages/work/src/harness/codex.js +27 -1
  14. package/dist/packages/work/src/harness/contract.d.ts +9 -0
  15. package/dist/packages/work/src/roles/agent-run.js +38 -10
  16. package/dist/packages/work/src/roles/exec.js +25 -8
  17. package/dist/packages/work/src/shift/loop.js +118 -4
  18. package/dist/packages/work/src/shift/runtime.d.ts +3 -0
  19. package/dist/packages/work/src/shift/runtime.js +10 -1
  20. package/dist/packages/work/src/submit-proof.d.ts +11 -8
  21. package/dist/packages/work/src/submit-proof.js +11 -8
  22. package/dist/src/capabilities.d.ts +70 -6
  23. package/dist/src/capabilities.js +49 -6
  24. package/dist/src/capability-mapping-client.d.ts +29 -0
  25. package/dist/src/capability-mapping-client.js +160 -0
  26. package/dist/src/cli.d.ts +2 -2
  27. package/dist/src/cli.js +1196 -164
  28. package/dist/src/defs.d.ts +32 -1
  29. package/dist/src/defs.js +391 -79
  30. package/dist/src/engine.d.ts +62 -19
  31. package/dist/src/engine.js +180 -70
  32. package/dist/src/hub.d.ts +77 -0
  33. package/dist/src/hub.js +162 -0
  34. package/dist/src/implements.d.ts +56 -0
  35. package/dist/src/implements.js +790 -0
  36. package/dist/src/index.d.ts +8 -6
  37. package/dist/src/index.js +4 -3
  38. package/dist/src/mcp/serve.js +254 -45
  39. package/dist/src/mcp/server.d.ts +10 -7
  40. package/dist/src/mcp/server.js +53 -8
  41. package/dist/src/model.d.ts +46 -10
  42. package/dist/src/model.js +220 -74
  43. package/dist/src/store/def-source.d.ts +19 -0
  44. package/dist/src/store/def-source.js +87 -17
  45. package/dist/src/store/gc-recovery.d.ts +46 -0
  46. package/dist/src/store/gc-recovery.js +258 -0
  47. package/dist/src/store/gc.d.ts +94 -0
  48. package/dist/src/store/gc.js +562 -0
  49. package/dist/src/store/index.d.ts +3 -1
  50. package/dist/src/store/index.js +2 -0
  51. package/dist/src/store/install.d.ts +34 -5
  52. package/dist/src/store/install.js +73 -11
  53. package/dist/src/store/pre-commit-verifier.js +42 -2
  54. package/dist/src/store/snapshot-guard.d.ts +18 -0
  55. package/dist/src/store/snapshot-guard.js +94 -0
  56. package/dist/src/store.d.ts +64 -4
  57. package/dist/src/store.js +211 -8
  58. package/dist/src/types.d.ts +61 -17
  59. package/dist/src/util.js +4 -1
  60. package/docs/authoring.md +145 -8
  61. package/docs/bundles.md +19 -0
  62. package/docs/cli.md +270 -30
  63. package/docs/crypto.md +13 -7
  64. package/docs/design.md +107 -46
  65. package/docs/evals/mcp-charter-baseline.json +428 -0
  66. package/docs/mcp-charter-eval.md +124 -0
  67. package/docs/shift-logs.md +18 -0
  68. package/docs/wire-contracts.md +28 -7
  69. package/examples/workflows/compile-dev-playbook.yaml +1 -1
  70. package/examples/workflows/ship.yaml +28 -2
  71. package/package.json +2 -1
  72. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
  73. package/plugins/claude-code/plugin/.mcp.json +1 -1
  74. package/plugins/claude-code/plugin/skills/author/SKILL.md +22 -0
  75. package/plugins/claude-code/plugin/skills/ephemeral/SKILL.md +95 -0
  76. package/plugins/claude-code/plugin/skills/graduate/SKILL.md +156 -0
  77. package/plugins/claude-code/plugin/skills/plan/SKILL.md +236 -0
  78. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
  79. package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
  80. package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +22 -0
  81. package/plugins/codex/plugins/owenloop/skills/ephemeral/SKILL.md +95 -0
  82. package/plugins/codex/plugins/owenloop/skills/graduate/SKILL.md +156 -0
  83. package/plugins/codex/plugins/owenloop/skills/plan/SKILL.md +236 -0
@@ -22,22 +22,25 @@
22
22
  * `pumpStdin` wires the real `process.stdin`/`process.stdout` in the roles.
23
23
  *
24
24
  * Supported methods (the subset an MCP host needs):
25
- * - `initialize` → capabilities `{tools:{}}`, serverInfo, and the
26
- * agreed protocolVersion (echo the client's when
27
- * recognized, else answer with ours).
25
+ * - `initialize` → capabilities `{tools:{}}`, serverInfo,
26
+ * instructions, and the agreed protocolVersion
27
+ * (echo the client's when recognized, else
28
+ * answer with ours).
28
29
  * - `notifications/initialized` → no-op (no response; it is a notification).
29
30
  * - `ping` → `{}`.
30
31
  * - `tools/list` → the registered tool defs.
31
- * - `tools/call` → dispatch to the tool handler; the result is
32
- * `{content:[{type:'text',text:<JSON>}], isError?}`.
32
+ * - `tools/call` → validate arguments against the registered
33
+ * input schema, then dispatch to the handler;
34
+ * the result is `{content:[{type:'text',text:<JSON>}], isError?}`.
33
35
  * - `notifications/cancelled` → abort a tracked in-flight `tools/call`; the
34
36
  * aborted call sends NO response frame.
35
37
  * - outbound `notifications/progress` when a call carried
36
38
  * `params._meta.progressToken` (via `ctx.sendProgress`).
37
39
  *
38
40
  * Errors: unknown method → -32601; malformed JSON / bad envelope → -32700;
39
- * invalid params → -32602. A notification (no `id`) never gets a response, even
40
- * on error. The process must never crash on a bad line.
41
+ * invalid params (including a tool-schema mismatch) → -32602. A notification
42
+ * (no `id`) never gets a response, even on error. The process must never crash
43
+ * on a bad line.
41
44
  */
42
45
  export declare const PARSE_ERROR = -32700;
43
46
  export declare const INVALID_REQUEST = -32600;
@@ -22,23 +22,27 @@
22
22
  * `pumpStdin` wires the real `process.stdin`/`process.stdout` in the roles.
23
23
  *
24
24
  * Supported methods (the subset an MCP host needs):
25
- * - `initialize` → capabilities `{tools:{}}`, serverInfo, and the
26
- * agreed protocolVersion (echo the client's when
27
- * recognized, else answer with ours).
25
+ * - `initialize` → capabilities `{tools:{}}`, serverInfo,
26
+ * instructions, and the agreed protocolVersion
27
+ * (echo the client's when recognized, else
28
+ * answer with ours).
28
29
  * - `notifications/initialized` → no-op (no response; it is a notification).
29
30
  * - `ping` → `{}`.
30
31
  * - `tools/list` → the registered tool defs.
31
- * - `tools/call` → dispatch to the tool handler; the result is
32
- * `{content:[{type:'text',text:<JSON>}], isError?}`.
32
+ * - `tools/call` → validate arguments against the registered
33
+ * input schema, then dispatch to the handler;
34
+ * the result is `{content:[{type:'text',text:<JSON>}], isError?}`.
33
35
  * - `notifications/cancelled` → abort a tracked in-flight `tools/call`; the
34
36
  * aborted call sends NO response frame.
35
37
  * - outbound `notifications/progress` when a call carried
36
38
  * `params._meta.progressToken` (via `ctx.sendProgress`).
37
39
  *
38
40
  * Errors: unknown method → -32601; malformed JSON / bad envelope → -32700;
39
- * invalid params → -32602. A notification (no `id`) never gets a response, even
40
- * on error. The process must never crash on a bad line.
41
+ * invalid params (including a tool-schema mismatch) → -32602. A notification
42
+ * (no `id`) never gets a response, even on error. The process must never crash
43
+ * on a bad line.
41
44
  */
45
+ import { summarizeIssues, validateValue } from "../schema.js";
42
46
  /** The MCP revisions this server will agree to echo back on `initialize`. */
43
47
  const RECOGNIZED_PROTOCOL_VERSIONS = new Set([
44
48
  '2024-11-05',
@@ -48,6 +52,36 @@ const RECOGNIZED_PROTOCOL_VERSIONS = new Set([
48
52
  ]);
49
53
  /** The version we answer with when the client's is missing or unrecognized. */
50
54
  const OUR_PROTOCOL_VERSION = '2025-06-18';
55
+ // The charter is served verbatim at MCP initialization and its bytes are hashed
56
+ // into docs/evals/mcp-charter-baseline.json. Any edit here invalidates that
57
+ // baseline. Regenerating it needs the --output flag — a bare
58
+ // `npm run eval:mcp-charter` prints the report and writes nothing:
59
+ //
60
+ // npm run eval:mcp-charter -- --output docs/evals/mcp-charter-baseline.json
61
+ //
62
+ // Commit the charter edit and the regenerated baseline together.
63
+ //
64
+ // One run is one sample, not a measurement. Codex's score moves between runs
65
+ // at a FIXED charter sha: 35773e2e scored 3/4, 4/4 and 4/4 on three runs
66
+ // across fifteen minutes. Read the committed number as a point in a range, and
67
+ // re-run before concluding an edit helped or hurt. The run history and the
68
+ // per-arm ranges live in docs/mcp-charter-eval.md.
69
+ //
70
+ // search_workflows is deliberately NOT named here. The eval scores the first
71
+ // tool call, and offering a second discovery verb in the charter competes with
72
+ // the catalog read this paragraph exists to force. Its own tool description
73
+ // carries when to prefer it.
74
+ const CHIEF_OF_STAFF_INSTRUCTIONS = `Owenloop is a control plane for delegated multi-step work. Act as the human's chief of staff, not as an inline worker.
75
+
76
+ Call \`list_workflows\` on every request, before you answer it, before you ask the human for missing inputs, and before you start any work. There is no request too small, too urgent, or too far outside software for this: you cannot know what the human has published without reading the catalog. Then inspect promising definitions; an existing playbook beats freelancing. When one fits, use \`start_run\` and let its crews execute. Do not perform step work inline unless no available crew serves the required capability. \`submit\` is for a crew member returning a held order, not for a chief of staff to fabricate progress.
77
+
78
+ After starting or attending runs, park on \`wake\`; when its cursor changes, call \`whats_next\`. Use \`whats_next\` directly when a workflow needs a tick or the human asks for their inbox. Relay gates, worker asks, receipts, and status clearly to the human. Use \`provide_input\` for seeded or owed human inputs. Use \`retry_artifact\` with the human's answer when a worker escalated with an ask.
79
+
80
+ Treat rejection as feedback that must be surfaced and resolved. Never bypass a rejected artifact to force progress; use \`reject_artifact\` only to send an actual upstream defect back with a concrete reason.
81
+
82
+ For your own complex one-off work that needs a workflow, use the ephemeral skill. Its explicitly ephemeral, caller-owned run is the exception: the caller may execute its served orders and return their real outputs with \`submit\` before retiring the name. Ordinary durable runs remain crew-first and never justify fabricated progress.
83
+
84
+ If no listed playbook fits, say so plainly and ask the human how they want to proceed.`;
51
85
  // ---- JSON-RPC error codes ---------------------------------------------------
52
86
  export const PARSE_ERROR = -32700;
53
87
  export const INVALID_REQUEST = -32600;
@@ -105,8 +139,18 @@ export function createMcpServer(opts) {
105
139
  replyError(id, METHOD_NOT_FOUND, `unknown tool '${name}'`);
106
140
  return;
107
141
  }
142
+ const hasArguments = 'arguments' in params;
108
143
  const rawArgs = params['arguments'];
109
- const args = isObject(rawArgs) ? rawArgs : {};
144
+ if (hasArguments && !isObject(rawArgs)) {
145
+ replyError(id, INVALID_PARAMS, 'tools/call "arguments" must be an object when supplied');
146
+ return;
147
+ }
148
+ const args = hasArguments ? rawArgs : {};
149
+ const shape = validateValue(reg.inputSchema, args);
150
+ if (!shape.valid) {
151
+ replyError(id, INVALID_PARAMS, `invalid arguments for tool '${name}': ${summarizeIssues(shape.issues)}`);
152
+ return;
153
+ }
110
154
  const progressToken = readProgressToken(params);
111
155
  const tracked = { cancelled: false, byClose: false, cancelCbs: [] };
112
156
  // Only tracked when it has a concrete id (a notification cannot be cancelled).
@@ -182,6 +226,7 @@ export function createMcpServer(opts) {
182
226
  protocolVersion: agreed,
183
227
  capabilities: { tools: {} },
184
228
  serverInfo: { name: opts.name, version: opts.version },
229
+ instructions: CHIEF_OF_STAFF_INSTRUCTIONS,
185
230
  });
186
231
  }
187
232
  function handleToolsList(id) {
@@ -36,6 +36,14 @@ export interface Firing {
36
36
  /** The trigger that made this firing eligible (§21). Absent means 'inputsGreen'. */
37
37
  cause?: FiringTrigger;
38
38
  }
39
+ /**
40
+ * A model-only authority action: a non-judge consumer retracts a bare
41
+ * collection member. This is not an eligible worker run, so it must stay out
42
+ * of `eligibleFirings()` (which is also the live scheduler).
43
+ */
44
+ export interface MemberRetractFiring extends Firing {
45
+ modelTransition: 'member-retract';
46
+ }
39
47
  /** A structural maintenance op the engine should apply (level-triggered). */
40
48
  export type CascadeOp = {
41
49
  kind: 'reject';
@@ -261,6 +269,20 @@ export declare function fingerprintMatches(arts: ArtifactMap, paths: readonly st
261
269
  * moment its bound element greens (dynamic cardinality, §11.1).
262
270
  */
263
271
  export declare function pendingOwed(def: WorkflowDef, arts: ArtifactMap): ArtifactData[];
272
+ /**
273
+ * The model-only collection-member retractions available in THIS state.
274
+ *
275
+ * `Engine.retract()` is an authority action rather than a scheduler action:
276
+ * every existing bare member that is not already retracted remains available
277
+ * to each authorized non-judge consumer. In particular, the transition must
278
+ * remain available after rejection, when a member has no ordinary map firing;
279
+ * otherwise modelCheck would call that runtime-valid state a deadlock.
280
+ *
281
+ * Kept separate from `eligibleFirings` deliberately: that function is the
282
+ * live worker scheduler, while these synthetic firings are consumed only by
283
+ * modelCheck's successor expansion.
284
+ */
285
+ export declare function memberRetractFirings(def: WorkflowDef, arts: ArtifactMap): MemberRetractFiring[];
264
286
  /**
265
287
  * Every firing eligible *right now* — inputs satisfied AND an owed/rejected
266
288
  * output to discharge. This is the scheduling gate (§11.4): necessary, not
@@ -308,9 +330,11 @@ export declare function canEverFire(step: StepDef, def: WorkflowDef, reachable?:
308
330
  * The standing guard: re-derive the invariant "an artifact is green only while
309
331
  * every artifact it directly consumed is green and unmoved" and report the
310
332
  * structural ops needed to restore it. Pure — the engine applies the ops and
311
- * re-runs to a fixpoint. Covers the forward reject cascade, retract/skip
312
- * tombstoning of map children, skip-propagation down dead branches, and the
313
- * re-arm of a skipped subtree when its branch revives.
333
+ * re-runs to a fixpoint. Covers ordinary build-fingerprint invalidation,
334
+ * retract/skip tombstoning of map children, skip-propagation down dead branches,
335
+ * and skipped-subtree revival. Calls gates are maintenance-local: they settle a
336
+ * dead calls branch and revive its engine cascade skip, but never validate a
337
+ * green calls fingerprint (which also includes a child-outcome pin).
314
338
  */
315
339
  export declare function maintainDecisions(def: WorkflowDef, arts: ArtifactMap, time?: TimeFacts): CascadeOp[];
316
340
  export interface Blocker {
@@ -413,6 +437,16 @@ export interface WorkflowStatus {
413
437
  heartbeatAgeMs?: number;
414
438
  }>;
415
439
  }
440
+ /**
441
+ * Whether one workflow instance has no outstanding artifact state (§17/§26).
442
+ *
443
+ * `atLeastOne` is the sole exception to a straight outstanding-state scan:
444
+ * once any member is green, owed siblings may remain untouched forever without
445
+ * keeping the workflow open. This predicate is intentionally cheaper than
446
+ * `workflowStatus` so hot engine paths can share its exact completion rule
447
+ * without building debts, eligibility, blockers, or pending-judge details.
448
+ */
449
+ export declare function workflowDone(def: WorkflowDef, arts: ArtifactMap): boolean;
416
450
  /** Derive the operator view purely from artifact state (§17) — never stored. */
417
451
  export declare function workflowStatus(def: WorkflowDef, arts: ArtifactMap): WorkflowStatus;
418
452
  export { SETTLED_STATES };
@@ -488,7 +522,8 @@ export declare function settleInMemory(def: WorkflowDef, arts: Map<string, Artif
488
522
  * bumping judgmentRejects+1
489
523
  * 'schema-reject' — acceptance rejected, schemaRejects+1 on the output
490
524
  * 'skip' — acceptance skipped + fingerprint of requiredInputs
491
- * 'retract' — acceptance retracted (collection member only)
525
+ * 'retract' — a non-judge consumer retracts an authorized bare
526
+ * collection member; acceptance becomes retracted
492
527
  * 'emit-seal' — collection producer: emit 1..maxCollectionSize green elements,
493
528
  * then seal; forks into (maxCollectionSize+1) successor states
494
529
  *
@@ -504,13 +539,14 @@ export declare function applyOutcome(def: WorkflowDef, arts: Map<string, Artifac
504
539
  * Explores the full (or depth/state-bounded) state space via BFS to find:
505
540
  * - a non-done, zero-eligible-firings state is split into exactly ONE of two
506
541
  * mutually exclusive buckets by recomputing eligibility with every freeze
507
- * lifted (unlimited attempts — see `eligibleFirings`'s `ignoreFreeze`):
508
- * - stall states: the recompute yields >= 1 firing — the state's only
509
- * blocker is a frozen/stalled debt (maxAttempts / maxSchemaFailures /
510
- * held). A by-design human-escalation brake. EXPECTED, never a defect.
542
+ * lifted and eventual idle time (unlimited attempts — see
543
+ * `eligibleFirings`'s `ignoreFreeze`):
544
+ * - stall states: the recompute yields >= 1 firing — a retryable frozen debt
545
+ * or future idle threshold is the only blocker. An expected brake/wait,
546
+ * never a defect.
511
547
  * - true deadlocks: the recompute STILL yields zero firings — a genuine
512
- * structural dead-end with no path to completion even at unlimited
513
- * attempts. A real defect.
548
+ * structural dead-end with no move even after retry or elapsed idle time.
549
+ * A real defect.
514
550
  * - stuck states: reachable states that have a stalled debt but STILL have
515
551
  * >= 1 eligible firing elsewhere (a brake tripped on one branch while the
516
552
  * line moves on another). Informational only; a no-moves state is never