@plasm_lang/vercel-agent 0.3.63

package/src/stubs/plasm-value-emitter.ts

@@ -0,0 +1,162 @@
+import type { CapabilityIntrospectionJson } from "./catalog-introspection.js";
+import type { CapabilityBinding } from "./stub-symbols.js";
+import type { CapabilityInvokeShape } from "./capability-invoke-shape.js";
+import { invokeBodyFields, searchFieldName } from "./capability-invoke-shape.js";
+
+export interface EmissionField {
+  name: string;
+  required: boolean;
+  access: string;
+  kind: "literal" | "number" | "boolean" | "select";
+}
+
+export function emissionKindForField(
+  field: import("./catalog-introspection.js").InputFieldSchemaJson,
+  values: Record<string, import("./catalog-introspection.js").NamedValueSchemaJson>,
+): EmissionField["kind"] {
+  const nv = field.value_ref ? values[field.value_ref] : undefined;
+  const ft = nv?.field_type;
+  if (typeof ft === "string") {
+    if (ft === "integer" || ft === "number") return "number";
+    if (ft === "boolean") return "boolean";
+    if (ft === "select") return "select";
+  }
+  if (field.input_type?.type === "value") {
+    const inner = field.input_type.field_type;
+    if (inner === "integer" || inner === "number") return "number";
+    if (inner === "boolean") return "boolean";
+  }
+  return "literal";
+}
+
+export function buildEmissionFields(
+  cap: CapabilityIntrospectionJson,
+  catalogValues: Record<string, import("./catalog-introspection.js").NamedValueSchemaJson>,
+  shape: CapabilityInvokeShape,
+  entityIdField: string,
+  inputVar: string,
+): EmissionField[] {
+  const body = invokeBodyFields(cap, shape, entityIdField);
+  return body.map((f) => ({
+    name: f.name,
+    required: !!f.required,
+    access: `${inputVar}.${f.name}`,
+    kind: emissionKindForField(f, catalogValues),
+  }));
+}
+
+export interface DottedArgCodegen {
+  key: string;
+  valueExpr: string;
+  kind: "literal" | "number" | "boolean" | "select";
+  optional: boolean;
+}
+
+export function dottedArgsCodegen(
+  cap: CapabilityIntrospectionJson,
+  catalogValues: Record<string, import("./catalog-introspection.js").NamedValueSchemaJson>,
+  shape: CapabilityInvokeShape,
+  entityIdField: string,
+  inputVar: string,
+): DottedArgCodegen[] {
+  return buildEmissionFields(cap, catalogValues, shape, entityIdField, inputVar).map((f) => ({
+    key: f.name,
+    valueExpr: f.access,
+    kind: f.kind,
+    optional: !f.required,
+  }));
+}
+
+function renderBuildDottedArgsCall(args: DottedArgCodegen[]): string {
+  if (!args.length) return '""';
+  const entries = args
+    .map(
+      (a) =>
+        `{ key: ${JSON.stringify(a.key)}, value: ${a.valueExpr}, kind: ${JSON.stringify(a.kind)}${a.optional ? ", optional: true" : ""} }`,
+    )
+    .join(", ");
+  return `buildDottedArgs([${entries}])`;
+}
+
+/** Generated TypeScript statements that set `program` (uses `buildDottedArgs`, `plasmLiteral`, …). */
+export function renderProgramStatements(
+  binding: CapabilityBinding,
+  cap: CapabilityIntrospectionJson,
+  catalogValues: Record<string, import("./catalog-introspection.js").NamedValueSchemaJson>,
+  shape: CapabilityInvokeShape,
+  entityIdField: string,
+  inputVar: string,
+): string {
+  const sym = binding.entitySymbol;
+  const dotted = renderBuildDottedArgsCall(
+    dottedArgsCodegen(cap, catalogValues, shape, entityIdField, inputVar),
+  );
+
+  switch (shape) {
+    case "RootQuery":
+      return `const program = ${JSON.stringify(sym)};`;
+    case "ScopedQuery": {
+      const args = dottedArgsCodegen(cap, catalogValues, shape, entityIdField, inputVar);
+      const dottedCall = renderBuildDottedArgsCall(args);
+      return `const preds = ${dottedCall};
+  const program = preds ? \`${sym}{\${preds}}\` : ${JSON.stringify(sym)};`;
+    }
+    case "GetById":
+      return `const program = \`${sym}(\${plasmLiteral(${inputVar}.${entityIdField})})\`;`;
+    case "SearchText": {
+      const q = searchFieldName(cap) ?? "q";
+      return `const program = \`${sym}~\${plasmLiteral(${inputVar}.${q})}\`;`;
+    }
+    case "SearchFiltered": {
+      const q = searchFieldName(cap) ?? "q";
+      const args = dottedArgsCodegen(cap, catalogValues, shape, entityIdField, inputVar);
+      const dottedCall = renderBuildDottedArgsCall(args);
+      return `const filterArgs = ${dottedCall};
+  const program = filterArgs
+    ? \`${sym}~\${plasmLiteral(${inputVar}.${q})}{\${filterArgs}}\`
+    : \`${sym}~\${plasmLiteral(${inputVar}.${q})}\`;`;
+    }
+    case "RootCreate":
+      return `const args = ${dotted};
+  const program = \`${sym}.create(\${args})\`;`;
+    case "ScopedUpdate":
+      return `const args = ${dotted};
+  const program = \`${sym}(\${plasmLiteral(${inputVar}.${entityIdField})}).update(\${args})\`;`;
+    case "ScopedAction": {
+      const wire = binding.methodWire;
+      const method = binding.methodSymbol ? `.${binding.methodSymbol}` : `.${wire}`;
+      return `const program = \`${sym}(\${plasmLiteral(${inputVar}.${entityIdField})})${method}()\`;`;
+    }
+    case "ScopedDelete":
+      return `const program = \`${sym}(\${plasmLiteral(${inputVar}.${entityIdField})}).delete()\`;`;
+    case "MethodUnion": {
+      const m = binding.methodSymbol ?? "m1";
+      return `const program = \`${sym}.${m}(\${plasmLiteral("v1")})\`;`;
+    }
+    case "MethodObject": {
+      const m = binding.methodSymbol ?? binding.methodWire;
+      return `const args = ${dotted};
+  const program = \`${sym}.${m}(\${args})\`;`;
+    }
+    default:
+      return `const program = ${JSON.stringify(sym)};`;
+  }
+}
+
+/** @deprecated Prefer {@link renderProgramStatements} — avoids nested-template syntax errors. */
+export function renderProgramExpr(
+  binding: CapabilityBinding,
+  cap: CapabilityIntrospectionJson,
+  catalogValues: Record<string, import("./catalog-introspection.js").NamedValueSchemaJson>,
+  shape: CapabilityInvokeShape,
+  entityIdField: string,
+  inputVar: string,
+): string {
+  void binding;
+  void cap;
+  void catalogValues;
+  void shape;
+  void entityIdField;
+  void inputVar;
+  return '""';
+}

