agentfootprint 2.14.5 → 3.1.0

package/dist/types/core/translator.d.ts

@@ -0,0 +1,95 @@
+/**
+ * GroupTranslator — UI-agnostic composition-level translator hook.
+ *
+ * Pattern: Visitor (GoF) at the composition boundary. Consumer supplies
+ *          a translator function; each agentfootprint composition
+ *          (Parallel, Sequence, Loop, Conditional, Agent, LLMCall)
+ *          invokes it with composition-level metadata to produce a
+ *          consumer-shaped UI output.
+ * Role:    The per-COMPOSITION hook alongside footprintjs's per-NODE
+ *          `StructureRecorder`. The two are independent — a consumer
+ *          can attach either, both, or neither.
+ *
+ *          - StructureRecorder observes ONE spec node at a time (record).
+ *          - GroupTranslator sees the WHOLE composition (compose).
+ *
+ *          For Lens's compound rendering (Parallel-as-container,
+ *          Agent-as-drillable-card, LLMCall-as-card-with-slots),
+ *          this is the right granularity: the translator knows the
+ *          composition KIND and its full member list at once, so it
+ *          can emit a single group-level shape with children pre-laid.
+ *
+ * Cascade: each composition that runs nested compositions exposes its
+ *          members' OWN translated outputs via `GroupMember.uiGroup`.
+ *          The consumer threads the same translator through every
+ *          composition's construction (or per-method override via
+ *          L1c) to get end-to-end coverage. No automatic propagation
+ *          — propagation requires footprintjs-level changes which
+ *          we're not making for this hook.
+ */
+import type { Runner } from './runner.js';
+/**
+ * The composition KIND a translator sees in `GroupMetadata.kind`.
+ * Closed union — every agentfootprint composition declares exactly
+ * one of these via the literal string baked into its `buildChart()`
+ * description prefix and surfaced here in `GroupMetadata`.
+ */
+export type GroupKind = 'Parallel' | 'Sequence' | 'Loop' | 'Conditional' | 'Agent' | 'LLMCall';
+/**
+ * One member of a composition. Shape is uniform across composition
+ * kinds — Parallel branches, Sequence steps, Loop body, Conditional
+ * branches, Agent tools/slots, LLMCall slots all map to this.
+ *
+ * `memberId` is the stable id the composition assigned (e.g. `legal`
+ * for a Parallel branch, `step-classify` for a Sequence step,
+ * `body` for a Loop). Consumers can correlate this with the
+ * SpecNode's `subflowId` / `id` to drill in.
+ *
+ * `runner` is the underlying `Runner` instance — useful for the
+ * consumer to call `member.runner.getSpec()` for the nested chart or
+ * `member.runner.getUIGroup()` for the nested translation result
+ * (when the same translator was threaded through that runner's
+ * construction).
+ *
+ * `uiGroup` is the member's already-translated output. Populated
+ * when the consumer threaded the same `groupTranslator` reference
+ * into each member's construction; `undefined` otherwise.
+ */
+export interface GroupMember {
+    readonly memberId: string;
+    readonly runner: Runner;
+    readonly uiGroup?: unknown;
+}
+/**
+ * What a composition hands to its `groupTranslator` at build time.
+ * All composition kinds emit the same shape — the `kind` discriminator
+ * + the `extra` bag carry per-composition specifics.
+ */
+export interface GroupMetadata {
+    readonly kind: GroupKind;
+    readonly id: string;
+    readonly name: string;
+    readonly members: ReadonlyArray<GroupMember>;
+    /**
+     * Composition-specific extras. Carried verbatim from the
+     * composition's own state — `Parallel` puts the merge strategy
+     * here, `Loop` puts iteration budgets, `Conditional` puts the
+     * fallback branch id, etc. Closed enough per kind that consumers
+     * can switch on `kind` to read it safely.
+     */
+    readonly extra?: Readonly<Record<string, unknown>>;
+}
+/**
+ * The consumer-supplied translator. Pure function — no async, no
+ * side effects expected. Runs ONCE per composition at the moment
+ * `getUIGroup()` is first called (memoised behaviour is per
+ * composition's discretion).
+ *
+ * Output type `T` is whatever the consumer wants — a React Flow
+ * group node, a Mermaid string, a domain-specific layout object,
+ * anything. agentfootprint stays UI-agnostic.
+ */
+export interface GroupTranslator<T = unknown> {
+    (group: GroupMetadata): T;
+}
+//# sourceMappingURL=translator.d.ts.map

