@agenteer/stdlib 1.0.0-rc.1

package/dist/validators/typecheck.js

@@ -0,0 +1,89 @@
+/**
+ * `@agenteer/node-typecheck` — thin wrapper over `compile` with
+ * types-only flags (sub-plan 03 §10).
+ *
+ * v1 supports TypeScript (`tsc --noEmit --strict`). The wrapper exists
+ * separately from `compile` so planners can distinguish "types only"
+ * from "full build"; the underlying adapter is shared.
+ */
+import { z } from "zod";
+import { makeManifest, authorizeOperation, } from "@agenteer/core";
+import { failOutput, passOutput, runCommand, tailOf, ValidatorOutputSchema, } from "../shared/index.js";
+const MANIFEST = makeManifest({
+    id: "@agenteer/node-typecheck",
+    name: "typecheck",
+    description: "Types-only check (v1: TypeScript tsc --noEmit --strict).",
+    determinism: "deterministic",
+    required_actions: ["shell.exec:"],
+    dynamic_actions: true,
+    dynamic_action_spec: "fs.read:${input.cwd}",
+    tags: ["validator"],
+});
+const InputSchema = z.object({
+    language: z.enum(["typescript"]),
+    cwd: z.string().min(1),
+    tsconfig: z.string().optional(),
+    strict: z.boolean().default(true),
+    timeout_ms: z.number().int().min(1).max(600_000).default(300_000),
+});
+const TSC_ISSUE_RE = /^(.+?)\((\d+),(\d+)\):\s+(error|warning)\s+TS\d+:\s+(.*)$/gm;
+export function typecheckFactory() {
+    return {
+        manifest: MANIFEST,
+        inputSchema: InputSchema,
+        outputSchema: ValidatorOutputSchema,
+        ctx: [],
+        model: null,
+        async execute(input, handle) {
+            const { cwd, tsconfig } = input.original;
+            const strict = input.original.strict ?? true;
+            const timeout_ms = input.original.timeout_ms ?? 300_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" },
+                };
+            }
+            const tsconfigArg = tsconfig ? `--project ${JSON.stringify(tsconfig)}` : "";
+            const strictFlag = strict ? "--strict" : "";
+            const command = `npx -y tsc --noEmit ${tsconfigArg} ${strictFlag}`.replace(/\s+/g, " ").trim();
+            try {
+                const r = await runCommand(command, { cwd, timeout_ms, signal: handle.signal });
+                const combined = `${r.stdout}\n${r.stderr}`;
+                const issues = [];
+                for (const m of combined.matchAll(TSC_ISSUE_RE)) {
+                    issues.push({
+                        path: `${m[1]}:${m[2]}:${m[3]}`,
+                        message: m[5].trim(),
+                        code: "TS",
+                        severity: m[4] === "warning" ? "warning" : "error",
+                    });
+                }
+                const verdict = r.exit_code === 0 && issues.length === 0 ? "pass" : "fail";
+                const out = verdict === "pass"
+                    ? { ...passOutput(`typecheck clean (${r.duration_ms}ms)`), exit_code: r.exit_code }
+                    : failOutput(issues.length ? issues : [{ message: `tsc exited ${r.exit_code}`, severity: "error" }], `typecheck: ${issues.length} issue(s)`, {
+                        exit_code: r.exit_code,
+                        stdout_tail: tailOf(r.stdout),
+                        stderr_tail: tailOf(r.stderr),
+                    });
+                return { kind: "output", value: out, evidence: { verdict } };
+            }
+            catch (err) {
+                return {
+                    kind: "failed",
+                    reason: err instanceof Error ? err.message : String(err),
+                    retryable: true,
+                    evidence: { verdict: "fail" },
+                };
+            }
+        },
+    };
+}
+export const typecheckManifest = MANIFEST;
+//# sourceMappingURL=typecheck.js.map

package/dist/validators/typecheck.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"typecheck.js","sourceRoot":"","sources":["../../src/validators/typecheck.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@agenteer/stdlib",
+  "version": "1.0.0-rc.1",
+  "description": "Agenteer standard library — 19 hardened, publishable nodes (primitives, validators, meta, humans, planner, context).",
+  "keywords": [
+    "agenteer",
+    "agent",
+    "stdlib",
+    "nodes",
+    "primitives",
+    "validators",
+    "planner",
+    "llm",
+    "tools"
+  ],
+  "author": "salehsquared (https://github.com/salehsquared)",
+  "license": "MIT",
+  "homepage": "https://github.com/salehsquared/agenteer#readme",
+  "bugs": {
+    "url": "https://github.com/salehsquared/agenteer/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/salehsquared/agenteer.git",
+    "directory": "packages/stdlib"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@agenteer/core": "1.0.0-rc.1",
+    "@agenteer/trust": "1.0.0-rc.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "vitest": "^3.2.4"
+  }
+}

