@methodts/runtime 0.1.0

package/dist/ports/continuation-envelope-cross-app.test.js

@@ -0,0 +1,95 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Continuation envelope — PRD-067 cross-app extension tests.
+ *
+ * Gates:
+ *   - G-ENVELOPE-BACKWARD-COMPAT: pre-PRD-067 envelopes (no crossApp field)
+ *     round-trip byte-identically via JSON.
+ *   - version literal stays 1 (additive extension — no version bump).
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { parseContinuationEnvelope, } from './continuation-envelope.js';
+function preCrossAppEnvelope() {
+    return {
+        version: 1,
+        sessionId: 'sess-xyz',
+        turnIndex: 3,
+        checkpointRef: { id: 'cp1', hash: 'h', sizeBytes: 100 },
+        budgetRef: {
+            reservationId: 'res1',
+            strategy: 'fresh-per-continuation',
+            remainingUsd: 1.0,
+            expiresAt: Date.now() + 60_000,
+        },
+        nextAction: { type: 'resume', reason: 'async_io' },
+        pactKey: 'pact-1',
+        tokenContext: {
+            userSub: 'user-1',
+            exchangeDepth: 1,
+            originatingRequestId: 'req-1',
+        },
+        emittedAt: Date.now(),
+        traceId: 'trace-1',
+    };
+}
+describe('ContinuationEnvelope — PRD-067 extension', () => {
+    it('G-ENVELOPE-BACKWARD-COMPAT: pre-PRD-067 envelope round-trips byte-identical', () => {
+        const envelope = preCrossAppEnvelope();
+        const serialised = JSON.stringify(envelope);
+        const reparsed = JSON.parse(serialised);
+        assert.equal(reparsed.version, 1);
+        assert.equal('crossApp' in reparsed, false);
+        const reserialised = JSON.stringify(reparsed);
+        assert.equal(serialised, reserialised, 'serialisation must be byte-identical');
+        const parsed = parseContinuationEnvelope(JSON.parse(serialised));
+        assert.equal(parsed.version, 1);
+    });
+    it('accepts optional crossApp field without version bump', () => {
+        const crossApp = {
+            callerNodeId: 'commission',
+            targetAppId: 'feature-dev-agent',
+            operation: 'commission_fix',
+            originatingRequestId: 'req-1',
+            targetDecisionId: 'd-1',
+            phase: 'awaiting_callee',
+        };
+        const envelope = { ...preCrossAppEnvelope(), crossApp };
+        const serialised = JSON.stringify(envelope);
+        const parsed = parseContinuationEnvelope(JSON.parse(serialised));
+        assert.equal(parsed.version, 1, 'version stays 1 — additive extension');
+        assert.ok(parsed.crossApp);
+        assert.equal(parsed.crossApp.phase, 'awaiting_callee');
+        assert.equal(parsed.crossApp.targetAppId, 'feature-dev-agent');
+    });
+    it('supports completed + failed phases carrying callee output / failure reason', () => {
+        const base = preCrossAppEnvelope();
+        const completed = {
+            ...base,
+            crossApp: {
+                callerNodeId: 'n',
+                targetAppId: 't',
+                operation: 'o',
+                originatingRequestId: 'req-1',
+                targetDecisionId: 'd',
+                phase: 'completed',
+                calleeOutput: { pr_url: 'x', effort: 'S' },
+            },
+        };
+        const failed = {
+            ...base,
+            crossApp: {
+                callerNodeId: 'n',
+                targetAppId: 't',
+                operation: 'o',
+                originatingRequestId: 'req-1',
+                targetDecisionId: 'd',
+                phase: 'failed',
+                failureReason: 'target 5xx',
+            },
+        };
+        assert.equal(JSON.parse(JSON.stringify(completed)).crossApp.phase, 'completed');
+        assert.equal(JSON.parse(JSON.stringify(failed)).crossApp.phase, 'failed');
+    });
+});
+//# sourceMappingURL=continuation-envelope-cross-app.test.js.map

package/dist/ports/continuation-envelope-cross-app.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"continuation-envelope-cross-app.test.js","sourceRoot":"","sources":["../../src/ports/continuation-envelope-cross-app.test.ts"],"names":[],"mappings":"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"}

package/dist/ports/continuation-envelope.d.ts