package/src/stubs/program-builder.ts

@@ -0,0 +1,82 @@
+import {
+  createEngine,
+  type DryRunResult,
+  type HostTransportFn,
+  type PlasmEngine,
+} from "../engine/napi-binding.js";
+import { createDefaultHostTransport } from "../engine/host-transport.js";
+
+export interface ProgramBuilderOptions {
+  entryId: string;
+  cgsHash: string;
+  engine?: PlasmEngine;
+  logicalSessionRef?: string;
+  agentSessionId?: string;
+  catalogRoot?: string;
+  /** Entity names to expose before dry-run / live execute. */
+  stubEntities?: string[];
+}
+
+export interface ProgramBuilderProvenance {
+  entryId: string;
+  catalogCgsHash: string;
+  logicalSessionRef?: string;
+  agentSessionId?: string;
+}
+
+export interface ProgramBuilder extends ProgramBuilderProvenance {
+  readonly catalogRoot?: string;
+  readonly stubEntities?: string[];
+  readonly engine?: PlasmEngine;
+  readonly programSource: string;
+  program(source: string): ProgramBuilder;
+  dryRun(): Promise<DryRunResult>;
+  run(planCommitRef: string, transport?: HostTransportFn): Promise<unknown>;
+}
+
+function cloneBuilder(
+  opts: ProgramBuilderOptions,
+  programSource: string,
+): ProgramBuilder {
+  const engine = opts.engine ?? createEngine();
+  const provenance: ProgramBuilderProvenance = {
+    entryId: opts.entryId,
+    catalogCgsHash: opts.cgsHash,
+    logicalSessionRef: opts.logicalSessionRef,
+    agentSessionId: opts.agentSessionId,
+  };
+
+  return {
+    ...provenance,
+    catalogRoot: opts.catalogRoot,
+    stubEntities: opts.stubEntities,
+    engine,
+    programSource,
+    program(source: string) {
+      return cloneBuilder(opts, source);
+    },
+    async dryRun() {
+      return engine.dryRun(programSource);
+    },
+    async run(planCommitRef: string, transport?: HostTransportFn) {
+      const hostTransport = transport ?? createDefaultHostTransport();
+      if (typeof engine.runPlanLive === "function") {
+        const live = await engine.runPlanLive(planCommitRef, hostTransport);
+        if (!live.ok) {
+          throw new Error(live.message);
+        }
+        return live;
+      }
+      const validation = await engine.runPlan(planCommitRef);
+      if (!validation.ok) {
+        throw new Error(validation.message);
+      }
+      return validation;
+    },
+  };
+}
+
+/** Typed program builder — dryRun/run delegate to NAPI PlasmEngine. */
+export function createProgramBuilder(opts: ProgramBuilderOptions): ProgramBuilder {
+  return cloneBuilder(opts, "");
+}