package/src/context/context_curator.ts

@@ -0,0 +1,154 @@
+/**
+ * `@agenteer/node-context-curator` — the 18th v1 node (master plan open
+ * #15 — **shipped in v1**). Sub-plan 01 §7.
+ *
+ * v1 scope: **query curator** only (sub-plan 01 §7.3 mode A). Given a
+ * task description and a target manifest, emit a deterministic
+ * `SliceSpec` that downstream nodes / planners can consume. Condensing
+ * and pedagogical modes are v2.
+ *
+ * Emits a `Decision` item recording the curation choice so a later
+ * `judge_with_stripped_ctx` can detect motivated reasoning.
+ */
+
+import { z } from "zod";
+import {
+  asArtifact,
+  makeManifest,
+  type Node,
+  type NodeInput,
+  type NodeManifest,
+  type NodeResult,
+} from "@agenteer/core";
+
+const MANIFEST: NodeManifest = makeManifest({
+  id: "@agenteer/node-context-curator",
+  name: "context_curator",
+  description:
+    "Emit a deterministic SliceSpec for a downstream node based on task description and target manifest.",
+  determinism: "deterministic",
+  required_actions: [],
+  tags: ["meta", "curator"],
+  side_effects: {
+    writes_fs: false,
+    network: false,
+    mutates_ctx: true,
+    emits_ctx_variants: ["decision.curation", "artifact.slice_spec"],
+  },
+});
+
+const ContextItemTypeSchema = z.enum([
+  "artifact",
+  "observation",
+  "decision",
+  "evidence_ref",
+  "claim",
+  "reference",
+]);
+
+const SelectorSchema = z.object({
+  ids: z.array(z.string()).optional(),
+  types: z.array(ContextItemTypeSchema).optional(),
+  tags: z
+    .object({
+      any: z.array(z.string()).optional(),
+      all: z.array(z.string()).optional(),
+      none: z.array(z.string()).optional(),
+    })
+    .optional(),
+  limit: z.number().int().positive().optional(),
+  order: z.enum(["oldest", "newest"]).optional(),
+});
+
+type Selector = z.infer<typeof SelectorSchema>;
+
+const InputSchema = z.object({
+  task: z.string().min(1),
+  target_manifest_id: z.string().min(1),
+  /** Optional hints; the curator treats these as selector constraints. */
+  hints: z
+    .object({
+      include_tags: z.array(z.string()).optional(),
+      exclude_tags: z.array(z.string()).optional(),
+      types: z.array(ContextItemTypeSchema).optional(),
+      limit: z.number().int().positive().optional(),
+    })
+    .optional(),
+  /** Name under which the slice spec is emitted to ctx. */
+  emit_as: z.string().default("slice_spec"),
+});
+
+const SliceSpecSchema = z.object({
+  name: z.string(),
+  selector: SelectorSchema,
+  stale_policy: z.enum(["reject", "recompute", "warn", "allow"]),
+  freeze: z.enum(["snapshot", "live"]),
+  budget: z
+    .object({
+      max_items: z.number().int().positive().optional(),
+      max_bytes: z.number().int().positive().optional(),
+    })
+    .optional(),
+});
+
+const OutputSchema = z.object({
+  slice_spec: SliceSpecSchema,
+  rationale: z.string(),
+});
+
+type Input = z.input<typeof InputSchema>;
+type Output = z.infer<typeof OutputSchema>;
+
+export function contextCuratorFactory(): 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 hints = i.hints ?? {};
+      const emitAs = i.emit_as ?? "slice_spec";
+
+      const selector: Selector = { order: "newest" };
+      if (hints.types && hints.types.length) selector.types = hints.types;
+      if (hints.include_tags?.length || hints.exclude_tags?.length) {
+        const tags: NonNullable<Selector["tags"]> = {};
+        if (hints.include_tags?.length) tags.any = hints.include_tags;
+        if (hints.exclude_tags?.length) tags.none = hints.exclude_tags;
+        selector.tags = tags;
+      }
+      if (hints.limit !== undefined) selector.limit = hints.limit;
+
+      const spec = {
+        name: `curated.${i.target_manifest_id.replace(/[^a-z0-9]+/gi, "_")}`,
+        selector,
+        stale_policy: "warn" as const,
+        freeze: "snapshot" as const,
+        ...(hints.limit !== undefined ? { budget: { max_items: hints.limit } } : {}),
+      };
+
+      const rationale =
+        `Curated a ${spec.freeze} slice for ${i.target_manifest_id} targeting "${i.task.slice(0, 80)}"` +
+        (hints.include_tags ? `; include_tags=[${hints.include_tags.join(",")}]` : "") +
+        (hints.exclude_tags ? `; exclude_tags=[${hints.exclude_tags.join(",")}]` : "") +
+        (hints.types ? `; types=[${hints.types.join(",")}]` : "");
+
+      return {
+        kind: "output",
+        value: { slice_spec: spec, rationale },
+        ctx_patch: {
+          // Decision item recording the curation choice — judge-friendly.
+          set: {
+            [`curator.choice.${spec.name}`]: rationale,
+            [emitAs]: asArtifact(spec, { media_type: "application/json" }),
+          },
+        },
+        evidence: { verdict: "pass" },
+      };
+    },
+  };
+}
+
+export const contextCuratorManifest = MANIFEST;