@@ -0,0 +1,199 @@
+/**
+ * ContinuationEnvelope v1 — the wire format for pact continuations (PRD-062 / S5 §2.1).
+ *
+ * Frozen: 2026-04-14 — see `.method/sessions/fcd-surface-job-backed-executor/decision.md`.
+ *
+ * Written to `ctx.jobs` as the job payload whenever a pact yields (suspends)
+ * between workers. The next worker pulls it, rehydrates via SessionStore,
+ * and invokes the pact with `nextAction` as the resumption signal.
+ *
+ * INVARIANT: `(sessionId, turnIndex)` is the idempotency key. At-least-once
+ * SQS delivery may invoke a handler with the same envelope twice; the
+ * runtime MUST detect duplicates via SessionStore's `lastAckedTurn` and
+ * ack-without-re-executing on replay.
+ *
+ * Breaking changes require `version: 2` + a dual-parse window. Gate
+ * `G-ENVELOPE-VERSION` enforces the literal `version: 1` in this file.
+ */
+/** Opaque reference to a checkpoint in SessionStore (S4). */
+export interface CheckpointRef {
+    /** SessionStore-scoped id; opaque to Cortex. */
+    id: string;
+    /** Content hash for integrity check on load. */
+    hash: string;
+    /** Size hint (bytes) — lets workers reject oversized loads fast. */
+    sizeBytes: number;
+}
+/**
+ * Budget carry-over strategies (S5 §5).
+ *
+ * Wave 1 ships `fresh-per-continuation` only. `batched-held` and
+ * `predictive-prereserve` are gated on Cortex Open Question O1
+ * (`ctx.llm.reserve()/settle()` API). The executor throws
+ * `BudgetStrategyNotImplemented` at runtime when an unimplemented
+ * strategy is requested; unknown strategy values fall back defensively
+ * to `batched-held` per S5 §9.
+ */
+export type BudgetCarryStrategy = 'fresh-per-continuation' | 'batched-held' | 'predictive-prereserve';
+/** Opaque reference to a budget reservation. */
+export interface BudgetRef {
+    /** Reservation id returned by `ctx.llm` reservation call (S3). */
+    reservationId: string;
+    /** Strategy the envelope was issued under (see §5). */
+    strategy: BudgetCarryStrategy;
+    /**
+     * Budget remaining at envelope emission (USD). Advisory — authoritative
+     * value lives in ctx.llm.
+     */
+    remainingUsd: number;
+    /**
+     * Absolute wall-clock deadline (UTC ms). After this, the continuation
+     * MUST refuse.
+     */
+    expiresAt: number;
+}
+/**
+ * What the resumption turn must perform (S5 §2.1).
+ *
+ * Scoped to the continuation envelope — this is NOT the same shape as
+ * `NextAction` in `./session-store-types.ts`, which is the S4 checkpoint
+ * resume hint. Consumers should import this type by its re-exported
+ * alias `ContinuationNextAction` from the `/ports` barrel to disambiguate.
+ */
+export type NextAction = {
+    type: 'resume';
+    reason: 'async_io' | 'scheduled' | 'checkpoint_yield';
+} | {
+    type: 'retry';
+    attempt: number;
+    lastError: string;
+} | {
+    type: 'gate_wait';
+    gateId: string;
+    waitingFor: string;
+};
+export interface TokenContext {
+    /** User the pact acts on behalf of (sub claim). */
+    userSub: string;
+    /** Exchange depth so far (RFC 8693). Cortex caps at 2. */
+    exchangeDepth: number;
+    /** Original request id for audit trail. */
+    originatingRequestId: string;
+}
+/**
+ * PRD-067: cross-app continuation context.
+ *
+ * Present only when the continuation arose from or is awaiting a
+ * `cross-app-invoke` node. Absent for pure in-app pacts — envelopes
+ * serialised pre-PRD-067 round-trip byte-identically
+ * (G-ENVELOPE-BACKWARD-COMPAT).
+ *
+ * Surface freeze: 2026-04-15 — additive extension of S5 `version: 1` per
+ * S5 §9 ("Additional envelope fields — MUST keep version: 1 semantics
+ * compatible; add optional fields only.").
+ */
+export interface CrossAppContinuationContext {
+    /** Node id in the caller's DAG that triggered the cross-app call. */
+    readonly callerNodeId: string;
+    /** Target app id the caller dispatched to. */
+    readonly targetAppId: string;
+    /** Operation name on the target app. */
+    readonly operation: string;
+    /** Originating request id on the caller side — lets the resumption path
+     *  correlate with the caller's audit entry. Matches
+     *  `tokenContext.originatingRequestId` of the emitting envelope. */
+    readonly originatingRequestId: string;
+    /** Cortex PRD-080 decisionId returned on the outbound invoke — lookup key
+     *  for audit correlation and (when async) callee-completion polling. */
+    readonly targetDecisionId: string;
+    /**
+     * Phase of the cross-app call (PRD-067 §6.3):
+     *   - "awaiting_callee" — caller suspended, callee's pact is running in
+     *     its own app's job queue; resumption happens when the caller's
+     *     ctx.events subscription receives
+     *     `method.cross_app.target_event.type=completed`.
+     *   - "completed" — output merged into DAG bundle, envelope moves on.
+     *   - "failed" — target returned error; strategy gate decides retry.
+     */
+    readonly phase: 'awaiting_callee' | 'completed' | 'failed';
+    /** Populated only when `phase === 'completed'` — opaque JSON merged by
+     *  the `output_merge` policy of the caller node. */
+    readonly calleeOutput?: Readonly<Record<string, unknown>>;
+    /** Populated only when `phase === 'failed'` — human-readable reason for
+     *  the gate decision. */
+    readonly failureReason?: string;
+}
+/**
+ * The canonical continuation envelope. Frozen wire schema at `version: 1`.
+ *
+ * Extension rule: additional OPTIONAL fields may be added without a
+ * version bump; any structural/required-field change requires `version: 2`
+ * + a dual-parse window. The literal `version: 1` MUST be preserved
+ * (G-ENVELOPE-VERSION).
+ */
+export interface ContinuationEnvelope {
+    /** Envelope schema version. Bump on breaking changes. */
+    version: 1;
+    /** Stable pact identifier — survives across all continuations. */
+    sessionId: string;
+    /** Monotonic turn counter. n-th continuation has turnIndex = n. */
+    turnIndex: number;
+    /** Pointer into SessionStore for the checkpoint the next worker must load. */
+    checkpointRef: CheckpointRef;
+    /** Pointer into the budget reservation the next worker inherits. */
+    budgetRef: BudgetRef;
+    /** What the next worker must do when it wakes. */
+    nextAction: NextAction;
+    /** Pact factory registration key — which pact to instantiate. */
+    pactKey: string;
+    /** Parent user token context for RFC 8693 re-exchange on resume. */
+    tokenContext: TokenContext;
+    /** Timestamp the previous worker emitted the envelope (UTC ms). */
+    emittedAt: number;
+    /** Opaque tracing id spanning the full pact lifecycle. */
+    traceId: string;
+    /**
+     * PRD-067: OPTIONAL cross-app continuation context.
+     *
+     * Present only when this continuation arose from or is awaiting a
+     * `cross-app-invoke` node. Absent for pure in-app pacts; an envelope
+     * serialised pre-PRD-067 round-trips byte-identically when this field is
+     * missing (G-ENVELOPE-BACKWARD-COMPAT).
+     *
+     * This is an ADDITIVE extension of S5 `version: 1` per S5 §9 and does not
+     * require a `version: 2` bump. See `CrossAppContinuationContext` above.
+     */
+    readonly crossApp?: CrossAppContinuationContext;
+}
+/**
+ * Soft cap (bytes) on a serialised envelope, enforced by the executor at
+ * `yield()` time (S5 §10.2). Well under the 256 KB SQS cap; keeps
+ * envelopes small + cheap to transport.
+ */
+export declare const ENVELOPE_SIZE_SOFT_CAP_BYTES: number;
+/**
+ * Error thrown when the executor encounters a continuation whose
+ * `version` is not `1`. The runtime MUST NOT attempt to parse forward.
+ */
+export declare class EnvelopeVersionError extends Error {
+    readonly observedVersion: unknown;
+    constructor(observedVersion: unknown);
+}
+/**
+ * Error thrown when a continuation arrives after its budget reservation
+ * has expired (`BudgetRef.expiresAt <= now`). Terminal — session is
+ * finalised and a DLQ event is emitted (S5 §5 expiry, §7 DLQ).
+ */
+export declare class BudgetExpiredError extends Error {
+    readonly expiresAt: number;
+    readonly now: number;
+    constructor(expiresAt: number, now: number);
+}
+/**
+ * Structural validation of a raw payload into a `ContinuationEnvelope`.
+ * Throws `EnvelopeVersionError` if `version !== 1`. Returns the same
+ * reference on success (no structural copy — callers should treat as
+ * immutable).
+ */
+export declare function parseContinuationEnvelope(payload: unknown): ContinuationEnvelope;
+//# sourceMappingURL=continuation-envelope.d.ts.map

