@loucompanion/forge-bridge 0.1.3-dev.f66395c3ac21 → 0.1.4-dev.04a1e5b9e484

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

@@ -1,5 +1,5 @@
 export interface RunOnceDispatchPacket {
-    readonly schemaVersion: 1;
+    readonly schemaVersion: 1 | 2;
     readonly userId: string;
     readonly workItem: DispatchWorkItem;
     readonly repo: DispatchRepo;
@@ -7,24 +7,82 @@ export interface RunOnceDispatchPacket {
     readonly session: DispatchSession;
     readonly lease: DispatchLease;
     readonly execution: DispatchExecution;
+    readonly runtimeIntent: DispatchRuntimeIntent;
     readonly serverLocal: DispatchServerLocalConfig;
+    readonly sandbox?: DispatchSandboxContext | null;
     readonly pullRequest?: DispatchPullRequestContext | null;
     readonly apiKeySecretGrant?: ApiKeySecretGrant | null;
+    readonly apiKeySecretGrantHandle?: ApiKeySecretGrantHandle | null;
     readonly artifacts: readonly DispatchResolvedArtifact[];
+    readonly priorPhaseArtifacts?: readonly DispatchPriorPhaseArtifact[];
     readonly warmPathOverrides?: readonly string[];
     readonly qaBrowser?: DispatchQaBrowserContext | null;
+    readonly qaScope?: DispatchQaScope | null;
     readonly qaRework?: DispatchQaReworkContext | null;
     readonly architectRevision?: DispatchArchitectRevisionContext | null;
+    readonly architectDependencies?: DispatchArchitectDependencyContext | null;
     readonly storyDevelop?: DispatchStoryDevelopContext | null;
     readonly storyQa?: DispatchStoryQaContext | null;
+    readonly designerRefs?: DispatchDesignerRefHandoffContext | null;
     readonly draft?: DispatchDraftPrompt | null;
 }
+export interface DispatchRuntimeIntent {
+    readonly executionClass: "analysis_only" | "managed_runtime";
+    readonly applicationRuntimeRequired: boolean;
+}
+export interface DispatchSandboxContext {
+    readonly dispatchAttemptId: string;
+    readonly executionLeaseId: string;
+    readonly runnerInstanceId: string;
+    readonly executionMode: "host" | "docker";
+    readonly executionPolicy: "host_allowed" | "sandbox_preferred" | "sandbox_required";
+    readonly networkPolicy: DispatchSandboxNetworkPolicy;
+    readonly requestedResources: DispatchSandboxResourceRequest;
+    readonly runtime?: string | null;
+    readonly sandboxConfigCommitSha?: string | null;
+    readonly inputCommitSha?: string | null;
+    readonly contractDigest?: string | null;
+    readonly imageDigest?: string | null;
+    readonly publicationMode: "bridge_push" | "shared_filesystem";
+    readonly publishGrantHandle?: DispatchPublishGrantHandle | null;
+}
+export interface DispatchPublishGrantHandle {
+    readonly grantId: string;
+    readonly branch: string;
+    readonly expiresAt: string;
+}
+export interface DispatchSandboxResourceRequest {
+    readonly sandboxSlots: number;
+    readonly cpuMillis: number;
+    readonly workerMemoryLimitBytes: number;
+    readonly serviceMemoryLimitBytes: number;
+    readonly runtimeOverheadBytes: number;
+    readonly memoryBytes: number;
+    readonly workspaceBytes: number;
+    readonly pids: number;
+    readonly buildSlots: number;
+}
+export interface DispatchSandboxNetworkPolicy {
+    readonly mode: "offline" | "public_allowlist" | "open_public";
+    readonly allowedHosts: readonly string[];
+}
 export interface DispatchDraftPrompt {
     readonly kind: string;
     readonly systemPrompt: string;
     readonly userPrompt: string;
     readonly projectName?: string | null;
     readonly repoName?: string | null;
+    readonly attachments?: readonly DispatchDraftAttachment[];
+}
+export interface DispatchDraftAttachment {
+    readonly index: number;
+    readonly fileName: string;
+    readonly contentType: string;
+    readonly kind: string;
+    readonly byteCount: number;
+    readonly summary: string;
+    readonly textContent?: string | null;
+    readonly contentBase64?: string | null;
 }
 export interface DispatchQaBrowserContext {
     readonly required: boolean;
@@ -32,11 +90,28 @@ export interface DispatchQaBrowserContext {
     readonly artifactsPath: string;
     readonly missingTargetReason?: string | null;
 }
+export interface DispatchQaScope {
+    readonly schema_version: number;
+    readonly surface: readonly string[];
+    readonly required_evidence: readonly string[];
+    readonly required_capabilities?: readonly string[];
+    readonly not_applicable: readonly string[];
+    readonly browser_required: boolean;
+    readonly api_required: boolean;
+    readonly source?: string | null;
+    readonly authority?: string | null;
+    readonly confidence?: string | null;
+    readonly confirmed_by_user?: boolean | null;
+    readonly locked?: boolean | null;
+    readonly derived_from?: Readonly<Record<string, unknown>> | null;
+    readonly rationale?: string | null;
+}
 export interface DispatchQaAppLaunchTarget {
     readonly url?: string | null;
     readonly command?: string | null;
     readonly working_directory?: string | null;
     readonly ready_url?: string | null;
+    readonly managed_runtime_port?: string | null;
     readonly routes: readonly string[];
     readonly notes?: string | null;
 }
@@ -53,6 +128,22 @@ export interface DispatchArchitectRevisionContext {
     readonly priorContentHash: string;
     readonly feedback: string;
 }
+export interface DispatchArchitectDependencyContext {
+    readonly baseBranch: string;
+    readonly prerequisites: readonly DispatchArchitectDependencyItemContext[];
+}
+export interface DispatchArchitectDependencyItemContext {
+    readonly storyId: string;
+    readonly title: string;
+    readonly scheduleIndex?: number | null;
+    readonly waveIndex?: number | null;
+    readonly featureScheduleIndex?: number | null;
+    readonly expectedOutput?: string | null;
+    readonly handoffSummary?: string | null;
+    readonly dependencyReason?: string | null;
+    readonly pullRequestNumber?: number | null;
+    readonly targetBranch: string;
+}
 export interface DispatchStoryDevelopContext {
     readonly storyWorkItemId: string;
     readonly planId: string;
@@ -62,6 +153,7 @@ export interface DispatchStoryDevelopContext {
     readonly dependencyWorkItemIds: readonly string[];
 }
 export interface DispatchStoryQaContext {
+    readonly references?: DispatchStoryQaReferenceBundle | null;
     readonly storyWorkItemId: string;
     readonly planId: string;
     readonly planContentHash: string;
@@ -73,6 +165,24 @@ export interface DispatchStoryQaContext {
     readonly childTasks: readonly DispatchStoryQaChildTaskContext[];
     readonly dependencies: readonly DispatchStoryQaDependencyContext[];
 }
+export interface DispatchStoryQaReferenceBundle {
+    readonly schemaVersion: number;
+    readonly cycleRunId: string;
+    readonly storyWorkItemId: string;
+    readonly projectId: string;
+    readonly repoId: string;
+    readonly planId: string;
+    readonly planContentHash: string;
+    readonly effectiveAmendmentHash: string;
+    readonly capturedAt: string;
+    readonly files: readonly DispatchStoryQaReferenceFile[];
+}
+export interface DispatchStoryQaReferenceFile {
+    readonly path: string;
+    readonly body: string;
+    readonly contentHash: string;
+    readonly provenance: string;
+}
 export interface DispatchStoryQaChildTaskContext {
     readonly workItemId: string;
     readonly title: string;
@@ -109,6 +219,55 @@ export interface DispatchStoryQaDependencyContext {
     readonly fromWorkItemId: string;
     readonly toWorkItemId: string;
 }
+export interface DispatchPriorPhaseArtifact {
+    readonly workItemId: string;
+    readonly artifactId: string;
+    readonly cycleRunId: string;
+    readonly phase: "implementation" | "self_review" | "validation";
+    readonly status: string;
+    readonly producedAt: string;
+    readonly sourcePath: string;
+    readonly verdictJson: string;
+    readonly report: string;
+    readonly verdictContentHash: string;
+    readonly reportContentHash: string;
+}
+export interface DispatchDesignerRefHandoffContext {
+    readonly schemaVersion: number;
+    readonly kind: string;
+    readonly ownerType: string;
+    readonly ownerId: string;
+    readonly projectId: string;
+    readonly repoId: string;
+    readonly title: string;
+    readonly refs: readonly DispatchDesignerRefAttachment[];
+}
+export interface DispatchDesignerRefAttachment {
+    readonly ref: DispatchDesignerRef;
+    readonly reason: string;
+    readonly required: boolean;
+    readonly source: string;
+    readonly lineageKind: string;
+    readonly inheritedFromItemType?: string | null;
+    readonly inheritedFromItemId?: string | null;
+    readonly inheritedFromDesignerRefId?: string | null;
+    readonly addedByLane: string;
+    readonly sortOrder: number;
+    readonly createdAt: string;
+}
+export interface DispatchDesignerRef {
+    readonly id: string;
+    readonly projectId: string;
+    readonly repoId: string;
+    readonly refKey: string;
+    readonly kind: string;
+    readonly path: string;
+    readonly anchor?: string | null;
+    readonly title: string;
+    readonly contentHash: string;
+    readonly commitSha: string;
+    readonly createdAt: string;
+}
 export interface DispatchPullRequestContext {
     readonly number: number;
     readonly provider: string;
@@ -124,6 +283,28 @@ export interface DispatchPullRequestContext {
     readonly unresolvedThreads: number;
     readonly humanApproved: boolean;
     readonly hasMergeConflicts: boolean;
+    readonly headSha: string;
+    readonly reviewIssueKey?: string | null;
+    readonly reviewFindings: readonly DispatchPullRequestReviewFinding[];
+    readonly openWorkOrderStories: readonly DispatchWorkOrderStory[];
+}
+export interface DispatchWorkOrderStory {
+    readonly workItemId: string;
+    readonly title: string;
+    readonly acceptanceCriteria: string;
+}
+export interface DispatchPullRequestReviewFinding {
+    readonly claimId: string;
+    readonly kind: string;
+    readonly bodySha256: string;
+    readonly body: string;
+    readonly contentAvailable: boolean;
+    readonly actionable: boolean;
+    readonly actionabilityReason: string;
+    readonly author?: string | null;
+    readonly url?: string | null;
+    readonly path?: string | null;
+    readonly line?: number | null;
 }
 export interface DispatchResolvedArtifact {
     readonly kind: string;
@@ -136,6 +317,7 @@ export interface DispatchResolvedArtifact {
     readonly event?: string | null;
 }
 export interface DispatchWorkItem {
+    readonly projectId?: string | null;
     readonly id: string;
     readonly kind: string;
     readonly title: string;
@@ -153,6 +335,7 @@ export interface DispatchRepo {
     readonly serverLocalPath?: string | null;
 }
 export interface DispatchCycleRun {
+    readonly effectivePlanAmendmentHash?: string | null;
     readonly id: string;
     readonly ownerType?: string | null;
     readonly ownerId?: string | null;
@@ -162,6 +345,7 @@ export interface DispatchCycleRun {
     readonly requestedBase: string;
     readonly baseBranch: string;
     readonly expectedCurrentBranch?: string | null;
+    readonly repairHeadSha?: string | null;
     readonly attempt: number;
     readonly model: string;
 }
@@ -169,6 +353,8 @@ export interface DispatchSession {
     readonly id: string;
     readonly model: string;
     readonly lane: string;
+    readonly resumedFromSessionId?: string | null;
+    readonly resumeProviderThreadId?: string | null;
 }
 export interface DispatchLease {
     readonly id: string;
@@ -191,6 +377,8 @@ export interface DispatchExecution {
     readonly lane: string;
     readonly requiresApiKeySecretGrant: boolean;
     readonly runnerRepoLocalPath?: string | null;
+    /** Reasoning effort from the Agents tab; null means the provider CLI's default. */
+    readonly effort?: string | null;
 }
 export interface ApiKeySecretGrant {
     readonly grantId: string;
@@ -198,11 +386,18 @@ export interface ApiKeySecretGrant {
     readonly secret: string;
     readonly expiresAt: string;
 }
+export interface ApiKeySecretGrantHandle {
+    readonly grantId: string;
+    readonly provider: string;
+    readonly expiresAt: string;
+}
 export interface DispatchServerLocalConfig {
     readonly repoRoot: string;
     readonly cleanupWorktrees: boolean;
 }
 export interface RunnerDispatchEvent {
+    /** Stable across callback retries; persisted atomically with the session event. */
+    readonly eventId?: string | null;
     readonly role: string;
     readonly kind: string;
     readonly content: string;
@@ -211,6 +406,22 @@ export interface RunnerDispatchEvent {
     readonly occurredAt?: string | null;
     /** Optional structured telemetry payload (JSON string), e.g. token usage for provider_usage events. */
     readonly data?: string | null;
+    /** Versioned nonterminal wait evidence. Legacy writers omit this field. */
+    readonly wait?: WaitEnvelope | null;
+}
+export interface WaitEnvelope {
+    readonly schemaVersion: 2;
+    readonly kind: string;
+    readonly scope: string;
+    readonly resourceKeys: readonly string[];
+    readonly queuePosition?: number | null;
+    readonly blockerSessionId?: string | null;
+    readonly blockerTitle?: string | null;
+    readonly wakeCondition: string;
+    readonly retryAt?: string | null;
+    readonly firstObservedAt: string;
+    readonly observationVersion: number;
+    readonly contractOrigin: "bridge_v2";
 }
 export interface RunnerDispatchSpec {
     readonly repoPath: string;
@@ -232,12 +443,74 @@ export interface RunnerDispatchArtifact {
     readonly producedBy: string;
     readonly status: string;
     readonly phase?: string | null;
+    /**
+     * QA sidecars are transported with the terminal result because managed
+     * worktrees may be released before the API mirrors the result. The API
+     * validates these bytes against the canonical evidence metadata and stores
+     * only that metadata.
+     */
+    readonly sidecars?: readonly RunnerDispatchSidecar[] | null;
+}
+export interface RunnerDispatchSidecar {
+    readonly path: string;
+    readonly contentBase64: string;
+    readonly contentHash: string;
+    readonly bytes: number;
+}
+export type FailureCategory = "domain" | "provider" | "transport" | "cancellation" | "ownership" | "resource" | "unknown";
+export type FailurePhase = "offer" | "build" | "prepare" | "agent" | "validation" | "import" | "teardown" | "unknown";
+export type FailureSource = "bridge" | "provider" | "sandbox" | "unknown";
+export type FailureRetryability = "retryable" | "non_retryable" | "policy_required" | "unknown";
+export type FailureOperatorAction = "none" | "retry_dispatch" | "retry_with_policy" | "inspect_failure" | "fix_input" | "fix_environment" | "reauthenticate" | "restore_ownership";
+export interface FailureCause {
+    readonly code: string;
+    readonly message: string;
+    readonly source: FailureSource;
+}
+export interface FailureEnvelope {
+    readonly schemaVersion: 2;
+    readonly code: string;
+    readonly message: string;
+    readonly category: FailureCategory;
+    readonly phase: FailurePhase;
+    readonly source: FailureSource;
+    readonly retryability: FailureRetryability;
+    readonly operatorAction: FailureOperatorAction;
+    readonly causalChain: readonly FailureCause[];
+    readonly occurredAt: string;
+    readonly contractOrigin: "bridge_v2";
+}
+export interface FailureFacts {
+    readonly code: string;
+    readonly category: FailureCategory;
+    readonly phase: FailurePhase;
+    readonly source: FailureSource;
+    readonly retryability: FailureRetryability;
+    readonly operatorAction: FailureOperatorAction;
+    readonly causalChain?: readonly FailureCause[];
+}
+export interface FailurePolicy {
+    readonly code: string;
+    readonly category: FailureCategory;
+    readonly phase: FailurePhase;
+    readonly retryability: FailureRetryability;
+    readonly operatorAction: FailureOperatorAction;
+    readonly allowedSources: readonly FailureSource[];
+    readonly known: boolean;
+}
+export declare class ForgeFailureError extends Error {
+    readonly failureCode: string;
+    readonly failureSource: FailureSource;
+    constructor(failureCode: string, message: string, failureSource?: FailureSource, options?: ErrorOptions);
 }
 export interface RunOnceResultPacket {
-    readonly schemaVersion: 1;
+    readonly schemaVersion: 1 | 2;
     readonly exitCode: number;
     readonly summary: string;
+    readonly resultCommitSha?: string | null;
+    readonly publishedCommitSha?: string | null;
     readonly events: readonly RunnerDispatchEvent[];
+    readonly failure?: FailureEnvelope | null;
     readonly spec?: RunnerDispatchSpec | null;
     readonly artifact?: RunnerDispatchArtifact | null;
     readonly artifacts?: readonly RunnerDispatchArtifact[] | null;
@@ -247,4 +520,52 @@ export interface RunnerEventLine {
     readonly event: RunnerDispatchEvent;
 }
 export declare function parseRunOnceDispatchPacket(value: unknown): RunOnceDispatchPacket;
-export declare function failureResult(summary: string, events?: readonly RunnerDispatchEvent[]): RunOnceResultPacket;
+export declare function parseRunOnceResultPacket(value: unknown): RunOnceResultPacket;
+export declare function waitKindForEvent(eventType: string): string;
+export declare function waitWakeCondition(kind: string): string;
+export interface HostRuntimeReadinessProbeRequest {
+    readonly requestId: string;
+    readonly fencingToken: string;
+    readonly userId: string;
+    readonly projectId: string;
+    readonly repoId: string;
+    readonly runnerId: string;
+    readonly runnerInstanceId: string;
+    readonly attempt: number;
+    readonly repoName: string;
+    readonly remoteUrl: string;
+    readonly defaultBranch: string;
+    readonly cloneOnDemand: boolean;
+    readonly runnerRepoLocalPath: string;
+    readonly revision: string;
+    readonly expiresAt: string;
+    readonly repoRoot: string;
+    readonly cleanupWorktrees: boolean;
+}
+export interface HostRuntimeReadinessProbeResult {
+    readonly status: "parallel_ready" | "serialized" | "failed";
+    readonly runtimeContractFingerprint?: string | null;
+    readonly runtimeContractSource?: string | null;
+    readonly reasonCode?: string | null;
+    readonly reasonMessage?: string | null;
+    readonly qaAppLaunchTarget?: HostRuntimeReadinessQaLaunchTarget | null;
+    readonly checkedAt: string;
+}
+export interface HostRuntimeReadinessQaLaunchTarget {
+    readonly managedRuntimePort: string;
+    readonly routes: readonly string[];
+}
+export declare function failureResult(summary: string, events?: readonly RunnerDispatchEvent[], facts?: FailureFacts): RunOnceResultPacket;
+export declare function createFailureEnvelope(message: string, facts: FailureFacts, occurredAt?: string): FailureEnvelope;
+export declare function failureFactsFromError(error: unknown, options?: {
+    readonly cancelled?: boolean;
+    readonly source?: FailureSource;
+}): FailureFacts;
+export declare function failureFactsForCode(code: string, source?: FailureSource): FailureFacts;
+export declare function failurePolicyForCode(code: string): FailurePolicy;
+/**
+ * Rebuilds an error graph at a privileged execution boundary without
+ * retaining the raw error or any raw recursive cause. Forge failure metadata
+ * survives so the P7 taxonomy remains authoritative after sanitization.
+ */
+export declare function sanitizeFailureError(error: unknown, exactSecrets?: readonly string[]): Error;