package/src/humans/approval_gate.ts

@@ -0,0 +1,101 @@
+/**
+ * `@agenteer/node-approval-gate` — human yes/no gate (sub-plan 03 §16).
+ *
+ * M4 scope (Q3-C decision): ship this, defer `ask_user` to M5 where the
+ * CLI can prompt a real user. The approval_gate is deterministic given
+ * its recorded decision, so tests can inject an `ApprovalResolver` that
+ * returns a canned answer. Session resume wires a real CLI prompt in M5.
+ *
+ * When the resolver is absent, the node returns `NeedsUser` with a
+ * prompt — that's the production-pause-for-CLI path.
+ */
+
+import { z } from "zod";
+import {
+  makeManifest,
+  type Node,
+  type NodeInput,
+  type NodeManifest,
+  type NodeResult,
+} from "@agenteer/core";
+
+const MANIFEST: NodeManifest = makeManifest({
+  id: "@agenteer/node-approval-gate",
+  name: "approval_gate",
+  description:
+    "Yes/no gate. When an ApprovalResolver is injected, resolves synchronously (tests + replay); otherwise returns NeedsUser.",
+  determinism: "deterministic",
+  tags: ["human"],
+});
+
+const InputSchema = z.object({
+  prompt: z.string().min(1),
+  /**
+   * Deterministic marker — when `decision` is present, the gate echoes
+   * it immediately without asking. Enables replay of a recorded session.
+   */
+  decision: z.enum(["approve", "deny"]).optional(),
+  /** Opaque id the resolver / CLI uses to look up the canned answer. */
+  decision_id: z.string().optional(),
+});
+
+const OutputSchema = z.object({
+  decision: z.enum(["approve", "deny"]),
+  /** Echo of the prompt for audit. */
+  prompt: z.string(),
+  source: z.enum(["recorded", "resolver", "user"]),
+});
+
+type Input = z.input<typeof InputSchema>;
+type Output = z.infer<typeof OutputSchema>;
+
+export interface ApprovalResolver {
+  /** Return `null` to fall through to `NeedsUser`. */
+  resolve(opts: { prompt: string; decision_id?: string }): "approve" | "deny" | null;
+}
+
+export function approvalGateFactory(
+  resolver?: ApprovalResolver,
+): () => 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;
+
+      if (i.decision !== undefined) {
+        return {
+          kind: "output",
+          value: { decision: i.decision, prompt: i.prompt, source: "recorded" },
+          evidence: { verdict: i.decision === "approve" ? "pass" : "fail" },
+        };
+      }
+
+      if (resolver) {
+        const ans = resolver.resolve({
+          prompt: i.prompt,
+          ...(i.decision_id !== undefined ? { decision_id: i.decision_id } : {}),
+        });
+        if (ans !== null) {
+          return {
+            kind: "output",
+            value: { decision: ans, prompt: i.prompt, source: "resolver" },
+            evidence: { verdict: ans === "approve" ? "pass" : "fail" },
+          };
+        }
+      }
+
+      return {
+        kind: "needs_user",
+        prompt: i.prompt,
+        schema: OutputSchema,
+        resume_hint: i.decision_id ?? "approval_gate",
+      };
+    },
+  });
+}
+
+export const approvalGateManifest = MANIFEST;

package/src/humans/ask_user.ts