package/dist/ports/continuation-envelope.d.ts.map

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

package/dist/ports/continuation-envelope.js

@@ -0,0 +1,69 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * ContinuationEnvelope v1 — the wire format for pact continuations (PRD-062 / S5 §2.1).
+ *
+ * Frozen: 2026-04-14 — see `.method/sessions/fcd-surface-job-backed-executor/decision.md`.
+ *
+ * Written to `ctx.jobs` as the job payload whenever a pact yields (suspends)
+ * between workers. The next worker pulls it, rehydrates via SessionStore,
+ * and invokes the pact with `nextAction` as the resumption signal.
+ *
+ * INVARIANT: `(sessionId, turnIndex)` is the idempotency key. At-least-once
+ * SQS delivery may invoke a handler with the same envelope twice; the
+ * runtime MUST detect duplicates via SessionStore's `lastAckedTurn` and
+ * ack-without-re-executing on replay.
+ *
+ * Breaking changes require `version: 2` + a dual-parse window. Gate
+ * `G-ENVELOPE-VERSION` enforces the literal `version: 1` in this file.
+ */
+/**
+ * Soft cap (bytes) on a serialised envelope, enforced by the executor at
+ * `yield()` time (S5 §10.2). Well under the 256 KB SQS cap; keeps
+ * envelopes small + cheap to transport.
+ */
+export const ENVELOPE_SIZE_SOFT_CAP_BYTES = 32 * 1024;
+/**
+ * Error thrown when the executor encounters a continuation whose
+ * `version` is not `1`. The runtime MUST NOT attempt to parse forward.
+ */
+export class EnvelopeVersionError extends Error {
+    observedVersion;
+    constructor(observedVersion) {
+        super(`ContinuationEnvelope.version ${String(observedVersion)} not supported — runtime speaks version: 1`);
+        this.name = 'EnvelopeVersionError';
+        this.observedVersion = observedVersion;
+    }
+}
+/**
+ * Error thrown when a continuation arrives after its budget reservation
+ * has expired (`BudgetRef.expiresAt <= now`). Terminal — session is
+ * finalised and a DLQ event is emitted (S5 §5 expiry, §7 DLQ).
+ */
+export class BudgetExpiredError extends Error {
+    expiresAt;
+    now;
+    constructor(expiresAt, now) {
+        super(`BudgetRef expired at ${new Date(expiresAt).toISOString()} (now ${new Date(now).toISOString()})`);
+        this.name = 'BudgetExpiredError';
+        this.expiresAt = expiresAt;
+        this.now = now;
+    }
+}
+/**
+ * Structural validation of a raw payload into a `ContinuationEnvelope`.
+ * Throws `EnvelopeVersionError` if `version !== 1`. Returns the same
+ * reference on success (no structural copy — callers should treat as
+ * immutable).
+ */
+export function parseContinuationEnvelope(payload) {
+    if (!payload || typeof payload !== 'object') {
+        throw new EnvelopeVersionError(undefined);
+    }
+    const maybe = payload;
+    if (maybe.version !== 1) {
+        throw new EnvelopeVersionError(maybe.version);
+    }
+    // Duck-typed: downstream consumers (the executor) validate shape by use.
+    return payload;
+}
+//# sourceMappingURL=continuation-envelope.js.map