package/src/stubs/stub-symbols.ts

@@ -0,0 +1,89 @@
+import type { CapabilityIntrospectionJson, CatalogIntrospectionJson } from "./catalog-introspection.js";
+import {
+  classifyInvokeShape,
+  type CapabilityInvokeShape,
+} from "./capability-invoke-shape.js";
+
+export interface EntitySymbolBinding {
+  entity: string;
+  symbol: string;
+}
+
+export interface CapabilityBinding {
+  capability: string;
+  entitySymbol: string;
+  methodSymbol?: string;
+  methodWire: string;
+  invokeShape: CapabilityInvokeShape;
+}
+
+/** Entities with capabilities, stable lexicographic order → `e1`…`eN`. */
+export function stubEntityNames(catalog: CatalogIntrospectionJson): string[] {
+  return catalog.entities
+    .filter((e) => catalog.capabilities.some((c) => c.entity === e.name))
+    .map((e) => e.name)
+    .sort((a, b) => a.localeCompare(b));
+}
+
+/** Deterministic `e#` from catalog entity order (no teaching session / intent). */
+export function assignEntitySymbols(entityNames: string[]): Map<string, EntitySymbolBinding> {
+  const sorted = [...entityNames].sort((a, b) => a.localeCompare(b));
+  const out = new Map<string, EntitySymbolBinding>();
+  sorted.forEach((entity, index) => {
+    out.set(entity, { entity, symbol: `e${index + 1}` });
+  });
+  return out;
+}
+
+function methodSymbolForCapability(
+  cap: CapabilityIntrospectionJson,
+  entityCaps: CapabilityIntrospectionJson[],
+): string | undefined {
+  const shape = classifyInvokeShape(cap);
+  if (shape !== "MethodObject" && shape !== "MethodUnion") {
+    return undefined;
+  }
+  const dotted = entityCaps
+    .filter((c) => {
+      const s = classifyInvokeShape(c);
+      return s === "MethodObject" || s === "MethodUnion";
+    })
+    .sort((a, b) => a.name.localeCompare(b.name));
+  const index = dotted.findIndex((c) => c.name === cap.name);
+  if (index < 0) return undefined;
+  return `m${index + 1}`;
+}
+
+/** Deterministic invoke bindings from introspection only (program API, not agent teaching). */
+export function assignCapabilityBindings(
+  catalog: CatalogIntrospectionJson,
+): Map<string, CapabilityBinding> {
+  const entityNames = stubEntityNames(catalog);
+  const entitySymbols = assignEntitySymbols(entityNames);
+  const capsByEntity = new Map<string, CapabilityIntrospectionJson[]>();
+  for (const cap of catalog.capabilities) {
+    const list = capsByEntity.get(cap.entity) ?? [];
+    list.push(cap);
+    capsByEntity.set(cap.entity, list);
+  }
+
+  const out = new Map<string, CapabilityBinding>();
+  for (const cap of catalog.capabilities) {
+    const entityBinding = entitySymbols.get(cap.entity);
+    if (!entityBinding) continue;
+    const entityCaps = capsByEntity.get(cap.entity) ?? [];
+    const invokeShape = classifyInvokeShape(cap);
+    out.set(cap.name, {
+      capability: cap.name,
+      entitySymbol: entityBinding.symbol,
+      methodSymbol: methodSymbolForCapability(cap, entityCaps),
+      methodWire: cap.invoke_wire_name,
+      invokeShape,
+    });
+  }
+  return out;
+}
+
+export function capabilityReturnTypeName(entityName: string): string {
+  return entityName.replace(/[^a-zA-Z0-9_]/g, "_");
+}

