@agenteer/stdlib 1.0.0-rc.1

package/src/meta/repair_loop.ts

@@ -0,0 +1,267 @@
+/**
+ * `@agenteer/node-repair-loop` — meta-node that drives a validate →
+ * repair → validate cycle via ReplaceMe (sub-plan 03 §14).
+ *
+ * **ReplaceMe-first.** Per master plan ratified resolutions, the retry
+ * mechanism is data-driven convergence: each repair pass returns
+ * `replace_me` with a successor carrying the narrowed target. A bounded
+ * `max_iterations` ceiling exists only as a runaway backstop.
+ *
+ * Shape of one iteration:
+ *   1. Run the target node (via `SpawnChildren`).
+ *   2. Run the validator against the target's output.
+ *   3. If validator.verdict === "pass" → Output(final).
+ *      If validator.verdict === "fail" and iter < ceiling →
+ *        ReplaceMe(self with target_input augmented by the failing issues).
+ *      Otherwise → Failed("repair_exhausted").
+ *
+ * This is the node that earns the framework's "self-obsolescence"
+ * pillar — it's where ReplaceMe pays rent in day-to-day workflows.
+ */
+
+import { z } from "zod";
+import {
+  asArtifact,
+  makeManifest,
+  type Node,
+  type NodeInput,
+  type NodeManifest,
+  type NodeResult,
+  type NodeSpawn,
+} from "@agenteer/core";
+import { ValidatorOutputSchema, type ValidatorOutput } from "../shared/index.js";
+
+const MANIFEST: NodeManifest = makeManifest({
+  id: "@agenteer/node-repair-loop",
+  name: "repair_loop",
+  description:
+    "ReplaceMe-first validate/repair loop. Max-iterations is a runaway backstop; progress is data-driven.",
+  determinism: "stochastic",
+  required_actions: [],
+  dynamic_actions: true,
+  // We spawn whichever target + validator the caller names.
+  dynamic_action_spec: "spawn:${input.target_manifest_id}, spawn:${input.validator_manifest_id}",
+  tags: ["meta"],
+  side_effects: {
+    writes_fs: false,
+    network: false,
+    mutates_ctx: true,
+    emits_ctx_variants: ["artifact.repair_loop.result"],
+  },
+});
+
+const InputSchema = z.object({
+  target_manifest_id: z.string().min(1),
+  target_input: z.unknown(),
+  validator_manifest_id: z.string().min(1),
+  validator_input: z.unknown().optional(),
+  max_iterations: z.number().int().min(1).max(32).default(4),
+  iteration: z.number().int().min(0).default(0),
+  /**
+   * Optional ctx tag: final result is emitted as an Artifact under this
+   * name so downstream nodes can read it via ctx.
+   */
+  emit_as: z.string().optional(),
+});
+
+const OutputSchema = z.object({
+  verdict: z.enum(["pass", "fail"]),
+  iterations: z.number().int().nonnegative(),
+  final_output: z.unknown(),
+  last_issues: z
+    .array(
+      z.object({
+        path: z.string().optional(),
+        message: z.string(),
+        code: z.string().optional(),
+        severity: z.enum(["error", "warning"]).optional(),
+      }),
+    )
+    .optional(),
+});
+
+type Input = z.input<typeof InputSchema>;
+type Output = z.infer<typeof OutputSchema>;
+
+const TARGET_CORRELATION = "repair.target";
+const VALIDATOR_CORRELATION = "repair.validator";
+
+export function repairLoopFactory(): Node<Input, Output> {
+  return {
+    manifest: MANIFEST,
+    inputSchema: InputSchema,
+    outputSchema: OutputSchema,
+    ctx: [],
+    model: null,
+    async execute(input: NodeInput<Input>): Promise<NodeResult<Output>> {
+      const i = input.original;
+      const iter = i.iteration ?? 0;
+      const maxIter = i.max_iterations ?? 4;
+
+      if (!input.children) {
+        // No children yet → we're on entry; spawn the target.
+        return {
+          kind: "spawn_children",
+          join: { mode: "all" },
+          children: [
+            {
+              manifest_id: i.target_manifest_id,
+              input: i.target_input,
+              correlation: TARGET_CORRELATION,
+            },
+          ],
+        };
+      }
+
+      // Re-entry. Two shapes to handle:
+      //   (a) only target-result present → spawn validator
+      //   (b) target + validator present → decide
+      const target = input.children.find((c) => c.correlation === TARGET_CORRELATION);
+      const validator = input.children.find((c) => c.correlation === VALIDATOR_CORRELATION);
+
+      if (!target) {
+        return {
+          kind: "failed",
+          reason: "repair_loop: no target child on re-entry",
+          retryable: false,
+          evidence: { verdict: "fail" },
+        };
+      }
+      if (target.result.kind !== "output") {
+        return {
+          kind: "failed",
+          reason: `repair_loop: target failed (${(target.result as { reason?: string }).reason ?? target.result.kind})`,
+          retryable: false,
+          details: { target: target.result },
+          evidence: { verdict: "fail" },
+        };
+      }
+
+      const targetOutput = (target.result as { value: unknown }).value;
+
+      if (!validator) {
+        // Spawn the validator with the target's output merged in.
+        const validatorInput = buildValidatorInput(i.validator_input, targetOutput);
+        return {
+          kind: "spawn_children",
+          join: { mode: "all" },
+          children: [
+            {
+              manifest_id: i.target_manifest_id,
+              input: i.target_input,
+              correlation: TARGET_CORRELATION,
+            },
+            {
+              manifest_id: i.validator_manifest_id,
+              input: validatorInput,
+              correlation: VALIDATOR_CORRELATION,
+            },
+          ],
+        };
+      }
+
+      // Validator present — interpret.
+      if (validator.result.kind !== "output") {
+        return {
+          kind: "failed",
+          reason: `repair_loop: validator failed (${(validator.result as { reason?: string }).reason ?? validator.result.kind})`,
+          retryable: false,
+          evidence: { verdict: "fail" },
+        };
+      }
+      const vParsed = ValidatorOutputSchema.safeParse((validator.result as { value: unknown }).value);
+      if (!vParsed.success) {
+        return {
+          kind: "failed",
+          reason: `repair_loop: validator output not a ValidatorOutput shape`,
+          retryable: false,
+          details: { issues: vParsed.error.issues },
+          evidence: { verdict: "fail" },
+        };
+      }
+      const vout: ValidatorOutput = vParsed.data;
+
+      if (vout.verdict === "pass") {
+        const base: Output = {
+          verdict: "pass",
+          iterations: iter,
+          final_output: targetOutput,
+        };
+        const patch = i.emit_as
+          ? {
+              set: {
+                [i.emit_as]: asArtifact(
+                  { verdict: "pass", iterations: iter, output: targetOutput },
+                  { media_type: "application/json" },
+                ),
+              },
+            }
+          : undefined;
+        return {
+          kind: "output",
+          value: base,
+          ...(patch ? { ctx_patch: patch } : {}),
+          evidence: { verdict: "pass" },
+        };
+      }
+
+      // Validator failed.
+      if (iter + 1 >= maxIter) {
+        return {
+          kind: "output",
+          value: {
+            verdict: "fail",
+            iterations: iter + 1,
+            final_output: targetOutput,
+            last_issues: vout.issues,
+          },
+          evidence: { verdict: "fail" },
+        };
+      }
+
+      // Repair step: ReplaceMe self with `iteration + 1`, feeding the
+      // validator's issues back into target_input as a hint.
+      const successor: NodeSpawn = {
+        manifest_id: MANIFEST.id,
+        // Runtime preserves the frame's correlation on ReplaceMe; this
+        // value is only used for lineage tracking on the successor's
+        // own spawn event.
+        correlation: `repair-iter-${iter + 1}`,
+        input: {
+          ...i,
+          iteration: iter + 1,
+          target_input: {
+            ...(typeof i.target_input === "object" && i.target_input !== null
+              ? (i.target_input as Record<string, unknown>)
+              : { original: i.target_input }),
+            prior_issues: vout.issues,
+            prior_iteration: iter,
+          },
+        },
+      };
+
+      return {
+        kind: "replace_me",
+        reason: `repair_iteration:${iter + 1}:${vout.issues.length}_issues`,
+        successor,
+      };
+    },
+  };
+}
+
+export const repairLoopManifest = MANIFEST;
+
+function buildValidatorInput(
+  baseValidatorInput: unknown,
+  targetOutput: unknown,
+): unknown {
+  // If the caller didn't specify, pass the target output through as
+  // `candidate` — a reasonable default for validators that inspect output.
+  if (baseValidatorInput === undefined || baseValidatorInput === null) {
+    return { candidate: targetOutput };
+  }
+  if (typeof baseValidatorInput === "object") {
+    return { ...(baseValidatorInput as Record<string, unknown>), candidate: targetOutput };
+  }
+  return baseValidatorInput;
+}