@@ -0,0 +1,137 @@
+/**
+ * `@agenteer/node-ask-user` — freeform user prompt (sub-plan 03 §16, M5).
+ *
+ * M5 scope (Q3-C follow-through from M4): now that session resume + CLI
+ * ship together, we can pair `approval_gate`'s yes/no with `ask_user`'s
+ * freeform answer. Both share the same resolver model — a pre-recorded
+ * answer wins, else a resolver answers synchronously, else `NeedsUser`.
+ *
+ * The schema for the answer is caller-provided. Tests and production can
+ * validate the string with a Zod schema passed at factory time.
+ */
+
+import { z, type ZodType } from "zod";
+import {
+  makeManifest,
+  type Node,
+  type NodeInput,
+  type NodeManifest,
+  type NodeResult,
+} from "@agenteer/core";
+
+const MANIFEST: NodeManifest = makeManifest({
+  id: "@agenteer/node-ask-user",
+  name: "ask_user",
+  description:
+    "Freeform user prompt. Recorded answer → resolver → NeedsUser fallback. Schema validates answers.",
+  determinism: "deterministic",
+  tags: ["human"],
+});
+
+const InputSchema = z.object({
+  prompt: z.string().min(1),
+  /** Deterministic marker — echo back the recorded answer without asking. */
+  answer: z.unknown().optional(),
+  /**
+   * Opaque identifier used to match a resolver / CLI answer. If absent,
+   * the NodeResult's resume_hint defaults to `ask_user:<prompt-slug>`.
+   */
+  question_id: z.string().optional(),
+});
+
+type Input = z.input<typeof InputSchema>;
+
+export interface AskUserResolver {
+  /**
+   * Return the recorded answer for this prompt, or `null` to fall
+   * through to NeedsUser. Implementations typically bind to a session
+   * state; see `recordedAnswerResolver` from `@agenteer/core/session`.
+   */
+  resolve(opts: { prompt: string; question_id?: string }): unknown | null;
+}
+
+export interface AskUserFactoryOptions<T = string> {
+  resolver?: AskUserResolver;
+  /** Zod schema to validate any resolved/recorded answer. Defaults to string. */
+  answerSchema?: ZodType<T>;
+}
+
+export function askUserFactory<T = string>(
+  options: AskUserFactoryOptions<T> = {},
+): () => Node<Input, { answer: T; prompt: string; source: "recorded" | "resolver" | "user" }> {
+  const answerSchema = (options.answerSchema ?? z.string()) as ZodType<T>;
+  const OutputSchema = z.object({
+    answer: answerSchema,
+    prompt: z.string(),
+    source: z.enum(["recorded", "resolver", "user"]),
+  });
+  type Output = { answer: T; prompt: string; source: "recorded" | "resolver" | "user" };
+
+  return () => ({
+    manifest: MANIFEST,
+    inputSchema: InputSchema,
+    outputSchema: OutputSchema,
+    ctx: [],
+    model: null,
+    async execute(input: NodeInput<Input>): Promise<NodeResult<Output>> {
+      const i = input.original;
+      const resumeHint = i.question_id ?? slugHint(i.prompt);
+
+      if (i.answer !== undefined) {
+        const parsed = answerSchema.safeParse(i.answer);
+        if (!parsed.success) {
+          return {
+            kind: "failed",
+            reason: `recorded_answer_schema_violation: ${parsed.error.message}`,
+            retryable: false,
+          };
+        }
+        return {
+          kind: "output",
+          value: { answer: parsed.data, prompt: i.prompt, source: "recorded" },
+          evidence: { verdict: "pass" },
+        };
+      }
+
+      if (options.resolver) {
+        const raw = options.resolver.resolve({
+          prompt: i.prompt,
+          ...(i.question_id !== undefined ? { question_id: i.question_id } : {}),
+        });
+        if (raw !== null && raw !== undefined) {
+          const parsed = answerSchema.safeParse(raw);
+          if (!parsed.success) {
+            return {
+              kind: "failed",
+              reason: `resolver_answer_schema_violation: ${parsed.error.message}`,
+              retryable: false,
+            };
+          }
+          return {
+            kind: "output",
+            value: { answer: parsed.data, prompt: i.prompt, source: "resolver" },
+            evidence: { verdict: "pass" },
+          };
+        }
+      }
+
+      return {
+        kind: "needs_user",
+        prompt: i.prompt,
+        schema: answerSchema,
+        resume_hint: resumeHint,
+      };
+    },
+  });
+}
+
+export const askUserManifest = MANIFEST;
+
+function slugHint(prompt: string): string {
+  const slug = prompt
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "_")
+    .replace(/^_|_$/g, "")
+    .slice(0, 40);
+  return `ask_user:${slug || "prompt"}`;
+}