package/src/symbol-registry.ts

@@ -0,0 +1,74 @@
+/**
+ * Agent-global append-only symbol registry (e#/m#/p#/r#).
+ * Teaching waves disclose symbols; this mirror supports operator UI and persistence.
+ */
+
+export type SymbolKind = "entity" | "method" | "param" | "relation";
+
+export interface SymbolBinding {
+  symbol: string;
+  kind: SymbolKind;
+  entryId: string;
+  wire: string;
+  entity?: string;
+  tombstoned?: boolean;
+}
+
+export interface SymbolRegistrySnapshot {
+  bindings: SymbolBinding[];
+  nextEntity: number;
+  nextMethod: number;
+  nextParam: number;
+  nextRelation: number;
+}
+
+export class SymbolRegistry {
+  private bindings: SymbolBinding[] = [];
+  private counters = { entity: 1, method: 1, param: 1, relation: 1 };
+
+  mint(kind: SymbolKind): string {
+    const prefix =
+      kind === "entity"
+        ? "e"
+        : kind === "method"
+          ? "m"
+          : kind === "param"
+            ? "p"
+            : "r";
+    const key = `${prefix}${this.counters[kind]}` as keyof typeof this.counters;
+    this.counters[kind] += 1;
+    return `${prefix}${this.counters[kind] - 1}`;
+  }
+
+  bind(binding: Omit<SymbolBinding, "symbol"> & { symbol?: string }): SymbolBinding {
+    const symbol = binding.symbol ?? this.mint(binding.kind);
+    const row: SymbolBinding = { ...binding, symbol };
+    this.bindings.push(row);
+    return row;
+  }
+
+  tombstone(symbol: string): void {
+    const row = this.bindings.find((b) => b.symbol === symbol);
+    if (row) row.tombstoned = true;
+  }
+
+  snapshot(): SymbolRegistrySnapshot {
+    return {
+      bindings: [...this.bindings],
+      nextEntity: this.counters.entity,
+      nextMethod: this.counters.method,
+      nextParam: this.counters.param,
+      nextRelation: this.counters.relation,
+    };
+  }
+
+  restore(snapshot: SymbolRegistrySnapshot): void {
+    this.bindings = [...snapshot.bindings];
+    this.counters = {
+      entity: snapshot.nextEntity,
+      method: snapshot.nextMethod,
+      param: snapshot.nextParam,
+      relation: snapshot.nextRelation,
+    };
+  }
+}

package/src/telemetry/plasm-spans.ts

