@agenteer/stdlib 1.0.0-rc.1

package/src/primitives/llm_call.ts

@@ -0,0 +1,113 @@
+/**
+ * `@agenteer/node-llm-call` — typed prompt + typed output via a model (sub-plan 03 §1).
+ *
+ * M2 scope: the structured-output wrapper with native-first / text-parse
+ * fallback lives in `@agenteer/trust/structured` (M3). Here we:
+ *   - validate the input shape,
+ *   - call `handle.callModel` which the runtime routes through the
+ *     permission kernel + ModelProvider,
+ *   - emit an Artifact ctx item with the validated value.
+ *
+ * Response schema is carried on `input.schema` as a Zod type. For
+ * third-party wire delivery (JSON-only), the M6 registry serializes
+ * schemas; that path is still future work.
+ */
+
+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-llm-call",
+  name: "llm_call",
+  description: "Call a configured model with a structured schema; return the validated value.",
+  determinism: "stochastic",
+  required_actions: [],
+  dynamic_actions: true,
+  dynamic_action_spec: "model:${input.model_id}",
+  tags: ["primitive", "llm"],
+  side_effects: {
+    writes_fs: false,
+    network: true,
+    mutates_ctx: true,
+    emits_ctx_variants: ["artifact.llm_call"],
+  },
+});
+
+const InputSchema = z.object({
+  model_id: z.string().min(1),
+  prompt: z.string().min(1),
+  system: z.string().optional(),
+  temperature: z.number().min(0).max(2).optional(),
+  max_tokens: z.number().int().min(1).optional(),
+  /** Tag under which the validated value is appended to context. */
+  emit_as: z.string().optional(),
+});
+
+const OutputSchema = z.object({
+  value: z.unknown(),
+  model: z.string(),
+  tokens: z.object({ prompt: z.number().int(), completion: z.number().int() }),
+  method: z.enum(["native", "text_parse", "mock"]),
+});
+
+type Input = z.infer<typeof InputSchema>;
+type Output = z.infer<typeof OutputSchema>;
+
+/**
+ * Factory. Accepts an optional response schema — nodes authored on top of
+ * `llm_call` typically pass a concrete Zod here. When absent, the return
+ * value is passed through unchecked (the manifest's `output_schema` still
+ * enforces the outer wrapper shape).
+ */
+export function llmCallFactory(responseSchema?: z.ZodTypeAny): () => Node<Input, Output> {
+  return () => ({
+    manifest: MANIFEST,
+    inputSchema: InputSchema,
+    outputSchema: OutputSchema,
+    ctx: [],
+    model: null, // resolved dynamically via input.model_id
+    async execute(input: NodeInput<Input>, handle: NodeRuntimeHandle): Promise<NodeResult<Output>> {
+      const { model_id, prompt, system, temperature, max_tokens, emit_as } = input.original;
+      try {
+        const res = await handle.callModel({
+          model_id,
+          prompt,
+          ...(system !== undefined ? { system } : {}),
+          ...(temperature !== undefined ? { temperature } : {}),
+          ...(max_tokens !== undefined ? { max_tokens } : {}),
+          ...(responseSchema ? { schema: responseSchema } : {}),
+        });
+        const value: Output = {
+          value: res.value,
+          model: res.model,
+          tokens: res.tokens,
+          method: res.method,
+        };
+        return {
+          kind: "output",
+          value,
+          ...(emit_as ? { ctx_patch: { set: { [emit_as]: res.value } } } : {}),
+          evidence: { verdict: "pass" },
+        };
+      } catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        const retryable = /timeout|rate.?limit|5\d\d/i.test(reason);
+        return {
+          kind: "failed",
+          reason,
+          retryable,
+          evidence: { verdict: "fail" },
+        };
+      }
+    },
+  });
+}
+
+export const llmCallManifest = MANIFEST;

package/src/primitives/shell_exec.ts

