lastlight-workflow-engine 0.1.0

package/dist/core/templates.js

@@ -0,0 +1,127 @@
+/**
+ * Minimal template engine for workflow prompt files.
+ *
+ * Supports:
+ *   {{varName}}            — simple variable substitution
+ *   {{slugify varName}}    — slugify helper applied to a variable
+ *   {{branchUrl file}}     — generate a GitHub branch URL for a file in issueDir
+ *   {{#if varName}}...{{/if}} — conditional blocks (no nesting, truthy check)
+ */
+export function slugify(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "")
+        .slice(0, 40);
+}
+/**
+ * Render a template string with the given context.
+ * Processes: {{#if}}, {{slugify}}, {{branchUrl}}, {{varName}}.
+ */
+export function renderTemplate(template, ctx) {
+    let result = template;
+    // 0. Phase output substitution: ${phaseName.output} → phaseOutputs[phaseName]
+    if (ctx.phaseOutputs) {
+        const phaseOutputs = ctx.phaseOutputs;
+        result = result.replace(/\$\{(\w+)\.output\}/g, (_match, phaseName) => {
+            const val = phaseOutputs[phaseName];
+            if (val === undefined || val === null)
+                return "";
+            return typeof val === "string" ? val : String(val?.output ?? JSON.stringify(val));
+        });
+    }
+    // Walk a dotted key like `scratch.socratic.ready` through ctx, falling
+    // back to ctx.phaseOutputs for the first segment. Returns undefined on
+    // any missing intermediate.
+    const walkKey = (key) => {
+        const parts = key.split(".");
+        if (parts.length === 1) {
+            const val = ctx[key];
+            if (val !== undefined && val !== null)
+                return val;
+            return ctx.phaseOutputs?.[key];
+        }
+        let cur = ctx[parts[0]];
+        if (cur === undefined || cur === null)
+            cur = ctx.phaseOutputs?.[parts[0]];
+        for (let i = 1; i < parts.length; i++) {
+            if (cur === null || typeof cur !== "object")
+                return undefined;
+            cur = cur[parts[i]];
+        }
+        return cur;
+    };
+    // 1. Conditional blocks: {{#if varName}}...{{/if}} (supports dot notation).
+    //    Key segments allow hyphens so phase/model keys like `pr-fix` resolve
+    //    (e.g. {{models.pr-fix}}); \w alone would leave them unrendered.
+    result = result.replace(/\{\{#if\s+(!?)([\w-]+(?:\.[\w-]+)*)\}\}([\s\S]*?)\{\{\/if\}\}/g, (_match, negate, varName, body) => {
+        const val = walkKey(varName);
+        // Truthy: non-empty string, non-zero number, non-empty array, true boolean
+        const truthy = val !== undefined &&
+            val !== null &&
+            val !== "" &&
+            val !== false &&
+            val !== 0 &&
+            !(Array.isArray(val) && val.length === 0);
+        return (negate ? !truthy : truthy) ? body : "";
+    });
+    // 2. Slugify helper: {{slugify varName}}
+    result = result.replace(/\{\{slugify\s+(\w+)\}\}/g, (_match, varName) => {
+        const val = ctx[varName];
+        if (val === undefined || val === null)
+            return "";
+        return slugify(String(val));
+    });
+    // 3. Branch URL helper: {{branchUrl filename}}
+    // Generates: https://github.com/{owner}/{repo}/blob/{branch}/.lastlight/issue-{N}/{file}
+    result = result.replace(/\{\{branchUrl\s+(\S+)\}\}/g, (_match, file) => {
+        const encoded = encodeURIComponent(ctx.branch);
+        return `https://github.com/${ctx.owner}/${ctx.repo}/blob/${encoded}/${ctx.issueDir}/${file}`;
+    });
+    // 3b. Artifact URL helper: {{artifactUrl filename}} — mode-aware link to a
+    // handoff doc. In repo mode it's identical to {{branchUrl}} (the doc is
+    // committed on the branch). In server mode the doc lives on the Last Light
+    // host, so the link points at the admin dashboard's Artifacts view. Falls
+    // back to the branch URL when no publicUrl is configured so a server-mode
+    // deploy without PUBLIC_URL still produces a usable (if GitHub-less) link.
+    result = result.replace(/\{\{artifactUrl\s+(\S+)\}\}/g, (_match, file) => {
+        const branchHref = `https://github.com/${ctx.owner}/${ctx.repo}/blob/${encodeURIComponent(ctx.branch)}/${ctx.issueDir}/${file}`;
+        if (!ctx.externalizeArtifacts)
+            return branchHref;
+        if (!ctx.publicUrl)
+            return branchHref;
+        const issueKey = ctx.issueDir.replace(/^\.lastlight\//, "");
+        const base = String(ctx.publicUrl).replace(/\/+$/, "");
+        const q = `repo=${encodeURIComponent(`${ctx.owner}/${ctx.repo}`)}` +
+            `&key=${encodeURIComponent(issueKey)}` +
+            `&doc=${encodeURIComponent(file)}`;
+        return `${base}/admin/?tab=artifacts&${q}`;
+    });
+    // 3c. Approval URL helper: {{approvalUrl}} — deep link to the focused
+    // approval view for the gate currently being rendered. `approvalId` is
+    // injected into the message context by PhaseExecutor.pauseForApproval, and
+    // `publicUrl` is the dashboard base. Renders empty when either is absent
+    // (e.g. no PUBLIC_URL configured) so the rest of the gate message still
+    // posts cleanly.
+    result = result.replace(/\{\{approvalUrl\}\}/g, () => {
+        if (!ctx.publicUrl || !ctx.approvalId)
+            return "";
+        const base = String(ctx.publicUrl).replace(/\/+$/, "");
+        return `${base}/admin/?approval=${encodeURIComponent(String(ctx.approvalId))}`;
+    });
+    // 4. Simple variable substitution: {{varName}} and {{a.b.c...}}.
+    //    Dotted access first checks top-level ctx, then falls back to
+    //    ctx.phaseOutputs[parent] for the first segment so YAML phases can
+    //    emit structured output via `output_var` and downstream prompts can
+    //    read it directly — and the socratic explore loop can read
+    //    {{scratch.socratic.qa}}.
+    //    Key segments allow hyphens (e.g. {{models.pr-fix}}) — see #1.
+    result = result.replace(/\{\{([\w-]+(?:\.[\w-]+)*)\}\}/g, (_match, key) => {
+        const val = walkKey(key);
+        if (val === undefined || val === null)
+            return "";
+        return typeof val === "object" ? JSON.stringify(val) : String(val);
+    });
+    return result;
+}
+//# sourceMappingURL=templates.js.map

package/dist/core/templates.js.map

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

package/dist/core/types.d.ts

@@ -0,0 +1,261 @@
+/**
+ * Shared vocabulary for the workflow engine — the concrete data types that flow
+ * through phase execution: the agent config/result, the git-sandbox access
+ * descriptor, and the deterministic command spec.
+ *
+ * These moved here (from `src/engine/github/profiles.ts`,
+ * `src/config/config.ts`, and `src/engine/executors/orchestrator.ts`) so the
+ * engine owns its own vocabulary and no longer type-depends on the app layer.
+ * The app-side modules re-export them from here for import-path stability.
+ *
+ * Engine-internal: this module imports nothing from `../engine`, `../state`,
+ * `../config`, etc. — the dependency-cruiser boundary gate enforces that.
+ */
+/** Workflow sandbox backend. */
+export type SandboxBackend = "gondolin" | "docker" | "smol" | "none";
+/** Where build handoff docs live for a run. */
+export type BuildAssetsLocation = "repo" | "server";
+/** OTEL forwarding + redaction config threaded into a phase run. */
+export interface OtelConfig {
+    enabled: boolean;
+    serviceName: string;
+    includeContent: boolean;
+    forwardToSandbox: boolean;
+    strict: boolean;
+    collectorHosts: string[];
+}
+/**
+ * Configuration for an agent execution.
+ */
+export interface ExecutorConfig {
+    /** Working directory for the agent (used by the no-sandbox path). */
+    cwd?: string;
+    /** Maximum conversation turns. Unused by agentic-pi; kept for API stability. */
+    maxTurns?: number;
+    /** Model id (e.g. "anthropic/claude-sonnet-4-6"). */
+    model?: string;
+    /**
+     * Pi thinking level: `off | minimal | low | medium | high | xhigh`.
+     * Forwarded to agentic-pi as the `thinking` option. When omitted,
+     * agentic-pi uses the model's default.
+     */
+    variant?: string;
+    /** Path to agent context directory. */
+    agentContextDir?: string;
+    /** Directory for persistent state. */
+    stateDir?: string;
+    /** Directory for agent sandboxes (cloned repos). */
+    sandboxDir?: string;
+    /**
+     * Run the agent in a `<workspace>/<repoSubdir>/` SUBDIRECTORY instead of the
+     * workspace root, WITHOUT going through the token-gated `prePopulate`/clone
+     * path. For callers that pre-seed the repo themselves (e.g. the evals harness
+     * in static-token mode): it reproduces production's nested layout — the repo
+     * checkout is a child dir, while `AGENTS.md`/`.lastlight-skills/` stay at the
+     * workspace root, siblings outside the repo's git tree. Ignored when a real
+     * `prePopulate` clone runs (that already nests into `<repo>/`). Use backend
+     * `none` so skills stage at the root rather than under the repo.
+     */
+    repoSubdir?: string;
+    /** Where the shim writes dashboard envelope jsonl. */
+    sessionsDir?: string;
+    /** Workflow sandbox backend (overrides config-level default). */
+    sandbox?: SandboxBackend;
+    /**
+     * Which docker sandbox image this phase runs in: `"qa"` selects the
+     * browser-QA image (Playwright + Chromium), anything else the lean default.
+     * Overlaid per-phase from `sandbox_image:` by `phaseConfigFor`; only acted on
+     * by the docker path.
+     */
+    sandboxImage?: "default" | "qa";
+    /**
+     * Where build handoff docs live for this run:
+     *   - "repo" (default): the agent writes/commits `.lastlight/<issueKey>/`
+     *     into the target repo branch; the stage-in/harvest seam is skipped.
+     *   - "server": docs are staged in from / harvested back to the server store
+     *     under `buildAssetsDir`, never committed. Set from the runtime config.
+     */
+    buildAssets?: BuildAssetsLocation;
+    /** Filesystem root for the server-mode build-assets store (when buildAssets === "server"). */
+    buildAssetsDir?: string;
+    /**
+     * Server-mode artifact identity for this run. Used by the stage-in/harvest
+     * seam to locate the run's docs in the store at
+     * `<buildAssetsDir>/<owner>/<repo>/<issueKey>/`. Set per run from simple.ts.
+     */
+    buildAssetsKey?: {
+        owner: string;
+        repo: string;
+        issueKey: string;
+    };
+    /**
+     * Bypass the HTTP egress allowlist for this phase. When true:
+     *   - gondolin: `allowedHttpHosts: ["*"]` is passed to agentic-pi.
+     *   - docker:   the sandbox container uses the open CoreDNS/nginx
+     *               egress-firewall pair instead of the strict one.
+     *
+     * Default false. Set via the `unrestricted_egress` field on a workflow
+     * phase — used for phases that need broad web access (e.g. an explore
+     * phase that searches third-party documentation).
+     */
+    unrestrictedEgress?: boolean;
+    /**
+     * Enable agentic-pi's web-search extension (`web_search` / `web_fetch`
+     * tools). Default false. agentic-pi auto-enables web search whenever a
+     * provider env var (`TAVILY_API_KEY`, `BRAVE_SEARCH_API_KEY`,
+     * `EXA_API_KEY`) is present, so we pass an explicit `false` downstream
+     * to suppress auto-enable for non-explore workflows.
+     */
+    webSearch?: boolean;
+    /**
+     * Force a specific web-search provider. When unset, agentic-pi picks
+     * one based on which API key env var is present (Tavily > Exa > Brave).
+     */
+    webSearchProvider?: "tavily" | "brave" | "exa";
+    /**
+     * Override the GitHub REST API base URL for agentic-pi's built-in
+     * `github_*` tools (Octokit `baseUrl`). Test/eval escape hatch only:
+     * the eval harness (`evals/`) points this at a local fake GitHub server so
+     * a real workflow runs unchanged with its GitHub calls mocked. Production
+     * leaves it unset → `https://api.github.com`. Only honoured by the
+     * in-process (`none`/`gondolin`) path.
+     */
+    githubApiBaseUrl?: string;
+    /** Controls OTEL env forwarding and PI event redaction for workflow phase runs. */
+    otel?: OtelConfig;
+    telemetry?: {
+        workflowName?: string;
+        phaseName?: string;
+        triggerId?: string;
+        workflowRunId?: string;
+    };
+    /**
+     * Absolute host paths to skill directories (each containing SKILL.md
+     * plus optional scripts/, references/, assets/). Staged into a per-phase
+     * bundle at `.lastlight-skills/<phaseName>/<basename>/` before the agent
+     * runs — gondolin/none via symlink, docker via copy — and passed to pi
+     * explicitly (`--skill` in docker, `skillPaths` in-process). cwd stays the
+     * repo; the bundle is a workspace-root sibling of the repo (never committed)
+     * on docker/none, and under the repo + local `.git/info/exclude` on gondolin
+     * (which mounts only cwd). Keyed per phase so parallel phases stay isolated.
+     * Resolved by `phaseConfigFor` in the workflow runner from the phase's
+     * `skill:`/`skills:` field.
+     */
+    skillPaths?: string[];
+}
+/**
+ * Normalized status of one agentic-pi extension for a single run.
+ */
+export interface ExtensionStatus {
+    /** "configured" when the extension loaded, "skipped" otherwise. */
+    status: string;
+    /** file-search only: "override" | "tools-only" | "tools-and-ui". */
+    mode?: string;
+    /** web-search only: the resolved search provider. */
+    provider?: string;
+    /** Number of tools the extension registered. */
+    toolCount?: number;
+    /** Why it was skipped (e.g. "no-credentials", "resolve-failed"). */
+    reason?: string;
+}
+export type ExtensionStatusMap = Record<string, ExtensionStatus>;
+/**
+ * One skill agentic-pi discovered for a run, flattened from the
+ * `skills_status` event's `skills[]`. Mirrors agentic-pi's `SkillSummary`.
+ */
+export interface SkillSummary {
+    /** Skill name (from SKILL.md frontmatter). */
+    name: string;
+    /** Absolute path to the skill's SKILL.md. */
+    source: string;
+    /**
+     * Whether the model can auto-invoke it. False when the skill set
+     * `disable-model-invocation: true`.
+     */
+    modelInvocable: boolean;
+}
+/**
+ * Normalized status of agentic-pi's skill discovery for a single run.
+ */
+export interface SkillsStatus {
+    status: string;
+    discovered: number;
+    skills: SkillSummary[];
+    mappedPaths: string[];
+    noSkills: boolean;
+}
+/**
+ * Result from an agent execution.
+ */
+export interface ExecutionResult {
+    success: boolean;
+    output: string;
+    turns: number;
+    error?: string;
+    durationMs: number;
+    /** Session id captured from the runtime's stream. */
+    sessionId?: string;
+    /** Total USD cost reported by the runtime. Zero under OAuth/subscription auth. */
+    costUsd?: number;
+    /** Tokens billed as fresh input (no cache hit). */
+    inputTokens?: number;
+    /** Tokens that triggered a cache write. */
+    cacheCreationInputTokens?: number;
+    /** Tokens served from prompt cache (heavily discounted). */
+    cacheReadInputTokens?: number;
+    /** Output tokens generated by the model. */
+    outputTokens?: number;
+    /** API-side duration (excludes orchestrator overhead). */
+    apiDurationMs?: number;
+    /** Mapped stop reason ("success" / "error_*" / etc.). */
+    stopReason?: string;
+    /** Which agentic-pi extensions were active for this run, keyed by name. */
+    extensions?: ExtensionStatusMap;
+    /** Skill-loading status captured from agentic-pi's `skills_status` event. */
+    skills?: SkillsStatus;
+}
+export type GitAccessProfile = "read" | "issues-write" | "review-write" | "repo-write";
+export interface GitSandboxAccess {
+    owner: string;
+    repo: string;
+    profile: GitAccessProfile;
+    /**
+     * When true, sandbox MCP can mint/refresh tokens using the app PEM.
+     * Leave false for lower-trust runs to keep private key material inaccessible.
+     */
+    allowMcpAppAuth?: boolean;
+    /**
+     * When set, the harness pre-clones the repo at this branch into the
+     * task's workspace before the sandbox container starts.
+     */
+    prePopulateBranch?: string;
+    /**
+     * The owning workflow run id. Stamped into a `<workDir>/.lastlight-run`
+     * marker by the pre-clone so a reused per-PR workspace can tell "next phase
+     * of the same run" from "a fresh run reusing an old PR dir".
+     */
+    runId?: string;
+    /**
+     * Clone shallowly (`--depth 1 --single-branch`). Set for read-only
+     * workflows that never need history.
+     */
+    shallow?: boolean;
+    /**
+     * Recreate the workspace from the **default branch** on a fresh run instead
+     * of reusing/refreshing an existing feature-branch checkout (issue #153).
+     */
+    recreateFromBase?: boolean;
+}
+/**
+ * The spec for a deterministic `type: bash` / `type: script` phase — a shell
+ * command or an inline script with a runtime.
+ */
+export type CommandSpec = {
+    kind: "bash";
+    command: string;
+} | {
+    kind: "script";
+    script: string;
+    runtime: "js" | "ts" | "python";
+    name: string;
+};

package/dist/core/types.js

@@ -0,0 +1,15 @@
+/**
+ * Shared vocabulary for the workflow engine — the concrete data types that flow
+ * through phase execution: the agent config/result, the git-sandbox access
+ * descriptor, and the deterministic command spec.
+ *
+ * These moved here (from `src/engine/github/profiles.ts`,
+ * `src/config/config.ts`, and `src/engine/executors/orchestrator.ts`) so the
+ * engine owns its own vocabulary and no longer type-depends on the app layer.
+ * The app-side modules re-export them from here for import-path stability.
+ *
+ * Engine-internal: this module imports nothing from `../engine`, `../state`,
+ * `../config`, etc. — the dependency-cruiser boundary gate enforces that.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/core/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/dist/core/verdict.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The single parser for a reviewer phase's verdict.
+ *
+ * A reviewer agent is asked to end its output with a `VERDICT:` marker line —
+ * either `VERDICT: APPROVED` or `VERDICT: REQUEST_CHANGES`. When that marker is
+ * present we trust it. When it's absent we fall back to a fragile heuristic
+ * (preserved here exactly as both runner sites had it): treat the output as
+ * approved only when it does NOT mention `REQUEST_CHANGES` and DOES start with
+ * `APPROVED`. `viaFallback` lets callers warn when the marker was missing.
+ *
+ * Hardening the fallback is deliberately out of scope — this parser is
+ * behaviour-neutral on verdict semantics.
+ */
+export type ReviewerVerdict = "APPROVED" | "REQUEST_CHANGES";
+export interface ParsedVerdict {
+    verdict: ReviewerVerdict;
+    viaFallback: boolean;
+}
+export declare function parseReviewerVerdict(output: string): ParsedVerdict;

package/dist/core/verdict.js

@@ -0,0 +1,30 @@
+/**
+ * The single parser for a reviewer phase's verdict.
+ *
+ * A reviewer agent is asked to end its output with a `VERDICT:` marker line —
+ * either `VERDICT: APPROVED` or `VERDICT: REQUEST_CHANGES`. When that marker is
+ * present we trust it. When it's absent we fall back to a fragile heuristic
+ * (preserved here exactly as both runner sites had it): treat the output as
+ * approved only when it does NOT mention `REQUEST_CHANGES` and DOES start with
+ * `APPROVED`. `viaFallback` lets callers warn when the marker was missing.
+ *
+ * Hardening the fallback is deliberately out of scope — this parser is
+ * behaviour-neutral on verdict semantics.
+ */
+export function parseReviewerVerdict(output) {
+    const marker = output.match(/^\s*VERDICT:\s*(APPROVED|REQUEST_CHANGES)\s*$/im);
+    if (marker) {
+        return {
+            verdict: marker[1].toUpperCase() === "APPROVED" ? "APPROVED" : "REQUEST_CHANGES",
+            viaFallback: false,
+        };
+    }
+    const upper = output.toUpperCase();
+    const hasRequestChanges = /\bREQUEST_CHANGES\b/.test(upper);
+    const isApproved = !hasRequestChanges && /^APPROVED\b/.test(upper);
+    return {
+        verdict: isApproved ? "APPROVED" : "REQUEST_CHANGES",
+        viaFallback: true,
+    };
+}
+//# sourceMappingURL=verdict.js.map

package/dist/core/verdict.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verdict.js","sourceRoot":"","sources":["../../src/core/verdict.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AASH,MAAM,UAAU,oBAAoB,CAAC,MAAc;IACjD,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,iDAAiD,CAAC,CAAC;IAC/E,IAAI,MAAM,EAAE,CAAC;QACX,OAAO;YACL,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,KAAK,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,iBAAiB;YAChF,WAAW,EAAE,KAAK;SACnB,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW,EAAE,CAAC;IACnC,MAAM,iBAAiB,GAAG,qBAAqB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC5D,MAAM,UAAU,GAAG,CAAC,iBAAiB,IAAI,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACnE,OAAO;QACL,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,iBAAiB;QACpD,WAAW,EAAE,IAAI;KAClB,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `lastlight-workflow-engine` — the port-driven workflow engine extracted from
+ * Last Light. Domain-agnostic (zod + node built-ins only); the embedding app
+ * supplies the agent/asset/liveness/telemetry seams via {@link EnginePorts}.
+ *
+ * The `test-support` subpath (`lastlight-workflow-engine/test-support`) ships
+ * in-memory fakes; it stays a separate entry so the fakes never enter a
+ * consumer's production import graph.
+ */
+export * from "./core/types.js";
+export * from "./core/schema.js";
+export * from "./core/templates.js";
+export * from "./core/dag.js";
+export * from "./core/verdict.js";
+export * from "./core/phase-ref.js";
+export * from "./core/loop-eval.js";
+export * from "./ports/ports.js";
+export { PhaseExecutor, isTerminated, isSoftOutcome, buildPhasePrompt, phaseConfigFor, runPhase, runCommandPhase, } from "./core/phase-executor.js";
+export type { PhaseRunContext } from "./core/phase-executor.js";
+export { runWorkflowCore } from "./core/scheduler.js";
+export type { SchedulerDeps, HostCapabilities } from "./core/scheduler.js";

package/dist/index.js

@@ -0,0 +1,24 @@
+/**
+ * `lastlight-workflow-engine` — the port-driven workflow engine extracted from
+ * Last Light. Domain-agnostic (zod + node built-ins only); the embedding app
+ * supplies the agent/asset/liveness/telemetry seams via {@link EnginePorts}.
+ *
+ * The `test-support` subpath (`lastlight-workflow-engine/test-support`) ships
+ * in-memory fakes; it stays a separate entry so the fakes never enter a
+ * consumer's production import graph.
+ */
+// Core leaves + vocabulary (no cross-overlap → safe star exports).
+export * from "./core/types.js";
+export * from "./core/schema.js";
+export * from "./core/templates.js";
+export * from "./core/dag.js";
+export * from "./core/verdict.js";
+export * from "./core/phase-ref.js";
+export * from "./core/loop-eval.js";
+// Ports (interfaces + engine result vocabulary).
+export * from "./ports/ports.js";
+// The executor + scheduler — explicit named exports so their re-exported port
+// types don't collide with the `./ports/ports.js` star export above.
+export { PhaseExecutor, isTerminated, isSoftOutcome, buildPhasePrompt, phaseConfigFor, runPhase, runCommandPhase, } from "./core/phase-executor.js";
+export { runWorkflowCore } from "./core/scheduler.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,mEAAmE;AACnE,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AAEpC,iDAAiD;AACjD,cAAc,kBAAkB,CAAC;AAEjC,8EAA8E;AAC9E,qEAAqE;AACrE,OAAO,EACL,aAAa,EACb,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,cAAc,EACd,QAAQ,EACR,eAAe,GAChB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC"}