@@ -0,0 +1,83 @@
+import { SpanStatusCode, trace, type Span } from "@opentelemetry/api";
+
+import { PlasmSpanAttributes } from "../instrumentation.js";
+
+export interface PlasmSpanContext {
+  sessionId?: string;
+  intent?: string;
+  logicalSessionRef?: string;
+  catalogCgsHash?: string;
+  entryId?: string;
+  planCommitRef?: string;
+  runId?: string;
+  toolName?: string;
+  transportHost?: string;
+  transportStatus?: number;
+}
+
+const tracer = trace.getTracer("plasm-agent");
+
+function applyPlasmAttributes(span: Span, ctx: PlasmSpanContext): void {
+  if (ctx.sessionId) span.setAttribute(PlasmSpanAttributes.SESSION_ID, ctx.sessionId);
+  if (ctx.intent) span.setAttribute(PlasmSpanAttributes.INTENT, ctx.intent);
+  if (ctx.logicalSessionRef) {
+    span.setAttribute(PlasmSpanAttributes.LOGICAL_SESSION_REF, ctx.logicalSessionRef);
+  }
+  if (ctx.catalogCgsHash) {
+    span.setAttribute(PlasmSpanAttributes.CATALOG_CGS_HASH, ctx.catalogCgsHash);
+  }
+  if (ctx.planCommitRef) {
+    span.setAttribute(PlasmSpanAttributes.PLAN_COMMIT_REF, ctx.planCommitRef);
+  }
+  if (ctx.runId) span.setAttribute(PlasmSpanAttributes.RUN_ID, ctx.runId);
+  if (ctx.entryId) span.setAttribute(PlasmSpanAttributes.ENTRY_ID, ctx.entryId);
+  if (ctx.toolName) span.setAttribute(PlasmSpanAttributes.TOOL_NAME, ctx.toolName);
+  if (ctx.transportHost) {
+    span.setAttribute(PlasmSpanAttributes.TRANSPORT_HOST, ctx.transportHost);
+  }
+  if (ctx.transportStatus !== undefined) {
+    span.setAttribute(PlasmSpanAttributes.TRANSPORT_STATUS, ctx.transportStatus);
+  }
+}
+
+export async function withPlasmSpan<T>(
+  name: string,
+  ctx: PlasmSpanContext,
+  fn: (span: Span) => Promise<T>,
+): Promise<T> {
+  return tracer.startActiveSpan(name, async (span) => {
+    applyPlasmAttributes(span, ctx);
+    try {
+      const result = await fn(span);
+      span.setStatus({ code: SpanStatusCode.OK });
+      return result;
+    } catch (error) {
+      span.recordException(error as Error);
+      span.setStatus({ code: SpanStatusCode.ERROR });
+      throw error;
+    } finally {
+      span.end();
+    }
+  });
+}
+
+export const plasmSpans = {
+  toolDiscover: <T>(ctx: PlasmSpanContext, fn: (span: Span) => Promise<T>) =>
+    withPlasmSpan("tool.discover_capabilities", { ...ctx, toolName: "discover_capabilities" }, fn),
+
+  toolContext: <T>(ctx: PlasmSpanContext, fn: (span: Span) => Promise<T>) =>
+    withPlasmSpan("tool.plasm_context", { ...ctx, toolName: "plasm_context" }, fn),
+
+  dryRun: <T>(ctx: PlasmSpanContext, fn: (span: Span) => Promise<T>) =>
+    withPlasmSpan("plasm.dry_run", ctx, fn),
+
+  liveRun: <T>(ctx: PlasmSpanContext, fn: (span: Span) => Promise<T>) =>
+    withPlasmSpan("plasm.live_run", ctx, fn),
+
+  transportHttp: <T>(ctx: PlasmSpanContext, fn: (span: Span) => Promise<T>) =>
+    withPlasmSpan("plasm.transport.http", ctx, fn),
+};
+
+export function activeTraceId(): string | undefined {
+  return trace.getActiveSpan()?.spanContext().traceId;
+}

package/src/tools/descriptions.ts