@@ -0,0 +1,122 @@
+/**
+ * `@agenteer/node-shell-exec` — permissioned subprocess (sub-plan 03 §5).
+ *
+ * `shell.exec` is intentionally coarse (sub-plan 02 §1.1.4). Dispatch
+ * checks capability + denylist on cwd; the runtime's §R1 snapshot wrap
+ * catches writes that escape the declared `fs.write` scope. Streaming
+ * stdout/stderr uses the shared capture utility so `compile` / `test_run`
+ * behave identically.
+ */
+
+import { z } from "zod";
+import {
+  authorizeOperation,
+  assertNotDenied,
+  makeManifest,
+  type Node,
+  type NodeInput,
+  type NodeManifest,
+  type NodeResult,
+  type NodeRuntimeHandle,
+} from "@agenteer/core";
+import { runCommand, tailOf } from "../shared/index.js";
+
+const MANIFEST: NodeManifest = makeManifest({
+  id: "@agenteer/node-shell-exec",
+  name: "shell_exec",
+  description: "Execute a shell command. Captures stdout/stderr/exit_code. Coarse-grained.",
+  determinism: "stochastic",
+  required_actions: ["shell.exec:"],
+  tags: ["primitive", "shell"],
+});
+
+const InputSchema = z.object({
+  command: z.string().min(1),
+  cwd: z.string().optional(),
+  timeout_ms: z.number().int().min(1).max(600_000).default(120_000),
+  stdin: z.string().optional(),
+});
+
+const OutputSchema = z.object({
+  exit_code: z.number().int(),
+  stdout: z.string(),
+  stderr: z.string(),
+  duration_ms: z.number().int().nonnegative(),
+  timed_out: z.boolean(),
+});
+
+type Input = z.input<typeof InputSchema>;
+type Output = z.infer<typeof OutputSchema>;
+
+export function shellExecFactory(): Node<Input, Output> {
+  return {
+    manifest: MANIFEST,
+    inputSchema: InputSchema,
+    outputSchema: OutputSchema,
+    ctx: [],
+    model: null,
+    async execute(input: NodeInput<Input>, handle: NodeRuntimeHandle): Promise<NodeResult<Output>> {
+      const { command, cwd, stdin } = input.original;
+      const timeout_ms = input.original.timeout_ms ?? 120_000;
+
+      try {
+        authorizeOperation(handle.granted, { kind: "shell.exec" });
+      } catch (err) {
+        return {
+          kind: "failed",
+          reason: `permission_denied: ${err instanceof Error ? err.message : String(err)}`,
+          retryable: false,
+          evidence: { verdict: "fail" },
+        };
+      }
+      if (cwd) {
+        try {
+          assertNotDenied(cwd);
+        } catch (err) {
+          return {
+            kind: "failed",
+            reason: err instanceof Error ? err.message : String(err),
+            retryable: false,
+            evidence: { verdict: "fail" },
+          };
+        }
+      }
+
+      try {
+        const r = await runCommand(command, {
+          ...(cwd !== undefined ? { cwd } : {}),
+          ...(stdin !== undefined ? { stdin } : {}),
+          timeout_ms,
+          signal: handle.signal,
+        });
+        return {
+          kind: "output",
+          value: {
+            exit_code: r.exit_code,
+            stdout: r.stdout,
+            stderr: r.stderr,
+            duration_ms: r.duration_ms,
+            timed_out: r.timed_out,
+          },
+          evidence: {
+            verdict: r.exit_code === 0 && !r.timed_out ? "pass" : "fail",
+            tool_output: {
+              command,
+              exit_code: r.exit_code,
+              stdout_tail: tailOf(r.stdout),
+            },
+          },
+        };
+      } catch (err) {
+        return {
+          kind: "failed",
+          reason: err instanceof Error ? err.message : String(err),
+          retryable: true,
+          evidence: { verdict: "fail" },
+        };
+      }
+    },
+  };
+}
+
+export const shellExecManifest = MANIFEST;

package/src/primitives/tool_call.ts