package/dist/types/core/translator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"translator.d.ts","sourceRoot":"","sources":["../../../src/core/translator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,UAAU,GAAG,UAAU,GAAG,MAAM,GAAG,aAAa,GAAG,OAAO,GAAG,SAAS,CAAC;AAE/F;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;IAC7C;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACpD;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,GAAG,OAAO;IAC1C,CAAC,KAAK,EAAE,aAAa,GAAG,CAAC,CAAC;CAC3B"}

package/dist/types/core-flow/Conditional.d.ts

@@ -11,13 +11,31 @@
  * v1 of this primitive supports `.when(id, predicate, runner)` + `.otherwise(id, runner)`.
  * LLM-gated routing (`.whenLLM(id, prompt, runner)`) lands in Phase 5.
  */
-import { type FlowChart, type FlowchartCheckpoint, type RunOptions } from 'footprintjs';
+import { type FlowchartCheckpoint, type RunOptions, type StructureRecorder } from 'footprintjs';
+import type { GroupMetadata, GroupTranslator } from '../core/translator.js';
 import type { RunnerPauseOutcome } from '../core/pause.js';
 import type { Runner } from '../core/runner.js';
 import { RunnerBase } from '../core/RunnerBase.js';
 export interface ConditionalOptions {
     readonly name?: string;
     readonly id?: string;
+    /**
+     * Optional build-time recorders passed through to footprintjs's
+     * `flowChart()` factory. Each recorder observes per-node build
+     * events (`onStageAdded` / `onSubflowMounted` / etc.) for this
+     * composition's internal chart (Seed + Route decider + each branch
+     * mount + Finalize). When omitted, no build-time observation is
+     * wired up.
+     */
+    readonly structureRecorders?: readonly StructureRecorder[];
+    /**
+     * Optional per-COMPOSITION translator (UI-agnostic). See
+     * `core/translator.ts`. When attached, `runner.getUIGroup()` invokes
+     * it with the Conditional's `GroupMetadata` (kind `'Conditional'`,
+     * id, name, branches as members, plus `extra.fallbackId`).
+     * Returns `undefined` when omitted.
+     */
+    readonly groupTranslator?: GroupTranslator;
 }
 export interface ConditionalInput {
     readonly message: string;
@@ -33,16 +51,35 @@ interface BranchEntry {
     readonly runner: BranchChild;
     /** Undefined for the `otherwise` fallback. */
     readonly predicate?: Predicate;
+    /** Optional per-method translator override for THIS branch only. */
+    readonly groupTranslator?: GroupTranslator;
+}
+/**
+ * Options bag accepted by `ConditionalBuilder.when()` and `.otherwise()`
+ * for per-method overrides. Backwards-compatible — when the trailing
+ * arg is a string, it's still treated as `name`.
+ */
+export interface ConditionalBranchOptions {
+    /** Human-friendly name for this branch. Default: the branch id. */
+    readonly name?: string;
+    /** Per-method translator override. See `BranchEntry.groupTranslator`. */
+    readonly groupTranslator?: GroupTranslator;
 }
 export declare class Conditional extends RunnerBase<ConditionalInput, ConditionalOutput> {
     readonly name: string;
     readonly id: string;
     private readonly branches;
     private readonly fallbackId;
+    private readonly opts;
     private currentRunContext;
     constructor(opts: ConditionalOptions, branches: readonly BranchEntry[], fallbackId: string);
     static create(opts?: ConditionalOptions): ConditionalBuilder;
-    toFlowChart(): FlowChart;
+    protected getGroupTranslator(): GroupTranslator | undefined;
+    /** Conditional: one member per branch (.when / .otherwise), plus
+     *  `extra.fallbackId` marking the otherwise branch. Per-method
+     *  overrides (L1c) take precedence over the branch runner's own
+     *  translator. */
+    protected buildUIGroupMetadata(): GroupMetadata;
     run(input: ConditionalInput, options?: RunOptions): Promise<ConditionalOutput | RunnerPauseOutcome>;
     resume(checkpoint: FlowchartCheckpoint, input?: unknown, options?: RunOptions): Promise<ConditionalOutput | RunnerPauseOutcome>;
     private createExecutor;
@@ -64,12 +101,19 @@ export declare class ConditionalBuilder {
      * Register a predicate-gated branch. `predicate` is a pure sync function
      * of the Conditional's input; if it returns true, the corresponding
      * runner executes. Branches evaluate in registration order.
+     *
+     * Fourth arg accepts EITHER a legacy bare `name` string OR a
+     * `ConditionalBranchOptions` bag containing `name` and/or a per-method
+     * `groupTranslator` override. The override applies ONLY to this
+     * branch's `member.uiGroup`.
      */
-    when(id: string, predicate: Predicate, runner: BranchChild, name?: string): this;
+    when(id: string, predicate: Predicate, runner: BranchChild, nameOrOpts?: string | ConditionalBranchOptions): this;
     /**
      * Register the fallback branch. Exactly ONE must be registered before build().
+     * Third arg accepts a legacy `name` string OR a `ConditionalBranchOptions`
+     * bag (same shape as `.when()`).
      */
-    otherwise(id: string, runner: BranchChild, name?: string): this;
+    otherwise(id: string, runner: BranchChild, nameOrOpts?: string | ConditionalBranchOptions): this;
     build(): Conditional;
 }
 export {};

package/dist/types/core-flow/Conditional.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Conditional.d.ts","sourceRoot":"","sources":["../../../src/core-flow/Conditional.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAGL,KAAK,SAAS,EACd,KAAK,mBAAmB,EACxB,KAAK,UAAU,EAEhB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAa,MAAM,uBAAuB,CAAC;AAQ9D,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC;AAEvC,KAAK,WAAW,GAAG,MAAM,CAAC;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,EAAE,MAAM,CAAC,CAAC;AAEvD,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,gBAAgB,KAAK,OAAO,CAAC;AAE7D,UAAU,WAAW;IACnB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;CAChC;AAMD,qBAAa,WAAY,SAAQ,UAAU,CAAC,gBAAgB,EAAE,iBAAiB,CAAC;IAC9E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyB;IAClD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC,OAAO,CAAC,iBAAiB,CAIvB;gBAEU,IAAI,EAAE,kBAAkB,EAAE,QAAQ,EAAE,SAAS,WAAW,EAAE,EAAE,UAAU,EAAE,MAAM;IAW1F,MAAM,CAAC,MAAM,CAAC,IAAI,GAAE,kBAAuB,GAAG,kBAAkB;IAIhE,WAAW,IAAI,SAAS;IAIlB,GAAG,CACP,KAAK,EAAE,gBAAgB,EACvB,OAAO,CAAC,EAAE,UAAU,GACnB,OAAO,CAAC,iBAAiB,GAAG,kBAAkB,CAAC;IAS5C,MAAM,CACV,UAAU,EAAE,mBAAmB,EAC/B,KAAK,CAAC,EAAE,OAAO,EACf,OAAO,CAAC,EAAE,UAAU,GACnB,OAAO,CAAC,iBAAiB,GAAG,kBAAkB,CAAC;IAOlD,OAAO,CAAC,cAAc;IAqBtB,OAAO,CAAC,cAAc;IAWtB,OAAO,CAAC,UAAU;CAqHnB;AAED;;;GAGG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAqB;IAC1C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAC9C,OAAO,CAAC,kBAAkB,CAAS;IACnC,OAAO,CAAC,UAAU,CAAM;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;gBAEjC,IAAI,EAAE,kBAAkB;IAIpC;;;;OAIG;IACH,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI;IAShF;;OAEG;IACH,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI;IAc/D,KAAK,IAAI,WAAW;CAQrB"}
+{"version":3,"file":"Conditional.d.ts","sourceRoot":"","sources":["../../../src/core-flow/Conditional.ts"],"names":[],"mappings":"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"}

package/dist/types/core-flow/Loop.d.ts

@@ -15,13 +15,30 @@
  * Hard ceiling of 500 iterations prevents runaway loops even if a guard
  * misfires; exceeding it throws.
  */
-import { type FlowChart, type FlowchartCheckpoint, type RunOptions } from 'footprintjs';
+import { type FlowchartCheckpoint, type RunOptions, type StructureRecorder } from 'footprintjs';
+import type { GroupMetadata, GroupTranslator } from '../core/translator.js';
 import type { RunnerPauseOutcome } from '../core/pause.js';
 import type { Runner } from '../core/runner.js';
 import { RunnerBase } from '../core/RunnerBase.js';
 export interface LoopOptions {
     readonly name?: string;
     readonly id?: string;
+    /**
+     * Optional build-time recorders passed through to footprintjs's
+     * `flowChart()` factory. Each recorder observes per-node build
+     * events (`onStageAdded` / `onSubflowMounted` / etc.) for this
+     * composition's internal chart (Seed + IterationStart + body mount +
+     * Guard). When omitted, no build-time observation is wired up.
+     */
+    readonly structureRecorders?: readonly StructureRecorder[];
+    /**
+     * Optional per-COMPOSITION translator (UI-agnostic). See
+     * `core/translator.ts`. When attached, `runner.getUIGroup()` invokes
+     * it with the Loop's `GroupMetadata` (kind `'Loop'`, id, name, body
+     * as the single member, plus iteration budgets in `extra`).
+     * Returns `undefined` when omitted.
+     */
+    readonly groupTranslator?: GroupTranslator;
 }
 export interface LoopInput {
     readonly message: string;
@@ -43,14 +60,23 @@ export declare class Loop extends RunnerBase<LoopInput, LoopOutput> {
     private readonly maxIterations;
     private readonly maxWallclockMs;
     private readonly until;
+    private readonly opts;
+    /** Per-method translator override on `.repeat()`, when set. Applies
+     *  to the body member's `uiGroup`. */
+    private readonly bodyTranslator;
     private currentRunContext;
     constructor(opts: LoopOptions, body: BodyChild, config: {
         maxIterations: number;
         maxWallclockMs?: number;
         until?: UntilGuard;
+        bodyTranslator?: GroupTranslator;
     });
     static create(opts?: LoopOptions): LoopBuilder;
-    toFlowChart(): FlowChart;
+    protected getGroupTranslator(): GroupTranslator | undefined;
+    /** Loop has a single body member + iteration budgets in `extra`.
+     *  Per-method override (L1c) takes precedence over the body
+     *  runner's own translator. */
+    protected buildUIGroupMetadata(): GroupMetadata;
     run(input: LoopInput, options?: RunOptions): Promise<LoopOutput | RunnerPauseOutcome>;
     resume(checkpoint: FlowchartCheckpoint, input?: unknown, options?: RunOptions): Promise<LoopOutput | RunnerPauseOutcome>;
     private createExecutor;
@@ -66,9 +92,18 @@ export declare class Loop extends RunnerBase<LoopInput, LoopOutput> {
  * 10 iterations (hard ceiling 500). Any of .times / .forAtMost / .until
  * can fire to exit the loop.
  */
+/**
+ * Options bag accepted by `LoopBuilder.repeat()` for per-method overrides.
+ */
+export interface LoopRepeatOptions {
+    /** Per-method translator override for the body runner — overrides
+     *  the runner's own constructor-level translator for THIS loop only. */
+    readonly groupTranslator?: GroupTranslator;
+}
 export declare class LoopBuilder {
     private readonly opts;
     private _body;
+    private _bodyTranslator;
     private _maxIterations;
     private _maxWallclockMs;
     private _until;
@@ -76,8 +111,12 @@ export declare class LoopBuilder {
     /**
      * The runner that executes each iteration. Required.
      * Each iteration's output string becomes the next iteration's input `{ message }`.
+     *
+     * Optional second arg `opts.groupTranslator` overrides the body
+     * runner's own translator for THIS loop only — only its
+     * `member.uiGroup` flips to the override's output.
      */
-    repeat(runner: BodyChild): this;
+    repeat(runner: BodyChild, opts?: LoopRepeatOptions): this;
     /**
      * Maximum iteration count. Default 10 if only `.repeat()` is called.
      * Hard ceiling 500 — larger values are clamped.

package/dist/types/core-flow/Loop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Loop.d.ts","sourceRoot":"","sources":["../../../src/core-flow/Loop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAGL,KAAK,SAAS,EACd,KAAK,mBAAmB,EACxB,KAAK,UAAU,EAEhB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAa,MAAM,uBAAuB,CAAC;AAQ9D,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC;AAEhC,KAAK,SAAS,GAAG,MAAM,CAAC;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,EAAE,MAAM,CAAC,CAAC;AAErD,mFAAmF;AACnF,MAAM,MAAM,UAAU,GAAG,CAAC,GAAG,EAAE;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B,KAAK,OAAO,CAAC;AAQd,qBAAa,IAAK,SAAQ,UAAU,CAAC,SAAS,EAAE,UAAU,CAAC;IACzD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAY;IACjC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqB;IACpD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAyB;IAE/C,OAAO,CAAC,iBAAiB,CAIvB;gBAGA,IAAI,EAAE,WAAW,EACjB,IAAI,EAAE,SAAS,EACf,MAAM,EAAE;QACN,aAAa,EAAE,MAAM,CAAC;QACtB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,KAAK,CAAC,EAAE,UAAU,CAAC;KACpB;IAWH,MAAM,CAAC,MAAM,CAAC,IAAI,GAAE,WAAgB,GAAG,WAAW;IAIlD,WAAW,IAAI,SAAS;IAIlB,GAAG,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,GAAG,kBAAkB,CAAC;IASrF,MAAM,CACV,UAAU,EAAE,mBAAmB,EAC/B,KAAK,CAAC,EAAE,OAAO,EACf,OAAO,CAAC,EAAE,UAAU,GACnB,OAAO,CAAC,UAAU,GAAG,kBAAkB,CAAC;IAO3C,OAAO,CAAC,cAAc;IAqBtB,OAAO,CAAC,cAAc;IAWtB,OAAO,CAAC,UAAU;CAiGnB;AAED;;;;;;;;GAQG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAc;IACnC,OAAO,CAAC,KAAK,CAAwB;IACrC,OAAO,CAAC,cAAc,CAAqB;IAC3C,OAAO,CAAC,eAAe,CAAqB;IAC5C,OAAO,CAAC,MAAM,CAAyB;gBAE3B,IAAI,EAAE,WAAW;IAI7B;;;OAGG;IACH,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI;IAQ/B;;;OAGG;IACH,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IAKtB;;;OAGG;IACH,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAK3B;;;OAGG;IACH,KAAK,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAK9B,KAAK,IAAI,IAAI;CAWd"}
+{"version":3,"file":"Loop.d.ts","sourceRoot":"","sources":["../../../src/core-flow/Loop.ts"],"names":[],"mappings":"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"}

package/dist/types/core-flow/Parallel.d.ts

@@ -10,7 +10,8 @@
  *          composition.fork_start / branch_complete / merge_end
  *          (via compositionRecorder).
  */
-import { type FlowChart, type FlowchartCheckpoint, type RunOptions } from 'footprintjs';
+import { type FlowchartCheckpoint, type RunOptions, type StructureRecorder } from 'footprintjs';
+import type { GroupMetadata, GroupTranslator } from '../core/translator.js';
 import type { RunnerPauseOutcome } from '../core/pause.js';
 import type { LLMProvider } from '../adapters/types.js';
 import type { Runner } from '../core/runner.js';
@@ -18,6 +19,36 @@ import { RunnerBase } from '../core/RunnerBase.js';
 export interface ParallelOptions {
     readonly name?: string;
     readonly id?: string;
+    /**
+     * Optional build-time recorders passed through to footprintjs's
+     * `flowChart()` factory. Each recorder observes per-node build
+     * events (`onStageAdded` / `onSubflowMounted` / etc.) for this
+     * composition's internal chart (Seed + each branch mount + Merge).
+     *
+     * Cascade: each branch runner attaches its OWN recorders at its
+     * own construction time. footprintjs does NOT propagate
+     * StructureRecorders into mounted subflows — so for full coverage,
+     * attach the same recorders to every nested composition. See the
+     * core-flow README's "StructureRecorder cascade" section.
+     *
+     * When omitted, no build-time observation is wired up.
+     */
+    readonly structureRecorders?: readonly StructureRecorder[];
+    /**
+     * Optional per-COMPOSITION translator (UI-agnostic). When attached,
+     * `runner.getUIGroup()` invokes it with the Parallel's
+     * `GroupMetadata` (kind, id, name, branches list, merge strategy)
+     * and returns whatever shape the translator produces.
+     *
+     * Independent of `structureRecorders` — those observe per-node spec
+     * events, this shapes whole-composition UI groups. Common case is to
+     * thread the SAME `GroupTranslator` reference through every nested
+     * composition so `member.uiGroup` is populated recursively; L1c
+     * per-method overrides add finer control.
+     *
+     * When omitted, `getUIGroup()` returns `undefined`.
+     */
+    readonly groupTranslator?: GroupTranslator;
 }
 export interface ParallelInput {
     readonly message: string;
@@ -56,6 +87,26 @@ interface BranchEntry {
     readonly id: string;
     readonly name: string;
     readonly runner: BranchChild;
+    /**
+     * Optional per-method translator override for THIS branch only.
+     * When set, the branch's `member.uiGroup` is produced by invoking
+     * this translator against the runner's own `GroupMetadata`, instead
+     * of calling `branch.runner.getUIGroup()` (which would use the
+     * runner's own constructor-level translator).
+     */
+    readonly groupTranslator?: GroupTranslator;
+}
+/**
+ * Options bag accepted by `ParallelBuilder.branch()` for per-method
+ * overrides. Backwards-compatible with the legacy
+ * `.branch(id, runner, name?)` signature: when the third arg is a
+ * string it's still treated as `name`.
+ */
+export interface ParallelBranchOptions {
+    /** Human-friendly name for this branch. Default: the branch id. */
+    readonly name?: string;
+    /** Per-method translator override. See `BranchEntry.groupTranslator`. */
+    readonly groupTranslator?: GroupTranslator;
 }
 type MergeStrategy = {
     readonly kind: 'fn';
@@ -72,13 +123,49 @@ export declare class Parallel extends RunnerBase<ParallelInput, ParallelOutput>
     readonly id: string;
     private readonly branches;
     private readonly merge;
+    private readonly opts;
     private currentRunContext;
+    /**
+     * Per-branch first-error messages captured during the current run.
+     *
+     * Filled by an internal CombinedRecorder attached in `createExecutor()`
+     * that observes footprintjs `FlowErrorEvent`s. Errors are keyed by the
+     * branch id (the first segment of `traversalContext.subflowPath`); only
+     * the first error per branch is kept so the surface mirrors the wrapper
+     * `try/catch` semantics that preceded the v0.x architectural refactor.
+     *
+     * Read by the Merge stage to populate strict-mode error messages and
+     * tolerant-mode `BranchOutcome.error` strings. Cleared at the start of
+     * every `run()` / `resume()`.
+     */
+    private readonly branchErrors;
     constructor(opts: ParallelOptions, branches: readonly BranchEntry[], merge: MergeStrategy);
     static create(opts?: ParallelOptions): ParallelBuilder;
-    toFlowChart(): FlowChart;
+    protected getGroupTranslator(): GroupTranslator | undefined;
+    /**
+     * Build the Parallel's `GroupMetadata` — kind `'Parallel'`, with one
+     * `GroupMember` per branch. Each member exposes its `runner` plus
+     * the runner's own `getUIGroup()` output (when the consumer
+     * threaded the same translator through that branch's construction).
+     */
+    protected buildUIGroupMetadata(): GroupMetadata;
     run(input: ParallelInput, options?: RunOptions): Promise<ParallelOutput | RunnerPauseOutcome>;
     resume(checkpoint: FlowchartCheckpoint, input?: unknown, options?: RunOptions): Promise<ParallelOutput | RunnerPauseOutcome>;
     private createExecutor;
+    /**
+     * Build the internal recorder that captures first-error-per-branch.
+     *
+     * footprintjs's `SubflowExecutor` swallows subflow errors into
+     * `parentContext.debug.addError(...)` and skips the `outputMapper`,
+     * so the failed branch's error message never lands in parent scope.
+     * To preserve the per-branch error surface the wrapper-based design
+     * provided, we observe `FlowRecorder.onError` and correlate by the
+     * first segment of `traversalContext.subflowPath`.
+     *
+     * Only the FIRST error per branch is kept. Errors fired outside any
+     * branch (e.g., a Merge-stage error) are ignored.
+     */
+    private makeBranchErrorRecorder;
     private finalizeResult;
     private buildChart;
 }
@@ -89,8 +176,16 @@ export declare class ParallelBuilder {
     private merge;
     private readonly seenIds;
     constructor(opts: ParallelOptions);
-    /** Add a branch. All branches run concurrently with the same input. */
-    branch(id: string, runner: BranchChild, name?: string): this;
+    /**
+     * Add a branch. All branches run concurrently with the same input.
+     *
+     * Third arg accepts EITHER a legacy bare `name` string (back-compat
+     * with pre-L1c callers) OR a `ParallelBranchOptions` bag containing
+     * `name` and/or a per-method `groupTranslator` override. The
+     * override applies ONLY to this branch's `member.uiGroup` and does
+     * not affect any other branch or the runner's own translator.
+     */
+    branch(id: string, runner: BranchChild, nameOrOpts?: string | ParallelBranchOptions): this;
     /**
      * Merge branch results via a pure function.
      * `fn` receives `{ [branchId]: string }` and returns the merged string.

package/dist/types/core-flow/Parallel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Parallel.d.ts","sourceRoot":"","sources":["../../../src/core-flow/Parallel.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Parallel.d.ts","sourceRoot":"","sources":["../../../src/core-flow/Parallel.ts"],"names":[],"mappings":"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"}

package/dist/types/core-flow/Sequence.d.ts

@@ -9,7 +9,9 @@
  *          any two steps.
  * Emits:   agentfootprint.composition.enter / exit (via compositionRecorder).
  */
-import { type FlowChart, type FlowchartCheckpoint, type RunOptions } from 'footprintjs';
+import { type FlowchartCheckpoint, type RunOptions } from 'footprintjs';
+import type { StructureRecorder } from 'footprintjs';
+import type { GroupMetadata, GroupTranslator } from '../core/translator.js';
 import type { RunnerPauseOutcome } from '../core/pause.js';
 import type { Runner } from '../core/runner.js';
 import { RunnerBase } from '../core/RunnerBase.js';
@@ -18,6 +20,29 @@ export interface SequenceOptions {
     readonly name?: string;
     /** Stable id used for topology + events. Default: 'sequence'. */
     readonly id?: string;
+    /**
+     * Optional build-time recorders passed through to footprintjs's
+     * `flowChart()` factory. Each recorder observes per-node build
+     * events (`onStageAdded` / `onSubflowMounted` / etc.) for this
+     * composition's internal chart (Seed + each step mount + Finalize).
+     *
+     * Cascade: each step runner attaches its OWN recorders at its own
+     * construction time. footprintjs does NOT propagate StructureRecorders
+     * into mounted subflows — attach the same recorders to every nested
+     * composition for full coverage.
+     *
+     * When omitted, no build-time observation is wired up.
+     */
+    readonly structureRecorders?: readonly StructureRecorder[];
+    /**
+     * Optional per-COMPOSITION translator (UI-agnostic). See
+     * `core/translator.ts`. When attached, `runner.getUIGroup()` invokes
+     * it with the Sequence's `GroupMetadata` (kind `'Sequence'`, id,
+     * name, ordered steps, no extras) and returns whatever shape the
+     * translator produces. When omitted, `getUIGroup()` returns
+     * `undefined`.
+     */
+    readonly groupTranslator?: GroupTranslator;
 }
 export interface SequenceInput {
     readonly message: string;
@@ -33,15 +58,32 @@ interface StepEntry {
     readonly mapFromPrev: (prev: string) => {
         message: string;
     };
+    /** Optional per-method translator override for THIS step only. */
+    readonly groupTranslator?: GroupTranslator;
+}
+/**
+ * Options bag accepted by `SequenceBuilder.step()` for per-method
+ * overrides. Backwards-compatible — when omitted the legacy two-arg
+ * `.step(id, runner)` signature still works.
+ */
+export interface SequenceStepOptions {
+    /** Per-method translator override. See `StepEntry.groupTranslator`. */
+    readonly groupTranslator?: GroupTranslator;
 }
 export declare class Sequence extends RunnerBase<SequenceInput, SequenceOutput> {
     readonly name: string;
     readonly id: string;
     private readonly steps;
+    private readonly opts;
     private currentRunContext;
     constructor(opts: SequenceOptions, steps: readonly StepEntry[]);
     static create(opts?: SequenceOptions): SequenceBuilder;
-    toFlowChart(): FlowChart;
+    protected getGroupTranslator(): GroupTranslator | undefined;
+    /** Sequence is a flat ordered list of steps. One member per step,
+     *  preserving definition order so the consumer can render them
+     *  linearly (default Lens UX). Per-method overrides (L1c) take
+     *  precedence over the step runner's own translator. */
+    protected buildUIGroupMetadata(): GroupMetadata;
     run(input: SequenceInput, options?: RunOptions): Promise<SequenceOutput | RunnerPauseOutcome>;
     resume(checkpoint: FlowchartCheckpoint, input?: unknown, options?: RunOptions): Promise<SequenceOutput | RunnerPauseOutcome>;
     private createExecutor;
@@ -69,8 +111,12 @@ export declare class SequenceBuilder {
      * First step receives the Sequence input; subsequent steps receive the
      * previous step's output (via the default string-chain mapper, or via
      * the transformer set by a preceding `.pipeVia(fn)` call).
+     *
+     * Optional third arg `opts.groupTranslator` overrides the runner's
+     * own constructor-level translator for THIS step only — only its
+     * `member.uiGroup` flips to the override's output.
      */
-    step(id: string, runner: StepChild): this;
+    step(id: string, runner: StepChild, opts?: SequenceStepOptions): this;
     /**
      * Transform the previous step's string output before it reaches the
      * next step. Consumed once by the next `.step()` call. Default

package/dist/types/core-flow/Sequence.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Sequence.d.ts","sourceRoot":"","sources":["../../../src/core-flow/Sequence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAGL,KAAK,SAAS,EACd,KAAK,mBAAmB,EACxB,KAAK,UAAU,EAEhB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAa,MAAM,uBAAuB,CAAC;AAQ9D,MAAM,WAAW,eAAe;IAC9B,sEAAsE;IACtE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC;AAKpC,KAAK,SAAS,GAAG,MAAM,CAAC;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,EAAE,MAAM,CAAC,CAAC;AAErD,UAAU,SAAS;IACjB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,+CAA+C;IAC/C,QAAQ,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7D;AAMD,qBAAa,QAAS,SAAQ,UAAU,CAAC,aAAa,EAAE,cAAc,CAAC;IACrE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAuB;IAE7C,OAAO,CAAC,iBAAiB,CAIvB;gBAEU,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,SAAS,SAAS,EAAE;IAU9D,MAAM,CAAC,MAAM,CAAC,IAAI,GAAE,eAAoB,GAAG,eAAe;IAI1D,WAAW,IAAI,SAAS;IAIlB,GAAG,CACP,KAAK,EAAE,aAAa,EACpB,OAAO,CAAC,EAAE,UAAU,GACnB,OAAO,CAAC,cAAc,GAAG,kBAAkB,CAAC;IASzC,MAAM,CACV,UAAU,EAAE,mBAAmB,EAC/B,KAAK,CAAC,EAAE,OAAO,EACf,OAAO,CAAC,EAAE,UAAU,GACnB,OAAO,CAAC,cAAc,GAAG,kBAAkB,CAAC;IAO/C,OAAO,CAAC,cAAc;IAqBtB,OAAO,CAAC,cAAc;IAWtB,OAAO,CAAC,UAAU;CAiEnB;AAED;;;;;;;;GAQG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAkB;IACvC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAmB;IACzC,2EAA2E;IAC3E,OAAO,CAAC,WAAW,CAAC,CAAwC;IAC5D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;gBAEjC,IAAI,EAAE,eAAe;IAIjC;;;;;OAKG;IACH,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI;IAWzC;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAKxD,KAAK,IAAI,QAAQ;CAQlB"}
+{"version":3,"file":"Sequence.d.ts","sourceRoot":"","sources":["../../../src/core-flow/Sequence.ts"],"names":[],"mappings":"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"}