@@ -0,0 +1,94 @@
+/** MCP-aligned tool descriptions (from plasm-core prompt_render assets). */
+
+export const DISCOVER_TOOL_DESCRIPTION = `Plasm is a source language. Pick catalogs/entities for one user goal — this tool does **not** produce program symbols. Tool order: optional \`discover_capabilities\` → \`plasm_context\` → \`plasm\` (dry-run) → \`plasm_run\` (live).
+     **Next:** copy TSV \`api\`/\`entity\` rows into one **\`plasm_context\`** **\`seeds\`** array on the same **\`intent\`**, then write **\`plasm.program\`** from teaching TSV (get \`e#(p#)\` vs search \`e#~"…"\` when exposed). Skip when you already know every \`api\`/\`entity\`. No alternate JSON discovery mode.`;
+
+export const PLASM_CONTEXT_TOOL_DESCRIPTION = `Tool order: optional \`discover_capabilities\` → \`plasm_context\` → \`plasm\` (dry-run) → \`plasm_run\` (live).
+     **Call before \`plasm\` / \`plasm_run\`.** **One goal → one stable \`intent\` → one \`logical_session_ref\`.** Stable = same \`intent\` string on every turn for that goal (not per message/API). Bad: \`intent: "msg 3: sort moves"\` each turn — breaks reuse and fragments \`e#\`/\`p#\`. Multi-API: one **\`seeds\`** array on the same intent.
+**Session:** one goal → one **\`intent\`** → one **\`logical_session_ref\`**; use **\`e#\`/\`m#\`/\`p#\`/\`r#\` from this session's teaching TSV only** (contract examples are shapes; substitute from your table).
+
+**Federated homonyms:** when multiple catalogs expose the same wire entity, method, relation, or field name, programs must use opaque **\`e#\` / \`m#\` / \`r#\` / \`p#\`** from this table — not bare wire names and not \`entry_id:Entity\` syntax. Each symbol is catalog-scoped; copying the wrong row's symbol is a compile error.
+
+**Open or extend:** **\`intent\`** + **\`seeds\`** (\`{api, entity}\`).
+
+Returns **\`logical_session_ref\`** + fenced teaching TSV. TSV is the active symbol table: copy left cells into **\`plasm.program\`** (Plasm source, not JSON). Delta waves assign new **\`e#\`** monotonically.
+
+**Extend picks:** same **\`intent\`**, expanded **\`seeds\`** — delta TSV or reuse cheat sheet when already exposed.
+
+**\`_meta.plasm\`:** \`logical_session_ref\`, \`continuity\`, \`domain_revision\`, optional **\`relations\`**.`;
+
+export const PLASM_TOOL_DESCRIPTION = `**Plan Plasm** (dry-run): **\`logical_session_ref\`** + **\`program\`**. Returns reviewable plan topology and executable **\`plan_commit_ref\`** (\`pcN\`). Pass that token to **\`plasm_run\`**; do **not** echo the program.
+
+**\`program\` is Plasm source text, not JSON data.** Write one raw expression (e.g. \`e3(p15="electric").r2[p4,p5]\`) or multiline bindings with final roots. If a plan merely echoes an object/array/string literal, that is a literal no-op; rewrite as Plasm source.
+
+Grammar below; symbols from \`plasm_context\` TSV. Reply with one valid plasm_program:
+
+Output:
+- Emit only code: one \`plasm_expr\`, or bindings then final roots. No prose, JSON, \`return\`, fences, or table rows.
+- Prefer bind → narrow/project/transform → few final roots.
+
+TSV table semantics:
+- Header: \`plasm_expr<TAB>Meaning\`; one tab per row. Left = syntax/metadata; right = guidance only (never copy \`Meaning\`).
+- Executable rows start with \`e#\`/Entity; metadata-only \`p#\`/\`v#\` rows are never roots.
+
+Symbol and fill rules:
+- \`e#\` entity; \`m#\` method; \`p#\` field/param/filter; \`r#\` relation nav; \`v#\` value-domain metadata only.
+- Relation hops: \`.wire\` or \`.r#\` on row producers — never bare \`p#\` after \`.\` (\`p#\` in \`e#{…}\` is filter/param).
+- Never write \`v#\` in code; use \`p#\` keys and read \`v#\` rows for allowed values.
+- \`e#(p#)\` identity rows: substitute real wire ids for \`<id>\`, \`<value>\`, \`<receiver>\`, \`elem\`.
+- Remove \`..\` ellipses or replace with real \`p#=\` assignments before output.
+- Optional keys (\`opt:\` in \`Meaning\`): add only as keyed assignments with real values.
+- Projection rows ending \`[p#,…]\` teach a valid field set. Reuse that suffix only on another expression returning the same entity or list type.
+
+Core surface:
+- Program shape: one \`plasm_expr\`, or \`label = …\` bindings then comma-separated final roots (no \`return\`).
+- Postfix on row producers: \`.limit(N)\` | \`.page_size(N)\` | \`.sort(p#, desc)\` / \`.sort(p#,dir)\` | \`.filter{…}\` | \`.filter(…)\` | \`.aggregate(specs)\` | \`.group_by(p#)\` then \`.aggregate(specs)\` | \`.group_by(p#, specs)\` (comma sugar) | \`.dedupe(p#[, …])\` | \`.distinct(p#[, …])\` | \`.distinct()\` | \`.singleton()\` | \`[p#,…]\`. Row postfix fields use teaching \`rows:\` \`p#\` symbols; wire field names are sugar.
+- Large list reads return the first **25 rows** in \`plasm_run\`; continue with \`page(l_<token>_pgN)\` from the tool result — not \`resources/read\`.
+- Run gate: pass \`pcN\` from a prior dry-run to \`plasm_run\`; MCP \`plasm_run\` does not accept program continuations.
+- Copy teaching TSV left cells; substitute placeholders; compose via bindings.
+- Search when exposed: \`e#~$\` or \`e#~"text"\` (bare \`e#~\` is invalid); optional scoped filters \`e#~"text"[{p#=…}]\`.
+- Field projection suffix: \`[p#,…]\`.
+
+Composition rules:
+- One binding per line; final roots last (preferred). Single-line bindings coerced; default return is first binding.
+- Postfix/\`[fields]\` chain on any row-producing binding or expression.
+- Row text: \`label = source <<TAG\` … \`TAG\` (equals required — never \`label source <<TAG\`); optional column list: \`label = source[p#,…] <<TAG\`. Minijinja \`rows\` = that source's projected rows only — not \`\${}\`.
+- Pass \`binding.content\` to string params; compose with \`\${report.content}\` in later heredocs/strings (never bare \`\${}\` in prose; \`$$\` escapes \`$\`).
+- Minijinja \`{{ }}\` / \`{% %}\` only inside row-to-text heredoc bodies — not in capability heredocs that use \`\${binding.path}\`.
+- Do not use \`report.content\` as a final root or relation receiver.
+- Action/create roots: return the action row or follow with \`e#(p#=…)\` get — not \`created.p#\` as a program root.
+- Relation embed fan-out (\`Type.pokemon\` / \`.r#\`): prefer explicit Gets until embed path is warm; \`.limit\` on relation hops may need hydrate when graph targets are missing.
+- Heredoc: \`<<TAG\` + newline; first trimmed \`TAG\` line closes; pick a tag absent from the body.
+- Examples: array argument \`p#=[e#(<id>), …]\`. Quoted strings use only \`\\"\` and \`\\\\\` escapes.
+- Worked row-compute program (shape only — substitute \`e#\` / \`p#\` from your table below):
+items = e_source
+filtered = items.filter{p_field>=300}  # prefer bind; bare \`e_source.filter{…}\` list-alls first
+sorted = filtered.sort(p_field, desc)
+limited = sorted.limit(10)
+limited[p_a,p_field]
+- Worked federated relation + row compute (shape only — copy \`e#\` / \`.r#\` from your table's left column):
+parent = e2(p_key=<val>)
+children = parent.rN
+limited = children.limit(5)
+limited[p_a,p_b]
+- \`markdown\`/\`html\`/\`document\`/\`json_text\`/\`blob\` values (per \`Meaning\`): \`<<TAG\` … \`TAG\` only; e.g. \`e2.mN(..., p#=<<TXT\` + newline body + \`TXT\` newline \`)\`.
+
+Common pitfalls:
+- \`[fields]\`/\`.group_by\`/\`.sort\`/\`.dedupe\`/row \`.filter\` use \`rows:\` fields only — not \`inputs:\`/\`opt:\` filter keys.
+- \`e#{…}\` filters at HTTP; \`binding.filter{…}\` filters materialized rows. Prefer \`label = e#\` then filter; bare \`e#.filter{…}\` list-alls first.
+- Primary group/agg: \`group_by(p_key).aggregate(n=count)\`; bare \`group_by(p_key)\` ≡ \`group_by(p_key, count=count)\`; multi-key comma sugar: \`group_by(k1, k2, n=count)\`.
+- \`=>\` only for derive \`{ k: _.field }\` or \`for_each\` updates — not relation reads (\`labels = issues.r#\`).
+- Homograph: relation fanout via \`.r#\`/wire; \`labels = issues.p#\` forgiven when binding name matches.
+- Never emit \`$\` from teaching rows; substitute real ids and \`e#~"text"\` search terms.
+- Search operand: \`e#~$\` or \`e#~"text"\` required — bare \`e#~\` is a parse error.
+- Federated sessions: when the same wire entity/method/relation/field name appears in multiple catalogs, bare wire tokens are compile errors — copy the session \`e#\` / \`m#\` / \`r#\` / \`p#\` from the teaching row for that catalog. Never write \`entry_id:Entity\` or \`catalog.Entity\` in programs.
+- Cross-catalog stitch (shape only — substitute symbols from your TSV): pokeapi \`Type\` get → row-to-text bindings → proof \`ShareLink\` document param with \`\${binding.content}\` inside \`<<TAG\` … \`TAG\`.
+- Search-only entities (no query): no \`e#{}\` list-all — scoped \`e#{p#=…}\` and/or \`e#~"text"\`.`;
+
+export const PLASM_RUN_TOOL_DESCRIPTION = `**Run Plasm** (live): **\`logical_session_ref\`** + **\`plan_commit_ref\`** (\`pcN\`) from a prior **\`plasm\`** dry-run. Real HTTP/API; may return **\`resource_link\`** / \`_meta.plasm\` snapshots.
+
+**Review gate:** \`plasm_run\` executes exactly the reviewed plan stored under the **\`plan_commit_ref\`**. If the token is missing, expired, or from another plan, call **\`plasm\`** again.
+
+**Live execute:** server spawns one async operation and awaits terminal rows in the tool response. Progress uses standard \`notifications/plasm/op\` on the registered handle.
+
+**Live results:** \`## {return_label} ({n} rows)\` + capped TSV (25 rows inline); multi-return programs use \`# Results\` with \`### {label} ({n} rows)\` per root. When more rows exist, continue with \`page(l_<token>_pgN)\` from the tool result or \`_meta.plasm.paging\`. Snapshot URI lines point at full JSON via MCP **\`resources/read\`** when needed. Run Explorer is supplemental.`;

