@crewhaus/ir 0.3.2 → 0.4.2

package/dist/index.js

@@ -1,3 +1,8 @@
 // Generated-bundle README renderer (item 42) — pure functions over the IR,
 // shared by every target emitter. See ./readme.ts for the module docs.
 export { GENERATED_README_MARKER, collectSecretRefs, renderBundleReadme, } from "./readme";
+// Loop contract 0.4 (Batch B, G42) — the canonical agent-loop projection
+// (`projectLoop(ir)`), whose LoopProjection shape is the wire contract
+// shared with the studio's /builder page and the compiler-worker's
+// `POST /loop` endpoint. See ./loop.ts for the module docs.
+export { CANVAS_TARGETS, NO_BUDGET_WARNING, PERCEIVE_TOOL_RE, RING_TARGETS, SEGMENT_ORDER, projectLoop, } from "./loop";

package/dist/loop.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Loop contract 0.4 (Batch B, G42) — `projectLoop(ir)`: project a lowered
+ * {@link IrNode} into its canonical AGENT-LOOP phase graph.
+ *
+ * The {@link LoopProjection} shape below is the WIRE CONTRACT shared with
+ * the studio's client-side projection (`studio-pwa/src/lib/loop-model.ts`):
+ * plain JSON-serializable data — no functions, no classes — rendered by the
+ * /builder page verbatim. The compiler-worker's `POST /loop` endpoint
+ * returns exactly this object for `projectLoop(lower(parseSpec(yaml)))`.
+ *
+ * Two projection kinds:
+ *   - `"ring"`   — single-agent shapes (cli / channel / managed): the
+ *     seven-component loop as ring segments (perceive / reason / act /
+ *     evaluate / update) plus the Stop and Safety boundary panels.
+ *   - `"canvas"` — step/node/role shapes (workflow / graph / crew /
+ *     pipeline / research / batch): steps/nodes/roles as canvas nodes,
+ *     edges/handoffs as arrows, HITL and judge gates surfaced, each node
+ *     carrying its own mini seven-segment summary.
+ *
+ * The remaining shapes (voice / browser / eval / onchain / onchain-game)
+ * fall back to the generic ring with an honest warning — "say so rather
+ * than shrink".
+ *
+ * MAPPING SOURCE OF TRUTH: the IR's RESOLVED fields, not the raw spec.
+ * This differs from the studio's spec-object projection in two deliberate
+ * ways:
+ *   - default-on config that the runtime WILL wire lights its segment
+ *     (e.g. cli continuity is default-on in 0.3+, so `update` is active
+ *     unless the spec opted out) — the projection reports what the loop
+ *     actually does;
+ *   - per-step/node models are resolved at lower time, so node minis always
+ *     show the resolved model (the spec-side "inherits the spec-level
+ *     model" state is not reconstructible from IR).
+ * Stop stays defaults-honest: with neither `budget` nor `limits` in the IR
+ * the segment is inactive and {@link NO_BUDGET_WARNING} is emitted.
+ *
+ * `keys` entries remain SPEC-dotted paths (`"agent.model_pool"`,
+ * `"channels.slack"`, `"tools[webFetch]"`) so the operator can jump from a
+ * segment to the YAML that (would) configure it.
+ *
+ * Pure functions of the IR — no I/O, no imports beyond the IR types.
+ */
+import type { IrNode } from "./index";
+/** The seven loop components, in canonical render order. */
+export type LoopSegmentId = "perceive" | "reason" | "act" | "evaluate" | "update" | "stop" | "safety";
+/** Canonical segment order — every ring and every node mini uses exactly this. */
+export declare const SEGMENT_ORDER: readonly LoopSegmentId[];
+/**
+ * One loop component. `active` iff the RESOLVED IR configures it; `keys`
+ * are the dotted spec paths that lit it (e.g. "agent.model_pool",
+ * "tools[webFetch]", "channels.slack"); `summary` is a one-line,
+ * operator-facing description of what is (or isn't) configured.
+ */
+export type LoopSegment = {
+    readonly id: LoopSegmentId;
+    readonly active: boolean;
+    readonly keys: readonly string[];
+    readonly summary: string;
+};
+/** The single-agent loop ring: always all seven segments, in SEGMENT_ORDER. */
+export type LoopRing = {
+    readonly segments: readonly LoopSegment[];
+};
+/**
+ * What a canvas node represents on its shape. EXACTLY the studio's
+ * `LoopNodeKind` union (studio-pwa `src/lib/loop-model.ts`) — the studio
+ * renderer is the wire consumer, so factory must not emit kinds outside it.
+ * Research branches and the batch queue render as `"node"`, mirroring the
+ * studio's own client-side projection of those shapes.
+ */
+export type LoopNodeKind = "step" | "node" | "role" | "doc";
+/**
+ * One canvas node (a workflow step, graph node, crew role, research branch,
+ * batch queue, or a doc/report artifact). `hitl` marks a human-approval
+ * badge; `mini` is the node's own seven-segment summary.
+ */
+export type LoopNode = {
+    readonly id: string;
+    readonly label: string;
+    readonly kind: LoopNodeKind;
+    readonly hitl?: boolean;
+    readonly mini: readonly LoopSegment[];
+};
+/** One canvas arrow. `conditional` marks a guarded edge (a graph `when`, a
+ *  judge gate's pass/retry, a routing rule). */
+export type LoopEdge = {
+    readonly from: string;
+    readonly to: string;
+    readonly label?: string;
+    readonly conditional?: boolean;
+};
+export type LoopCanvas = {
+    readonly nodes: readonly LoopNode[];
+    readonly edges: readonly LoopEdge[];
+};
+/**
+ * The full projection. Exactly one of `ring` / `canvas` is set, matching
+ * `kind`. `target` is the IR's target. `warnings` carry defaults-only
+ * boundaries (see {@link NO_BUDGET_WARNING}), family hints for fallback
+ * targets, and structural notes (crew routing, dangling graph edges,
+ * parallel barrier groups).
+ */
+export type LoopProjection = {
+    readonly kind: "ring" | "canvas";
+    readonly target: string;
+    readonly ring?: LoopRing;
+    readonly canvas?: LoopCanvas;
+    readonly warnings: readonly string[];
+};
+/** Single-agent shapes rendered as the seven-component ring. */
+export declare const RING_TARGETS: readonly string[];
+/** Step/node/role shapes rendered as a node canvas. */
+export declare const CANVAS_TARGETS: readonly string[];
+/**
+ * The exact defaults-only Stop warning (guardrails-first affordance): with
+ * neither `budget:` nor `limits:` the loop's only boundary is the runtime's
+ * hardcoded tool-iteration cap. Shared verbatim with the studio.
+ */
+export declare const NO_BUDGET_WARNING = "no budget: \u2014 stops only at the 500-iteration default";
+/**
+ * Tool names that count as PERCEPTION (bringing outside state into the
+ * loop) rather than plain action. Everything in `tools` still counts toward
+ * the Act segment; matching names ALSO light Perceive.
+ */
+export declare const PERCEIVE_TOOL_RE: RegExp;
+/**
+ * Project a lowered IR into its canonical loop view. Total over the IrNode
+ * union and never throws: every variant maps to a ring or canvas, and the
+ * shapes without a dedicated projection fall back to the generic ring with
+ * an honest warning.
+ */
+export declare function projectLoop(ir: IrNode): LoopProjection;