package/dist/ports/continuation-envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"continuation-envelope.js","sourceRoot":"","sources":["../../src/ports/continuation-envelope.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC;;;;;;;;;;;;;;;;GAgBG;AAoKH;;;;GAIG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,EAAE,GAAG,IAAI,CAAC;AAEtD;;;GAGG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IACpC,eAAe,CAAU;IAClC,YAAY,eAAwB;QAClC,KAAK,CACH,gCAAgC,MAAM,CAAC,eAAe,CAAC,4CAA4C,CACpG,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,eAAe,GAAG,eAAe,CAAC;IACzC,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAClC,SAAS,CAAS;IAClB,GAAG,CAAS;IACrB,YAAY,SAAiB,EAAE,GAAW;QACxC,KAAK,CAAC,wBAAwB,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,SAAS,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;QACxG,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;IACjB,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CAAC,OAAgB;IACxD,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QAC5C,MAAM,IAAI,oBAAoB,CAAC,SAAS,CAAC,CAAC;IAC5C,CAAC;IACD,MAAM,KAAK,GAAG,OAAgC,CAAC;IAC/C,IAAI,KAAK,CAAC,OAAO,KAAK,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,oBAAoB,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAChD,CAAC;IACD,yEAAyE;IACzE,OAAO,OAA+B,CAAC;AACzC,CAAC"}