@@ -0,0 +1,84 @@
+/**
+ * `@agenteer/node-tool-call` — primitive for invoking a registered tool
+ * (sub-plan 03 §2). §R4 honest dynamic-action disclosure:
+ *   dynamic_actions: true
+ *   dynamic_action_spec: "tool:${input.tool_name}"
+ *
+ * The permission kernel synthesizes `tool:<concrete_name>` at spawn time
+ * and checks against the parent's granted set. Tools themselves are
+ * adapters injected via `Runtime({ toolRegistry })`.
+ */
+
+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-tool-call",
+  name: "tool_call",
+  description:
+    "Invoke a registered tool by name. §R4-compliant: declared tool capability is synthesized from input at dispatch.",
+  determinism: "stochastic",
+  required_actions: [],
+  dynamic_actions: true,
+  dynamic_action_spec: "tool:${input.tool_name}",
+  tags: ["primitive"],
+  side_effects: {
+    writes_fs: false,
+    network: true,
+    mutates_ctx: false,
+  },
+});
+
+const InputSchema = z.object({
+  tool_name: z.string().min(1),
+  args: z.unknown(),
+});
+
+const OutputSchema = z.object({
+  tool_name: z.string(),
+  value: z.unknown(),
+});
+
+type Input = z.input<typeof InputSchema>;
+type Output = z.infer<typeof OutputSchema>;
+
+export function toolCallFactory(): Node<Input, Output> {
+  return {
+    manifest: MANIFEST,
+    inputSchema: InputSchema,
+    outputSchema: OutputSchema,
+    ctx: [],
+    model: null,
+    async execute(input: NodeInput<Input>, handle: NodeRuntimeHandle): Promise<NodeResult<Output>> {
+      const { tool_name, args } = input.original;
+      try {
+        const value = await handle.callAction<unknown>("tool.invoke", {
+          tool_name,
+          args,
+        });
+        return {
+          kind: "output",
+          value: { tool_name, value },
+          evidence: { verdict: "pass", tool_output: { command: `tool:${tool_name}` } },
+        };
+      } catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        return {
+          kind: "failed",
+          reason,
+          retryable: /rate.?limit|timeout|5\d\d/i.test(reason),
+          evidence: { verdict: "fail" },
+        };
+      }
+    },
+  };
+}
+
+export const toolCallManifest = MANIFEST;

package/src/shared/capture.ts

