@cleocode/playbooks 2026.6.13 → 2026.6.15

package/src/runtime.ts

@@ -48,13 +48,17 @@ import type {
   PlaybookNode,
   PlaybookRun,
   PlaybookRunStatus,
+  SubstitutionContext,
 } from '@cleocode/contracts';
 // T11762 ST-2: registry-driven ensures.schema resolution. The bodied accessors
 // live in `@cleocode/core` (Gate-10 contracts-purity forbids them in the
 // contracts leaf); core does NOT depend on playbooks, so this import direction
 // is cycle-free (mirrors the existing `@cleocode/core/store/schema` import in
 // `./schema.ts`).
-import { getEnsuresSchema, listEnsuresSchemaNames } from '@cleocode/core';
+// T1944 (M4): `defaultVariableResolver` is the canonical T1238 mustache engine,
+// re-used here (DRY) to resolve `PlaybookAgenticNode.inputs` `{{path}}`
+// templates at the dispatch boundary rather than re-implementing substitution.
+import { defaultVariableResolver, getEnsuresSchema, listEnsuresSchemaNames } from '@cleocode/core';
 import { createApprovalGate, getPlaybookSecret } from './approval.js';
 import {
   createPlaybookApproval,
@@ -84,8 +88,69 @@ export interface AgentDispatchInput {
   taskId: string;
   /** Snapshot of the accumulated bindings at dispatch time. */
   context: Record<string, unknown>;
+  /**
+   * Per-step resolved bindings for this node (T1944 · M4 cantbook done-gate).
+   *
+   * Additive field. Built by {@link resolveStepBindings} from
+   * {@link PlaybookAgenticNode.inputs} — each declared input is a mustache
+   * `{{path}}` template resolved against the accumulated run `context` (via the
+   * canonical T1238 {@link DefaultVariableResolver}), then layered ON TOP of
+   * that context so a step input SHADOWS a same-named context key.
+   *
+   * The runtime always populates this when dispatching an agentic node (it is a
+   * shallow copy of `context` when the node declares no `inputs`). It is typed
+   * optional only to keep the change strictly additive for any out-of-tree
+   * dispatcher that constructs an {@link AgentDispatchInput} directly.
+   *
+   * Resolver precedence (highest → lowest):
+   * `step bindings ⊳ playbook bindings (run context) ⊳ session ⊳ project-context ⊳ env ⊳ default`.
+   */
+  bindings?: Record<string, unknown>;
   /** 1-based iteration counter for this specific node (retry-aware). */
   iteration: number;
+  /**
+   * Name of the running playbook (`.cantbook`) — the first segment of the
+   * cantbook node identity `cantbook:<playbook>#<nodeId>` (T11759 · M4).
+   *
+   * Additive. The runtime always populates it for agentic nodes; the dispatcher
+   * uses it (with {@link nodeId}) to resolve a declared per-stage LLM profile
+   * through the E9 chokepoint. Optional only so an out-of-tree dispatcher that
+   * constructs an {@link AgentDispatchInput} directly remains source-compatible.
+   */
+  playbookName?: string;
+  /**
+   * The node's declared per-stage LLM pin (T11759 · M4) — lifted verbatim from
+   * {@link PlaybookAgenticNode.profile} / `.model` / `.provider`.
+   *
+   * Additive + all-optional. When any field is set the dispatcher resolves the
+   * stage's LLM through `resolveLLMForSystem` keyed by the cantbook node
+   * identity, honoring the profile pin; when all are unset resolution is
+   * unchanged. The runtime NEVER acts on these itself — it only forwards them.
+   */
+  profile?: string;
+  /** Inline model-id pin forwarded from {@link PlaybookAgenticNode.model} (T11759). */
+  model?: string;
+  /** Inline provider pin forwarded from {@link PlaybookAgenticNode.provider} (T11759). */
+  provider?: string;
+  /**
+   * Per-step skill allowlist lifted verbatim from
+   * {@link PlaybookAgenticNode.allowed_skills} (T1947 · M4).
+   *
+   * Additive + optional. When present the dispatcher passes it to
+   * `composeSpawnPayload`, which intersects it with the resolved agent's skill
+   * baseline (Tier-0/1/2) — the allowlist can only RESTRICT, never expand. When
+   * absent the spawn carries its full baseline skill set. The runtime NEVER acts
+   * on this itself — it only forwards it.
+   */
+  allowedSkills?: string[];
+  /**
+   * Per-step tool allowlist lifted verbatim from
+   * {@link PlaybookAgenticNode.allowed_tools} (T1947 · M4).
+   *
+   * Same restrict-only intersection semantics as {@link allowedSkills}, applied
+   * to the spawn's tool baseline.
+   */
+  allowedTools?: string[];
 }
 
 /**
@@ -500,6 +565,75 @@ function resolveNode(nodeId: string, idx: NodeIndex): PlaybookNode {
 // Per-node execution
 // ---------------------------------------------------------------------------
 
+/**
+ * Resolve a {@link PlaybookAgenticNode}'s declared `inputs` into the per-step
+ * binding map handed to the dispatcher (T1944 · M4 cantbook done-gate).
+ *
+ * Each `inputs` value is a mustache `{{path}}` template. Templates are resolved
+ * against the accumulated run `context` using the canonical T1238
+ * {@link DefaultVariableResolver} (no second substitution engine — DRY) and the
+ * resolved key/value pairs are then layered ON TOP of the run context. The
+ * result is the dispatch-time binding map.
+ *
+ * ## Canonical resolver precedence (highest → lowest)
+ *
+ * 1. **step bindings** — the resolved `node.inputs` themselves. They are merged
+ *    LAST over the run context, so a step input always SHADOWS a same-named
+ *    context key (AC3 / AC6).
+ * 2. **playbook bindings** — the accumulated run `context` (seeded from the
+ *    playbook's declared inputs + every prior node's merged output).
+ * 3. **session / project-context / env / default** — supplied to the underlying
+ *    {@link DefaultVariableResolver} via the {@link SubstitutionContext} below.
+ *
+ * The run `context` is exposed to the resolver through BOTH the `projectContext`
+ * tier (which supports dot-notation, so `{{inputs.epicId}}` and `{{context.foo}}`
+ * resolve into nested objects) and `process.env` (the `env` tier). The
+ * resolver runs in lenient mode.
+ *
+ * ## Missing-key rule
+ *
+ * Lenient. When a `{{path}}` template references a value that resolves through
+ * NO tier, the literal placeholder text is left intact in the bound value (e.g.
+ * `{{missing}}` stays `"{{missing}}"`). This mirrors the canonical T1238
+ * lenient posture — a missing input never aborts the dispatch; the agent
+ * receives the literal placeholder and can fail loudly downstream if required.
+ *
+ * @param node - The agentic node whose `inputs` are resolved.
+ * @param context - The accumulated run bindings at dispatch time.
+ * @returns A new binding map = `{ ...context, ...resolvedStepInputs }`. When the
+ *   node declares no `inputs`, this is a shallow copy of `context`.
+ */
+export function resolveStepBindings(
+  node: PlaybookAgenticNode,
+  context: Record<string, unknown>,
+): Record<string, unknown> {
+  // No declared inputs — bindings are just a snapshot of the run context.
+  if (node.inputs === undefined || Object.keys(node.inputs).length === 0) {
+    return { ...context };
+  }
+
+  // Expose the run context to the canonical resolver. `projectContext` is the
+  // dot-notation-capable tier, so `{{inputs.epicId}}` / `{{context.foo.bar}}`
+  // walk into nested objects; flat keys (`{{epicId}}`) resolve via a
+  // single-segment walk on the same tier.
+  const substitutionContext: SubstitutionContext = {
+    projectContext: context,
+    env: process.env,
+  };
+
+  const resolvedInputs: Record<string, unknown> = {};
+  for (const [key, template] of Object.entries(node.inputs)) {
+    // Lenient resolve — missing placeholders are left literal (see TSDoc).
+    const result = defaultVariableResolver.resolve(template, substitutionContext, {
+      strict: false,
+    });
+    resolvedInputs[key] = result.text;
+  }
+
+  // Step bindings shadow the run context for same-named keys (AC3 / AC6).
+  return { ...context, ...resolvedInputs };
+}
+
 /**
  * Execute a single `agentic` node via the injected {@link AgentDispatcher}.
  * The dispatcher receives the current context and must return a success /
@@ -511,6 +645,7 @@ async function executeAgenticNode(
   context: Record<string, unknown>,
   iteration: number,
   dispatcher: AgentDispatcher,
+  playbookName: string,
 ): Promise<NodeOutcome> {
   const agentId = node.agent ?? node.skill;
   if (agentId === undefined) {
@@ -523,6 +658,10 @@ async function executeAgenticNode(
   const taskIdRaw = context['taskId'];
   const taskId = typeof taskIdRaw === 'string' && taskIdRaw.length > 0 ? taskIdRaw : runId;
 
+  // T1944 (M4): resolve `node.inputs` `{{path}}` templates against the run
+  // context and layer them on top so step inputs shadow context (AC1/AC2/AC3).
+  const bindings = resolveStepBindings(node, context);
+
   try {
     const result = await dispatcher.dispatch({
       runId,
@@ -530,7 +669,20 @@ async function executeAgenticNode(
       agentId,
       taskId,
       context: { ...context },
+      bindings,
       iteration,
+      // T11759 (M4): forward the playbook name + the node's per-stage LLM pin so
+      // the dispatcher can resolve a declared `profile:` through the E9
+      // chokepoint. All-additive; omitted when the node declares no pin.
+      playbookName,
+      ...(node.profile !== undefined ? { profile: node.profile } : {}),
+      ...(node.model !== undefined ? { model: node.model } : {}),
+      ...(node.provider !== undefined ? { provider: node.provider } : {}),
+      // T1947 (M4): forward the per-step skill/tool allowlists so the dispatcher
+      // can intersect them against the Tier-0/1/2 baseline at spawn time. Omitted
+      // when the node declares no allowlist (additive — baseline unchanged).
+      ...(node.allowed_skills !== undefined ? { allowedSkills: node.allowed_skills } : {}),
+      ...(node.allowed_tools !== undefined ? { allowedTools: node.allowed_tools } : {}),
     });
     if (result.status === 'success') {
       return { kind: 'success', output: result.output };
@@ -846,7 +998,14 @@ async function runFromNode(args: {
 
     let outcome: NodeOutcome;
     if (node.type === 'agentic') {
-      outcome = await executeAgenticNode(node, run.runId, context, attempt, dispatcher);
+      outcome = await executeAgenticNode(
+        node,
+        run.runId,
+        context,
+        attempt,
+        dispatcher,
+        playbook.name,
+      );
     } else if (node.type === 'deterministic') {
       outcome = await executeDeterministicNode(
         node,