package/dist/ports/conversation.d.ts

@@ -0,0 +1,64 @@
+/**
+ * ConversationPort — Human-agent conversation for Build Orchestrator gates.
+ *
+ * Provides the communication channel between the orchestrator agent and
+ * the human via the dashboard conversation panel. Supports rich cards,
+ * threading, per-gate action buttons, and on-demand skill invocation.
+ *
+ * @see PRD 047 — Build Orchestrator §Surfaces
+ */
+import type { ConversationMessage } from './checkpoint.js';
+export interface ConversationPort {
+    /** Send a message from the orchestrator to the human (renders in chat panel). */
+    sendAgentMessage(buildId: string, message: AgentMessage): Promise<void>;
+    /** Send a system notification (phase transition, checkpoint, status). */
+    sendSystemMessage(buildId: string, message: string): Promise<void>;
+    /** Wait for the human to respond (blocks until message received via UI). */
+    waitForHumanMessage(buildId: string): Promise<HumanMessage>;
+    /** Wait for a gate decision (blocks until approve/reject via UI). */
+    waitForGateDecision(buildId: string, gate: GateType): Promise<GateDecision>;
+    /** Get full conversation history for a build. */
+    getHistory(buildId: string): Promise<ConversationMessage[]>;
+    /** Human requests an optional skill invocation mid-pipeline. */
+    requestSkillInvocation(buildId: string, skill: SkillRequest): Promise<void>;
+    /** Deliver a human message from the REST route (resolves waitForHumanMessage). */
+    receiveHumanMessage(buildId: string, message: HumanMessage): void;
+    /** Deliver a gate decision from the REST route (resolves waitForGateDecision). */
+    receiveGateDecision(buildId: string, decision: GateDecision): void;
+}
+export interface AgentMessage {
+    readonly type: "text" | "card" | "artifact";
+    readonly content: string;
+    readonly card?: StructuredCard;
+    readonly replyTo?: string;
+}
+export interface HumanMessage {
+    readonly content: string;
+    readonly replyTo?: string;
+}
+export interface GateDecision {
+    readonly gate: GateType;
+    readonly decision: "approve" | "reject" | "adjust";
+    readonly feedback?: string;
+    readonly adjustments?: Record<string, unknown>;
+}
+export type GateType = "specify" | "design" | "plan" | "review" | "escalation";
+/** Per-gate action sets rendered by the UI. */
+export declare const GATE_ACTIONS: Record<GateType, readonly string[]>;
+export type SkillRequest = {
+    type: "debate";
+    context: string;
+} | {
+    type: "review";
+    commissionId?: string;
+    context: string;
+} | {
+    type: "surface";
+    domains: [string, string];
+    description: string;
+};
+export interface StructuredCard {
+    readonly type: "feature-spec" | "prd-summary" | "commission-plan" | "review-findings" | "evidence-report" | "debate-decision";
+    readonly data: Record<string, unknown>;
+}
+//# sourceMappingURL=conversation.d.ts.map

package/dist/ports/conversation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation.d.ts","sourceRoot":"","sources":["../../src/ports/conversation.ts"],"names":[],"mappings":"AACA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAI3D,MAAM,WAAW,gBAAgB;IAC/B,iFAAiF;IACjF,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxE,yEAAyE;IACzE,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnE,4EAA4E;IAC5E,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAC5D,qEAAqE;IACrE,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAC5E,iDAAiD;IACjD,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAAC;IAC5D,gEAAgE;IAChE,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5E,kFAAkF;IAClF,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,IAAI,CAAC;IAClE,kFAAkF;IAClF,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;CACpE;AAID,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,UAAU,CAAC;IAC5C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,cAAc,CAAC;IAC/B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAC;IACnD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChD;AAID,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,GAAG,YAAY,CAAC;AAE/E,+CAA+C;AAC/C,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAMnD,CAAC;AAIX,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC1D;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC;AAIxE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,aAAa,GAAG,iBAAiB,GAAG,iBAAiB,GAAG,iBAAiB,GAAG,iBAAiB,CAAC;IAC9H,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACxC"}