package/src/planner/default_planner.ts

@@ -0,0 +1,182 @@
+/**
+ * `@agenteer/node-default-planner` — LLM-driven plan composer (sub-plan 03 §17).
+ *
+ * **Returns a plan as DATA**, not as `SpawnChildren` (master plan ratified
+ * resolution). This enables:
+ *   - Replay: a plan is a value you can serialize, review, and diff.
+ *   - Human approval: pair with `approval_gate` to require sign-off before exec.
+ *   - Judge review: `judge_with_stripped_ctx` can score the plan.
+ *   - Swapping planners: another node consumes the plan and spawns.
+ *
+ * The node emits the plan as an Artifact via `ctx.set(asArtifact(...))`
+ * (uses R3-A) so downstream nodes see it via their context slice.
+ */
+
+import { z } from "zod";
+import {
+  asArtifact,
+  makeManifest,
+  type Node,
+  type NodeInput,
+  type NodeManifest,
+  type NodeResult,
+  type NodeRuntimeHandle,
+} from "@agenteer/core";
+
+const MANIFEST: NodeManifest = makeManifest({
+  id: "@agenteer/node-default-planner",
+  name: "default_planner",
+  description:
+    "LLM-driven planner. Returns a plan (as data + ctx artifact); does NOT spawn the plan itself.",
+  determinism: "stochastic",
+  required_actions: [],
+  dynamic_actions: true,
+  dynamic_action_spec: "model:${input.model_id}",
+  tags: ["meta", "planner"],
+  side_effects: {
+    writes_fs: false,
+    network: true,
+    mutates_ctx: true,
+    emits_ctx_variants: ["artifact.plan"],
+  },
+});
+
+const PlanStepSchema = z.object({
+  id: z.string().min(1),
+  manifest_id: z.string().min(1),
+  input: z.unknown(),
+  rationale: z.string().optional(),
+  depends_on: z.array(z.string()).default([]),
+  attenuate: z.array(z.string()).optional(),
+});
+
+const PlanSchema = z.object({
+  goal: z.string(),
+  steps: z.array(PlanStepSchema).min(1),
+  notes: z.string().optional(),
+});
+
+const InputSchema = z.object({
+  goal: z.string().min(1),
+  /**
+   * Manifests the planner is allowed to include. Structural filter —
+   * the planner picks from this set and only this set. No semantic
+   * "free-for-all"; matches the "planner filters structurally first"
+   * invariant.
+   */
+  available_manifests: z
+    .array(
+      z.object({
+        id: z.string().min(1),
+        name: z.string(),
+        description: z.string(),
+        required_actions: z.array(z.string()).default([]),
+      }),
+    )
+    .min(1),
+  model_id: z.string().min(1),
+  /** Tag under which the plan is emitted to ctx (default: "plan"). */
+  emit_as: z.string().default("plan"),
+});
+
+const OutputSchema = z.object({
+  plan: PlanSchema,
+  model: z.string(),
+  method: z.enum(["native", "text_parse", "mock"]),
+});
+
+type Input = z.input<typeof InputSchema>;
+type Output = z.infer<typeof OutputSchema>;
+
+export function defaultPlannerFactory(): Node<Input, Output> {
+  return {
+    manifest: MANIFEST,
+    inputSchema: InputSchema,
+    outputSchema: OutputSchema,
+    ctx: [],
+    model: null,
+    async execute(input: NodeInput<Input>, handle: NodeRuntimeHandle): Promise<NodeResult<Output>> {
+      const i = input.original;
+      const emitAs = i.emit_as ?? "plan";
+
+      const systemPrompt = buildSystemPrompt();
+      const userPrompt = buildUserPrompt(i);
+
+      try {
+        const res = await handle.callModel<z.infer<typeof PlanSchema>>({
+          model_id: i.model_id,
+          prompt: userPrompt,
+          system: systemPrompt,
+          schema: PlanSchema,
+        });
+        const plan = res.value;
+
+        // Defensive: reject plans whose steps reference manifests outside
+        // the allowed set. The kernel would refuse at spawn anyway, but
+        // we fail fast here so the planner sees feedback as a `Failed`
+        // that a repair_loop can digest.
+        const allowed = new Set(i.available_manifests.map((m) => m.id));
+        const illegal = plan.steps.filter((s) => !allowed.has(s.manifest_id));
+        if (illegal.length > 0) {
+          return {
+            kind: "failed",
+            reason: `planner chose manifests outside available_manifests: ${illegal.map((s) => s.manifest_id).join(", ")}`,
+            retryable: true,
+            evidence: { verdict: "fail" },
+          };
+        }
+
+        return {
+          kind: "output",
+          value: { plan, model: res.model, method: res.method },
+          ctx_patch: {
+            set: {
+              [emitAs]: asArtifact(plan, {
+                media_type: "application/json",
+                schema_ref: "@agenteer/default_planner.plan.v1",
+              }),
+            },
+          },
+          evidence: { verdict: "pass" },
+        };
+      } catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        return {
+          kind: "failed",
+          reason,
+          retryable: /timeout|rate.?limit|5\d\d|structured_output_exhausted/i.test(reason),
+          evidence: { verdict: "fail" },
+        };
+      }
+    },
+  };
+}
+
+export const defaultPlannerManifest = MANIFEST;
+
+function buildSystemPrompt(): string {
+  return [
+    "You are a software-engineering planner.",
+    "You produce a JSON plan whose steps can be executed by the given manifests.",
+    "Constraints:",
+    "- Every step.manifest_id MUST be drawn from the provided `available_manifests` list.",
+    "- Every step.id is unique within the plan.",
+    "- `depends_on` references earlier step ids only; no cycles.",
+    "- `input` must match what the named manifest expects.",
+    "- Keep plans minimal — no speculative steps.",
+  ].join("\n");
+}
+
+function buildUserPrompt(input: Input): string {
+  const catalog = input.available_manifests
+    .map((m) => `- ${m.id} (${m.name}): ${m.description}`)
+    .join("\n");
+  return [
+    `Goal: ${input.goal}`,
+    ``,
+    `Available manifests:`,
+    catalog,
+    ``,
+    `Return JSON matching: { goal, steps: [{ id, manifest_id, input, rationale?, depends_on[] }], notes? }`,
+  ].join("\n");
+}

