@loucompanion/forge-bridge 0.1.1-dev.2bc1e7f19b3a → 0.1.1-dev.2d1a116ca78d

package/dist/session/provider-cli/provider-cli.types.d.ts

@@ -6,6 +6,11 @@ export interface ProviderCliRunContext {
     readonly signal?: AbortSignal;
     emit(event: RunnerDispatchEvent): Promise<void>;
 }
+export interface ProviderCliDraftContext {
+    readonly dispatch: RunOnceDispatchPacket;
+    readonly signal?: AbortSignal;
+    emit(event: RunnerDispatchEvent): Promise<void>;
+}
 export interface ProviderCliRunResult {
     readonly summary: string;
     readonly spec?: RunnerDispatchSpec | null;

package/dist/session/provider-cli/provider-usage.d.ts

@@ -0,0 +1,25 @@
+import type { RunOnceDispatchPacket, RunnerDispatchEvent } from "../session.types.js";
+export type UsageSource = "provider_reported" | "cli_reported" | "estimated" | "unknown";
+/**
+ * Normalized, provider-agnostic token usage accumulated for a dispatch. Cost is never computed
+ * here; the API recomputes cost from these tokens x model rates (ADR-0006).
+ */
+export interface ProviderUsage {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly cacheReadTokens: number;
+    readonly cacheCreationTokens: number;
+    readonly reasoningOutputTokens: number;
+    readonly providerDurationMs: number | null;
+    readonly source: UsageSource;
+}
+export declare function emptyUsage(source?: UsageSource): ProviderUsage;
+export declare function addUsage(base: ProviderUsage, next: Partial<ProviderUsage>): ProviderUsage;
+export declare function totalTokens(usage: ProviderUsage): number;
+export declare function hasUsage(usage: ProviderUsage | null): usage is ProviderUsage;
+/**
+ * Builds the durable `provider_usage` event. Token numbers travel as a structured `data` JSON
+ * string (snake_case) that the API parses into a usage_event row.
+ */
+export declare function buildProviderUsageEvent(dispatch: RunOnceDispatchPacket, usage: ProviderUsage): RunnerDispatchEvent;
+export declare function readUsageNumber(source: Record<string, unknown>, key: string): number;

package/dist/session/provider-cli/provider-usage.js

@@ -0,0 +1,64 @@
+export function emptyUsage(source = "unknown") {
+    return {
+        inputTokens: 0,
+        outputTokens: 0,
+        cacheReadTokens: 0,
+        cacheCreationTokens: 0,
+        reasoningOutputTokens: 0,
+        providerDurationMs: null,
+        source
+    };
+}
+export function addUsage(base, next) {
+    return {
+        inputTokens: base.inputTokens + nonNegative(next.inputTokens),
+        outputTokens: base.outputTokens + nonNegative(next.outputTokens),
+        cacheReadTokens: base.cacheReadTokens + nonNegative(next.cacheReadTokens),
+        cacheCreationTokens: base.cacheCreationTokens + nonNegative(next.cacheCreationTokens),
+        reasoningOutputTokens: base.reasoningOutputTokens + nonNegative(next.reasoningOutputTokens),
+        providerDurationMs: next.providerDurationMs ?? base.providerDurationMs,
+        source: next.source ?? base.source
+    };
+}
+export function totalTokens(usage) {
+    return usage.inputTokens + usage.outputTokens + usage.cacheReadTokens + usage.cacheCreationTokens;
+}
+export function hasUsage(usage) {
+    return usage !== null && totalTokens(usage) > 0;
+}
+/**
+ * Builds the durable `provider_usage` event. Token numbers travel as a structured `data` JSON
+ * string (snake_case) that the API parses into a usage_event row.
+ */
+export function buildProviderUsageEvent(dispatch, usage) {
+    const data = {
+        provider: dispatch.execution.provider,
+        model: dispatch.execution.model,
+        lane: dispatch.execution.lane,
+        phase: dispatch.cycleRun.phase,
+        attempt: dispatch.cycleRun.attempt,
+        input_tokens: usage.inputTokens,
+        output_tokens: usage.outputTokens,
+        cache_read_tokens: usage.cacheReadTokens,
+        cache_creation_tokens: usage.cacheCreationTokens,
+        reasoning_output_tokens: usage.reasoningOutputTokens,
+        metered: dispatch.execution.authKind === "api_key",
+        usage_source: usage.source,
+        provider_duration_ms: usage.providerDurationMs
+    };
+    const total = totalTokens(usage);
+    return {
+        role: "runner",
+        kind: "checkpoint",
+        content: `Provider usage: ${total} tokens (${usage.inputTokens} in / ${usage.outputTokens} out) for ${dispatch.execution.model}.`,
+        eventType: "provider_usage",
+        data: JSON.stringify(data)
+    };
+}
+export function readUsageNumber(source, key) {
+    const value = source[key];
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : 0;
+}
+function nonNegative(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
+}

package/dist/session/qa-sidecar-validation.d.ts

@@ -0,0 +1,3 @@
+export declare function isPathUnderRoot(root: string, target: string): boolean;
+export declare function ensureNoSymbolicLinkPathSegments(root: string, targetDirectory: string, errorMessage: string): Promise<void>;
+export declare function sha256File(filePath: string): Promise<string>;

package/dist/session/qa-sidecar-validation.js

@@ -0,0 +1,44 @@
+import crypto from "node:crypto";
+import { createReadStream } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+export function isPathUnderRoot(root, target) {
+    const relative = path.relative(path.resolve(root), path.resolve(target));
+    return Boolean(relative)
+        && relative !== ".."
+        && !relative.startsWith(`..${path.sep}`)
+        && !path.isAbsolute(relative);
+}
+export async function ensureNoSymbolicLinkPathSegments(root, targetDirectory, errorMessage) {
+    const resolvedRoot = path.resolve(root);
+    const resolvedTargetDirectory = path.resolve(targetDirectory);
+    const relative = path.relative(resolvedRoot, resolvedTargetDirectory);
+    if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        throw new Error(errorMessage);
+    }
+    let current = resolvedRoot;
+    const rootStat = await fs.lstat(current);
+    if (rootStat.isSymbolicLink()) {
+        throw new Error(errorMessage);
+    }
+    if (!relative) {
+        return;
+    }
+    for (const segment of relative.split(path.sep)) {
+        if (!segment) {
+            continue;
+        }
+        current = path.join(current, segment);
+        const stat = await fs.lstat(current);
+        if (stat.isSymbolicLink()) {
+            throw new Error(errorMessage);
+        }
+    }
+}
+export async function sha256File(filePath) {
+    const hash = crypto.createHash("sha256");
+    for await (const chunk of createReadStream(filePath)) {
+        hash.update(chunk);
+    }
+    return hash.digest("hex");
+}