@@ -0,0 +1,155 @@
+/**
+ * Streaming stdout/stderr capture with ring-buffer truncation — sub-plan
+ * 03 §S.2. Shared by `shell_exec`, `compile`, `test_run`. One module,
+ * not three, so truncation + timeout + binary-detection behavior stays
+ * consistent across validators.
+ */
+
+import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
+
+export interface RunCommandOptions {
+  readonly cwd?: string;
+  readonly timeout_ms: number;
+  readonly stdin?: string;
+  readonly signal: AbortSignal;
+  readonly env?: NodeJS.ProcessEnv;
+  /** Per-stream ring buffer cap (default 256 KiB). */
+  readonly capture_limit?: number;
+  /** SIGTERM → SIGKILL grace (default 5s). */
+  readonly kill_grace_ms?: number;
+  readonly onStdoutLine?: (line: string) => void;
+  readonly onStderrLine?: (line: string) => void;
+}
+
+export interface RunCommandResult {
+  exit_code: number;
+  stdout: string;
+  stderr: string;
+  duration_ms: number;
+  timed_out: boolean;
+  truncated: { stdout: boolean; stderr: boolean };
+}
+
+const DEFAULT_CAPTURE_LIMIT = 256 * 1024;
+const DEFAULT_KILL_GRACE_MS = 5_000;
+
+export async function runCommand(
+  command: string,
+  opts: RunCommandOptions,
+): Promise<RunCommandResult> {
+  const startedAt = Date.now();
+  return await new Promise<RunCommandResult>((resolve, reject) => {
+    const child: ChildProcessWithoutNullStreams = spawn(command, {
+      shell: true,
+      ...(opts.cwd !== undefined ? { cwd: opts.cwd } : {}),
+      ...(opts.env ? { env: opts.env } : {}),
+    }) as ChildProcessWithoutNullStreams;
+
+    const limit = opts.capture_limit ?? DEFAULT_CAPTURE_LIMIT;
+    let stdout = "";
+    let stderr = "";
+    let stdoutTruncated = false;
+    let stderrTruncated = false;
+    let timedOut = false;
+    let settled = false;
+    let stdoutTail = "";
+    let stderrTail = "";
+
+    const feed = (
+      chunk: Buffer | string,
+      which: "stdout" | "stderr",
+    ): void => {
+      const s = chunk.toString();
+      const appendTo = (buf: string, truncated: boolean): [string, boolean] => {
+        if (truncated) return [buf, true];
+        if (buf.length + s.length > limit) {
+          const room = Math.max(0, limit - buf.length);
+          return [buf + s.slice(0, room), true];
+        }
+        return [buf + s, false];
+      };
+      if (which === "stdout") {
+        [stdout, stdoutTruncated] = appendTo(stdout, stdoutTruncated);
+        if (opts.onStdoutLine) {
+          stdoutTail += s;
+          const idx = stdoutTail.lastIndexOf("\n");
+          if (idx >= 0) {
+            for (const line of stdoutTail.slice(0, idx).split("\n")) {
+              if (line.length) opts.onStdoutLine(line);
+            }
+            stdoutTail = stdoutTail.slice(idx + 1);
+          }
+        }
+      } else {
+        [stderr, stderrTruncated] = appendTo(stderr, stderrTruncated);
+        if (opts.onStderrLine) {
+          stderrTail += s;
+          const idx = stderrTail.lastIndexOf("\n");
+          if (idx >= 0) {
+            for (const line of stderrTail.slice(0, idx).split("\n")) {
+              if (line.length) opts.onStderrLine(line);
+            }
+            stderrTail = stderrTail.slice(idx + 1);
+          }
+        }
+      }
+    };
+
+    child.stdout.on("data", (c) => feed(c, "stdout"));
+    child.stderr.on("data", (c) => feed(c, "stderr"));
+
+    const grace = opts.kill_grace_ms ?? DEFAULT_KILL_GRACE_MS;
+    const timeoutTimer = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGTERM");
+      const hard = setTimeout(() => child.kill("SIGKILL"), grace);
+      hard.unref();
+    }, opts.timeout_ms);
+
+    const onAbort = (): void => {
+      child.kill("SIGTERM");
+    };
+    opts.signal.addEventListener("abort", onAbort, { once: true });
+
+    child.on("error", (err) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeoutTimer);
+      opts.signal.removeEventListener("abort", onAbort);
+      reject(err);
+    });
+
+    child.on("close", (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeoutTimer);
+      opts.signal.removeEventListener("abort", onAbort);
+      // Flush any remaining partial lines.
+      if (stdoutTail.length && opts.onStdoutLine) opts.onStdoutLine(stdoutTail);
+      if (stderrTail.length && opts.onStderrLine) opts.onStderrLine(stderrTail);
+      resolve({
+        exit_code: code ?? -1,
+        stdout: stdoutTruncated
+          ? `${stdout}\n[...stdout truncated at ${limit} bytes...]`
+          : stdout,
+        stderr: stderrTruncated
+          ? `${stderr}\n[...stderr truncated at ${limit} bytes...]`
+          : stderr,
+        duration_ms: Date.now() - startedAt,
+        timed_out: timedOut,
+        truncated: { stdout: stdoutTruncated, stderr: stderrTruncated },
+      });
+    });
+
+    if (opts.stdin !== undefined) {
+      child.stdin.write(opts.stdin);
+    }
+    child.stdin.end();
+  });
+}
+
+/** Convenience: tail of a stream for evidence `stdout_tail` / summary. */
+export function tailOf(text: string, maxChars = 4096): string {
+  if (text.length <= maxChars) return text;
+  return `[...]${text.slice(-maxChars)}`;
+}

package/src/shared/ctx.ts