package/src/primitives/file_read.ts

@@ -0,0 +1,82 @@
+/**
+ * `@agenteer/node-file-read` — permissioned filesystem read (sub-plan 03 §3).
+ *
+ * Deterministic. Declares `fs.read:*`; actual scope attenuation happens at
+ * spawn time. At dispatch the permission kernel synthesizes the concrete
+ * `fs.read:<path>` capability and checks against `granted`.
+ */
+
+import { z } from "zod";
+import {
+  makeManifest,
+  type Node,
+  type NodeInput,
+  type NodeManifest,
+  type NodeResult,
+  type NodeRuntimeHandle,
+} from "@agenteer/core";
+
+const MANIFEST: NodeManifest = makeManifest({
+  id: "@agenteer/node-file-read",
+  name: "file_read",
+  description: "Read a file from disk into a string. Capability-gated at dispatch.",
+  determinism: "deterministic",
+  // Static caps: none. Dynamic augmentation derives the concrete fs.read
+  // scope from input.path at spawn time (master plan §R4).
+  required_actions: [],
+  dynamic_actions: true,
+  dynamic_action_spec: "fs.read:${input.path}",
+  tags: ["primitive", "fs"],
+  side_effects: {
+    writes_fs: false,
+    network: false,
+    mutates_ctx: true,
+    emits_ctx_variants: ["artifact.file_read"],
+  },
+});
+
+const InputSchema = z.object({
+  path: z.string().min(1),
+  /** Optional ctx tag to emit the content under via ctx_patch.set. */
+  emit_as: z.string().optional(),
+});
+
+const OutputSchema = z.object({
+  path: z.string(),
+  content: z.string(),
+  bytes: z.number().int().nonnegative(),
+});
+
+type Input = z.infer<typeof InputSchema>;
+type Output = z.infer<typeof OutputSchema>;
+
+export function fileReadFactory(): Node<Input, Output> {
+  return {
+    manifest: MANIFEST,
+    inputSchema: InputSchema,
+    outputSchema: OutputSchema,
+    ctx: [],
+    model: null,
+    async execute(input: NodeInput<Input>, handle: NodeRuntimeHandle): Promise<NodeResult<Output>> {
+      const { path, emit_as } = input.original;
+      try {
+        const content = await handle.callAction<string>("fs.read", { path });
+        return {
+          kind: "output",
+          value: { path, content, bytes: Buffer.byteLength(content, "utf8") },
+          ...(emit_as ? { ctx_patch: { set: { [emit_as]: content } } } : {}),
+          evidence: { verdict: "pass" },
+        };
+      } catch (err) {
+        return {
+          kind: "failed",
+          reason: err instanceof Error ? err.message : String(err),
+          retryable: false,
+          evidence: { verdict: "fail" },
+        };
+      }
+    },
+  };
+}
+
+export const fileReadManifest = MANIFEST;