package/dist/session/session.service.js

@@ -13,7 +13,9 @@ export class BridgeSessionService {
         const redactionSecrets = exactSecrets(dispatch);
         const events = [];
         const emit = async (event) => {
-            throwIfAborted(signal);
+            if (signal?.aborted) {
+                return;
+            }
             const redacted = redactSecrets(event, redactionSecrets);
             events.push(redacted);
             await sink.emit(redacted);
@@ -25,15 +27,39 @@ export class BridgeSessionService {
             content: "forge-bridge accepted run-once dispatch.",
             eventType: "dispatch_accepted"
         });
+        if (dispatch.draft) {
+            const run = await this.providerCli.runDraft({
+                dispatch,
+                emit,
+                signal
+            });
+            throwIfAborted(signal);
+            return redactSecrets({
+                schemaVersion: 1,
+                exitCode: 0,
+                summary: run.summary,
+                events,
+                spec: run.spec ?? null,
+                artifact: run.artifact ?? null,
+                artifacts: run.artifacts?.length ? run.artifacts : run.artifact ? [run.artifact] : []
+            }, redactionSecrets);
+        }
         const worktree = await this.worktrees.prepare({
             repo: dispatch.repo,
             workItem: dispatch.workItem,
             baseBranch: dispatch.cycleRun.baseBranch || dispatch.cycleRun.requestedBase,
+            worktreeKey: dispatch.lease.worktreeKey,
+            ownerType: dispatch.cycleRun.ownerType ?? dispatch.lease.ownerType ?? null,
+            ownerId: dispatch.cycleRun.ownerId ?? dispatch.lease.ownerId ?? null,
+            lane: dispatch.execution.lane,
+            phase: dispatch.cycleRun.phase,
             allowedRepoRoot: dispatch.serverLocal.repoRoot,
             cleanupWorktrees: dispatch.serverLocal.cleanupWorktrees,
             artifacts: dispatch.artifacts,
+            qaRework: dispatch.qaRework,
             warmPathOverrides: dispatch.warmPathOverrides
         });
+        const providerDispatch = withPreparedQaReworkPacket(dispatch, worktree.qaReworkPacketPath);
         throwIfAborted(signal);
         await emit({
             role: "runner",
@@ -49,22 +75,22 @@ export class BridgeSessionService {
             const lane = dispatch.execution.lane.toLowerCase();
             const role = dispatch.execution.role.toLowerCase();
             const isQa = role === "qa" || lane === "qa";
+            const isArchitect = role === "architect" || lane === "architect" || dispatch.cycleRun.kind.toLowerCase() === "architect";
             const isConflictResolve = role === "conflict_resolve" || lane === "conflict_resolve";
+            const context = {
+                dispatch: providerDispatch,
+                worktree,
+                emit,
+                signal
+            };
             const run = isQa
-                ? await this.providerCli.runQa(dispatch, emit, signal)
-                : isConflictResolve
-                    ? await this.providerCli.runConflictResolve({
-                        dispatch,
-                        worktree,
-                        emit,
-                        signal
-                    })
-                    : await this.providerCli.runImplementation({
-                        dispatch,
-                        worktree,
-                        emit,
-                        signal
-                    });
+                ? await this.providerCli.runQa(context)
+                : isArchitect
+                    ? await this.providerCli.runArchitect(context)
+                    : isConflictResolve
+                        ? await this.providerCli.runConflictResolve(context)
+                        : await this.providerCli.runImplementation(context);
+            throwIfAborted(signal);
             const phaseArtifacts = run.artifacts?.length ? run.artifacts : run.artifact ? [run.artifact] : [];
             return redactSecrets({
                 schemaVersion: 1,
@@ -108,6 +134,18 @@ function validateApiKeySecretGrant(dispatch) {
 function exactSecrets(dispatch) {
     return dispatch.apiKeySecretGrant?.secret ? [dispatch.apiKeySecretGrant.secret] : [];
 }
+function withPreparedQaReworkPacket(dispatch, packetPath) {
+    if (!dispatch.qaRework || !packetPath) {
+        return dispatch;
+    }
+    return {
+        ...dispatch,
+        qaRework: {
+            ...dispatch.qaRework,
+            packetPath
+        }
+    };
+}
 async function emitDependencyWarmEvents(warm, emit) {
     if (warm.linked.length > 0) {
         await emit({

package/dist/session/session.types.d.ts

@@ -8,9 +8,122 @@ export interface RunOnceDispatchPacket {
     readonly lease: DispatchLease;
     readonly execution: DispatchExecution;
     readonly serverLocal: DispatchServerLocalConfig;
+    readonly pullRequest?: DispatchPullRequestContext | null;
     readonly apiKeySecretGrant?: ApiKeySecretGrant | null;
     readonly artifacts: readonly DispatchResolvedArtifact[];
     readonly warmPathOverrides?: readonly string[];
+    readonly qaBrowser?: DispatchQaBrowserContext | null;
+    readonly qaRework?: DispatchQaReworkContext | null;
+    readonly architectRevision?: DispatchArchitectRevisionContext | null;
+    readonly storyDevelop?: DispatchStoryDevelopContext | null;
+    readonly storyQa?: DispatchStoryQaContext | null;
+    readonly draft?: DispatchDraftPrompt | null;
+}
+export interface DispatchDraftPrompt {
+    readonly kind: string;
+    readonly systemPrompt: string;
+    readonly userPrompt: string;
+    readonly projectName?: string | null;
+    readonly repoName?: string | null;
+}
+export interface DispatchQaBrowserContext {
+    readonly required: boolean;
+    readonly launchTarget?: DispatchQaAppLaunchTarget | null;
+    readonly artifactsPath: string;
+    readonly missingTargetReason?: string | null;
+}
+export interface DispatchQaAppLaunchTarget {
+    readonly url?: string | null;
+    readonly command?: string | null;
+    readonly working_directory?: string | null;
+    readonly ready_url?: string | null;
+    readonly routes: readonly string[];
+    readonly notes?: string | null;
+}
+export interface DispatchQaReworkContext {
+    readonly attempt: number;
+    readonly maxAttempts: number;
+    readonly packetPath: string;
+    readonly packetJson: string;
+    readonly findingIds: readonly string[];
+    readonly findings: readonly Record<string, unknown>[];
+}
+export interface DispatchArchitectRevisionContext {
+    readonly priorPlanId: string;
+    readonly priorContentHash: string;
+    readonly feedback: string;
+}
+export interface DispatchStoryDevelopContext {
+    readonly storyWorkItemId: string;
+    readonly planId: string;
+    readonly planContentHash: string;
+    readonly architectTaskId: string;
+    readonly phaseId: string;
+    readonly dependencyWorkItemIds: readonly string[];
+}
+export interface DispatchStoryQaContext {
+    readonly storyWorkItemId: string;
+    readonly planId: string;
+    readonly planContentHash: string;
+    readonly worktreeKey: string;
+    readonly branch: string;
+    readonly implementationPlanJson?: string | null;
+    readonly qaPlanJson?: string | null;
+    readonly finalQaChecks: readonly string[];
+    readonly childTasks: readonly DispatchStoryQaChildTaskContext[];
+    readonly dependencies: readonly DispatchStoryQaDependencyContext[];
+}
+export interface DispatchStoryQaChildTaskContext {
+    readonly workItemId: string;
+    readonly title: string;
+    readonly architectTaskId: string;
+    readonly phaseId: string;
+    readonly phaseOrder: number;
+    readonly dependencyWorkItemIds: readonly string[];
+    readonly spec?: DispatchStoryQaChildSpecContext | null;
+    readonly implementationArtifact?: DispatchStoryQaArtifactContext | null;
+    readonly selfReviewArtifact?: DispatchStoryQaArtifactContext | null;
+    readonly validationArtifact?: DispatchStoryQaArtifactContext | null;
+    readonly qaArtifact?: DispatchStoryQaArtifactContext | null;
+}
+export interface DispatchStoryQaChildSpecContext {
+    readonly version: number;
+    readonly status: string;
+    readonly path: string;
+    readonly contentHash: string;
+    readonly body: string;
+}
+export interface DispatchStoryQaArtifactContext {
+    readonly artifactId: string;
+    readonly cycleRunId: string;
+    readonly phase: string;
+    readonly status: string;
+    readonly producedAt: string;
+    readonly path?: string | null;
+    readonly verdictJson?: string | null;
+    readonly evidenceJson?: string | null;
+    readonly findingsJson?: string | null;
+    readonly report?: string | null;
+}
+export interface DispatchStoryQaDependencyContext {
+    readonly fromWorkItemId: string;
+    readonly toWorkItemId: string;
+}
+export interface DispatchPullRequestContext {
+    readonly number: number;
+    readonly provider: string;
+    readonly title: string;
+    readonly sourceBranch: string;
+    readonly targetBranch: string;
+    readonly url: string;
+    readonly state: string;
+    readonly checkState: string;
+    readonly mergeState: string;
+    readonly requiredChecksPassed: number;
+    readonly requiredChecksTotal: number;
+    readonly unresolvedThreads: number;
+    readonly humanApproved: boolean;
+    readonly hasMergeConflicts: boolean;
 }
 export interface DispatchResolvedArtifact {
     readonly kind: string;
@@ -41,6 +154,9 @@ export interface DispatchRepo {
 }
 export interface DispatchCycleRun {
     readonly id: string;
+    readonly ownerType?: string | null;
+    readonly ownerId?: string | null;
+    readonly workItemId?: string | null;
     readonly kind: string;
     readonly phase: string;
     readonly requestedBase: string;
@@ -56,6 +172,9 @@ export interface DispatchSession {
 }
 export interface DispatchLease {
     readonly id: string;
+    readonly ownerType?: string | null;
+    readonly ownerId?: string | null;
+    readonly workItemId?: string | null;
     readonly worktreeKey: string;
     readonly lane: string;
     readonly fencingToken: string;
@@ -71,6 +190,7 @@ export interface DispatchExecution {
     readonly role: string;
     readonly lane: string;
     readonly requiresApiKeySecretGrant: boolean;
+    readonly runnerRepoLocalPath?: string | null;
 }
 export interface ApiKeySecretGrant {
     readonly grantId: string;
@@ -87,6 +207,10 @@ export interface RunnerDispatchEvent {
     readonly kind: string;
     readonly content: string;
     readonly eventType: string;
+    /** Provider/runner-reported event time (ISO-8601) when available, preserved for accurate durations. */
+    readonly occurredAt?: string | null;
+    /** Optional structured telemetry payload (JSON string), e.g. token usage for provider_usage events. */
+    readonly data?: string | null;
 }
 export interface RunnerDispatchSpec {
     readonly repoPath: string;
@@ -99,6 +223,11 @@ export interface RunnerDispatchArtifact {
     readonly repoPath: string;
     readonly path: string;
     readonly verdictJson: string;
+    readonly planJson?: string | null;
+    readonly evidenceJson?: string | null;
+    readonly findingsJson?: string | null;
+    readonly implementationPlanJson?: string | null;
+    readonly qaPlanJson?: string | null;
     readonly report: string;
     readonly producedBy: string;
     readonly status: string;