package/src/tools/format.ts

@@ -0,0 +1,29 @@
+export function formatPlasmContextMarkdown(
+  logicalSessionRef: string,
+  tsv: string,
+  reused: boolean,
+): string {
+  const delta = tsv.trim();
+  if (!delta) {
+    if (reused) {
+      return `\`${logicalSessionRef}\`\n\nUnchanged — seeds already exposed. Next: \`plasm\` / \`plasm_run\`.\n`;
+    }
+    return `\`${logicalSessionRef}\`\n`;
+  }
+  return `\`${logicalSessionRef}\`\n\n\`\`\`tsv\n${delta}\n\`\`\`\n`;
+}
+
+export function formatPlasmDryRunMarkdown(summary: string, planCommitRef: string): string {
+  return `\`\`\`text\n${summary.trim()}\n\`\`\`\n\n**Run:** pass \`plan_commit_ref\`: \`${planCommitRef}\` to **\`plasm_run\`**. Do not echo the program.`;
+}
+
+export function formatPlasmRunMarkdown(
+  message: string,
+  ok: boolean,
+  rowsJson?: string,
+): string {
+  if (!ok) return `**plasm_run** (pending transport)\n\n${message}`;
+  const rows = rowsJson?.trim();
+  if (!rows) return message;
+  return `${message}\n\n\`\`\`json\n${rows}\n\`\`\``;
+}