@@ -0,0 +1,45 @@
+/**
+ * ctx_patch builders for stdlib authors (sub-plan 03 §S.4).
+ *
+ * Keeps stdlib code terse: `mergeSetArtifacts({ "plan.head": plan })`
+ * instead of spelling out the `asArtifact` wrapper per entry.
+ */
+
+import { asArtifact, type CtxArtifactMarker, type CtxPatch } from "@agenteer/core";
+
+export function setArtifacts(
+  entries: Record<string, { body: unknown; media_type?: string; schema_ref?: string }>,
+): Pick<CtxPatch, "set"> {
+  const set: Record<string, CtxArtifactMarker> = {};
+  for (const [key, spec] of Object.entries(entries)) {
+    set[key] = asArtifact(spec.body, {
+      ...(spec.media_type !== undefined ? { media_type: spec.media_type } : {}),
+      ...(spec.schema_ref !== undefined ? { schema_ref: spec.schema_ref } : {}),
+    });
+  }
+  return { set };
+}
+
+export function mergePatches(...patches: (CtxPatch | undefined)[]): CtxPatch | undefined {
+  const set: Record<string, unknown> = {};
+  const del: string[] = [];
+  const append: Record<string, unknown[]> = {};
+  let any = false;
+  for (const p of patches) {
+    if (!p) continue;
+    any = true;
+    if (p.set) Object.assign(set, p.set);
+    if (p.delete) del.push(...p.delete);
+    if (p.append) {
+      for (const [k, vs] of Object.entries(p.append)) {
+        append[k] = [...(append[k] ?? []), ...vs];
+      }
+    }
+  }
+  if (!any) return undefined;
+  const out: CtxPatch = {};
+  if (Object.keys(set).length) out.set = set;
+  if (del.length) out.delete = del;
+  if (Object.keys(append).length) out.append = append;
+  return out;
+}

package/src/shared/index.ts

@@ -0,0 +1,17 @@
+export {
+  runCommand,
+  tailOf,
+  type RunCommandOptions,
+  type RunCommandResult,
+} from "./capture.js";
+
+export {
+  ValidatorIssueSchema,
+  ValidatorOutputSchema,
+  type ValidatorIssue,
+  type ValidatorOutput,
+  passOutput,
+  failOutput,
+} from "./validator.js";
+
+export { setArtifacts, mergePatches } from "./ctx.js";

package/src/shared/validator.ts

@@ -0,0 +1,51 @@
+/**
+ * Validator shape (sub-plan 03 §Part B; master plan ratified resolution).
+ *
+ * Validators emit `verdict: "fail"` as DATA on `Output`, not via `Failed`.
+ * `Failed` is reserved for "couldn't run at all" (binary missing,
+ * unreadable input, capability denied). This helper normalizes the
+ * output shape so downstream meta-nodes (repair_loop, judge) can switch
+ * on a single field.
+ */
+
+import { z } from "zod";
+
+export const ValidatorIssueSchema = z.object({
+  path: z.string().optional(),
+  message: z.string(),
+  code: z.string().optional(),
+  severity: z.enum(["error", "warning"]).default("error"),
+});
+export type ValidatorIssue = z.infer<typeof ValidatorIssueSchema>;
+
+export const ValidatorOutputSchema = z.object({
+  verdict: z.enum(["pass", "fail"]),
+  issues: z.array(ValidatorIssueSchema),
+  /** Short human-readable summary for logs / evidence. */
+  summary: z.string(),
+  /** Tool-level exit code if applicable; 0 for pass, non-zero for fail. */
+  exit_code: z.number().int().optional(),
+  /** Tail of raw tool output, bounded. */
+  stdout_tail: z.string().optional(),
+  stderr_tail: z.string().optional(),
+});
+export type ValidatorOutput = z.infer<typeof ValidatorOutputSchema>;
+
+export function passOutput(summary: string): ValidatorOutput {
+  return { verdict: "pass", issues: [], summary, exit_code: 0 };
+}
+
+export function failOutput(
+  issues: ValidatorIssue[],
+  summary: string,
+  extra?: { exit_code?: number; stdout_tail?: string; stderr_tail?: string },
+): ValidatorOutput {
+  return {
+    verdict: "fail",
+    issues,
+    summary,
+    ...(extra?.exit_code !== undefined ? { exit_code: extra.exit_code } : {}),
+    ...(extra?.stdout_tail ? { stdout_tail: extra.stdout_tail } : {}),
+    ...(extra?.stderr_tail ? { stderr_tail: extra.stderr_tail } : {}),
+  };
+}