package/dist/ports/conversation.js

@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * ConversationPort — Human-agent conversation for Build Orchestrator gates.
+ *
+ * Provides the communication channel between the orchestrator agent and
+ * the human via the dashboard conversation panel. Supports rich cards,
+ * threading, per-gate action buttons, and on-demand skill invocation.
+ *
+ * @see PRD 047 — Build Orchestrator §Surfaces
+ */
+/** Per-gate action sets rendered by the UI. */
+export const GATE_ACTIONS = {
+    specify: ["Approve Spec"],
+    design: ["Approve Design"],
+    plan: ["Approve Plan"],
+    review: ["Approve", "Approve with Comments", "Request Changes"],
+    escalation: ["Retry with Direction", "Fix Manually", "Abort"],
+};
+//# sourceMappingURL=conversation.js.map

package/dist/ports/conversation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation.js","sourceRoot":"","sources":["../../src/ports/conversation.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC;;;;;;;;GAQG;AAkDH,+CAA+C;AAC/C,MAAM,CAAC,MAAM,YAAY,GAAwC;IAC/D,OAAO,EAAE,CAAC,cAAc,CAAC;IACzB,MAAM,EAAE,CAAC,gBAAgB,CAAC;IAC1B,IAAI,EAAE,CAAC,cAAc,CAAC;IACtB,MAAM,EAAE,CAAC,SAAS,EAAE,uBAAuB,EAAE,iBAAiB,CAAC;IAC/D,UAAU,EAAE,CAAC,sBAAsB,EAAE,cAAc,EAAE,OAAO,CAAC;CACrD,CAAC"}

package/dist/ports/cost-oracle.d.ts

@@ -0,0 +1,26 @@
+/**
+ * CostOracle — Port interface (PRD 051 S1).
+ *
+ * Consumed by strategies domain (dry-run) and MCP tool.
+ * Implemented by cost-governor domain.
+ */
+import type { InvocationSignature, CostBand } from '@methodts/types';
+export interface NodeEstimate {
+    readonly nodeId: string;
+    readonly signature: InvocationSignature;
+    readonly cost: CostBand;
+    readonly durationMs: CostBand;
+}
+export interface StrategyEstimate {
+    readonly nodes: readonly NodeEstimate[];
+    readonly totalCost: CostBand;
+    readonly totalDurationMs: CostBand;
+    readonly unknownNodes: readonly string[];
+}
+export interface CostOracle {
+    /** Walk a DAG and estimate total cost/time via critical-path with parallelism-discount. */
+    estimateStrategy(nodeSignatures: ReadonlyMap<string, InvocationSignature>, dagEdges: ReadonlyMap<string, readonly string[]>): StrategyEstimate;
+    /** Record an actual outcome. Called after releaseSlot. */
+    record(sig: InvocationSignature, actualCostUsd: number, actualDurationMs: number, accountId: string): void;
+}
+//# sourceMappingURL=cost-oracle.d.ts.map

package/dist/ports/cost-oracle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-oracle.d.ts","sourceRoot":"","sources":["../../src/ports/cost-oracle.ts"],"names":[],"mappings":"AACA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAIrE,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,mBAAmB,CAAC;IACxC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC;CAC/B;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,CAAC;IACxC,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC;IAC7B,QAAQ,CAAC,eAAe,EAAE,QAAQ,CAAC;IACnC,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAID,MAAM,WAAW,UAAU;IACzB,2FAA2F;IAC3F,gBAAgB,CACd,cAAc,EAAE,WAAW,CAAC,MAAM,EAAE,mBAAmB,CAAC,EACxD,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,GAC/C,gBAAgB,CAAC;IAEpB,0DAA0D;IAC1D,MAAM,CACJ,GAAG,EAAE,mBAAmB,EACxB,aAAa,EAAE,MAAM,EACrB,gBAAgB,EAAE,MAAM,EACxB,SAAS,EAAE,MAAM,GAChB,IAAI,CAAC;CACT"}

package/dist/ports/cost-oracle.js

@@ -0,0 +1,9 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * CostOracle — Port interface (PRD 051 S1).
+ *
+ * Consumed by strategies domain (dry-run) and MCP tool.
+ * Implemented by cost-governor domain.
+ */
+export {};
+//# sourceMappingURL=cost-oracle.js.map

package/dist/ports/cost-oracle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-oracle.js","sourceRoot":"","sources":["../../src/ports/cost-oracle.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC;;;;;GAKG"}