package/src/primitives/file_write.ts

@@ -0,0 +1,80 @@
+/**
+ * `@agenteer/node-file-write` — permissioned filesystem write (sub-plan 03 §4).
+ *
+ * Deterministic w.r.t. (path, content), though authors often want to
+ * mark it stochastic if the upstream producer was an LLM — the wrapper
+ * node is the right place for that. `fs.write:<path>` is checked at
+ * dispatch; the hard denylist applies unconditionally.
+ */
+
+import { z } from "zod";
+import {
+  makeManifest,
+  type Node,
+  type NodeInput,
+  type NodeManifest,
+  type NodeResult,
+  type NodeRuntimeHandle,
+} from "@agenteer/core";
+
+const MANIFEST: NodeManifest = makeManifest({
+  id: "@agenteer/node-file-write",
+  name: "file_write",
+  description: "Write a file to disk. Capability-gated; denylist enforced.",
+  determinism: "deterministic",
+  required_actions: [],
+  dynamic_actions: true,
+  dynamic_action_spec: "fs.write:${input.path}",
+  tags: ["primitive", "fs"],
+  side_effects: {
+    writes_fs: true,
+    network: false,
+    mutates_ctx: false,
+  },
+});
+
+const InputSchema = z.object({
+  path: z.string().min(1),
+  content: z.string(),
+});
+
+const OutputSchema = z.object({
+  path: z.string(),
+  bytes: z.number().int().nonnegative(),
+});
+
+type Input = z.infer<typeof InputSchema>;
+type Output = z.infer<typeof OutputSchema>;
+
+export function fileWriteFactory(): Node<Input, Output> {
+  return {
+    manifest: MANIFEST,
+    inputSchema: InputSchema,
+    outputSchema: OutputSchema,
+    ctx: [],
+    model: null,
+    async execute(input: NodeInput<Input>, handle: NodeRuntimeHandle): Promise<NodeResult<Output>> {
+      const { path, content } = input.original;
+      try {
+        const { bytes } = await handle.callAction<{ bytes: number }>("fs.write", {
+          path,
+          content,
+        });
+        return {
+          kind: "output",
+          value: { path, bytes },
+          evidence: { verdict: "pass" },
+        };
+      } catch (err) {
+        return {
+          kind: "failed",
+          reason: err instanceof Error ? err.message : String(err),
+          retryable: false,
+          evidence: { verdict: "fail" },
+        };
+      }
+    },
+  };
+}
+
+export const fileWriteManifest = MANIFEST;