package/src/tools/harness-tools.ts

@@ -0,0 +1,65 @@
+import { tool } from "ai";
+import { z } from "zod";
+
+import type { SkillDefinition } from "../authoring/define-skill.js";
+import type { SubagentRegistry } from "../authoring/subagent-loader.js";
+
+export function createHarnessTools(options: {
+  skills?: SkillDefinition[];
+  subagents?: SubagentRegistry;
+}) {
+  const skillByName = new Map((options.skills ?? []).map((s) => [s.name, s]));
+
+  const readSkill =
+    skillByName.size > 0
+      ? {
+          read_skill: tool({
+            description:
+              "Load full text for a filesystem skill by name. Use when the skill index in the system prompt is not enough.",
+            inputSchema: z.object({
+              name: z.string().min(1).describe("Skill name from the index"),
+            }),
+            execute: async ({ name }: { name: string }) => {
+              const skill = skillByName.get(name);
+              if (!skill) {
+                return `Unknown skill "${name}". Available: ${[...skillByName.keys()].join(", ")}`;
+              }
+              return skill.body.trim();
+            },
+          }),
+        }
+      : {};
+
+  const subagentNames = options.subagents?.list().map((s) => s.name) ?? [];
+  const delegateSubagent =
+    subagentNames.length > 0 && options.subagents
+      ? {
+          delegate_subagent: tool({
+            description:
+              "Delegate a sub-task to a filesystem-isolated child agent. Each subagent has its own catalogs and session scope.",
+            inputSchema: z.object({
+              name: z
+                .string()
+                .min(1)
+                .describe(`Subagent name. One of: ${subagentNames.join(", ")}`),
+              message: z.string().min(1).describe("User message for the child agent turn"),
+            }),
+            execute: async ({ name, message }: { name: string; message: string }) => {
+              const result = await options.subagents!.delegate(name, message);
+              return `${result.text}\n\n(steps: ${result.steps})`;
+            },
+          }),
+        }
+      : {};
+
+  return { ...readSkill, ...delegateSubagent };
+}
+
+export function renderSkillIndex(skills: SkillDefinition[]): string {
+  if (!skills.length) return "";
+  const lines = skills.map((skill) => {
+    const desc = skill.description ?? "Filesystem skill";
+    return `- **${skill.name}** — ${desc} (use read_skill to load)`;
+  });
+  return ["## Skill index", ...lines].join("\n");
+}