@loucompanion/forge-bridge 0.1.3-dev.bd0c67bbf352 → 0.1.3-dev.bf78fdcaa623

package/dist/bridge/bridge.types.d.ts

@@ -1,7 +1,26 @@
-import type { RunOnceResultPacket, RunnerDispatchEvent } from "../session/session.types.js";
+import type { ApiKeySecretGrant, RunOnceResultPacket, RunnerDispatchEvent } from "../session/session.types.js";
+import type { SandboxFeatureMatrix } from "../sandbox/sandbox.types.js";
 export interface BridgeServiceConfig {
     readonly serverUrl: string;
     readonly runnerId: string;
+    readonly runnerInstanceId: string;
+    readonly trustDomainId: string;
+    readonly maxConcurrentSandboxes: number;
+    readonly maxConcurrentSandboxBuilds: number;
+    readonly sandboxPidCapacity: number;
+    readonly dockerEnabled: boolean;
+    readonly sandboxPublicationMode?: "bridge_push" | "shared_filesystem";
+    readonly dockerExecutable: string;
+    readonly dockerContext: string;
+    readonly sandboxStateRoot: string;
+    readonly requireRootlessDocker: boolean;
+    readonly diskHighWatermarkPercent: number;
+    readonly diskLowWatermarkPercent: number;
+    readonly minimumWorkspaceBytes: number;
+    readonly imageRetentionCount: number;
+    readonly imageRetentionTtlMs: number;
+    readonly auditRetentionCount: number;
+    readonly auditRetentionTtlMs: number;
     readonly deviceToken: string;
     readonly deviceName: string;
     readonly defaultRepoRoot: string;
@@ -17,6 +36,8 @@ export interface BridgeServiceConfig {
     readonly supportsManagedForgeArtifacts: boolean;
     readonly supportsRunnerAuthoredPhaseArtifacts: boolean;
     readonly supportsDraftRunOnce: boolean;
+    readonly supportsDraftAttachments: boolean;
+    readonly supportsDraftImageAttachments: boolean;
     readonly version: string;
     readonly protocolVersion: number;
     readonly minServerVersion?: string | null;
@@ -52,17 +73,51 @@ export interface BridgeCapabilities {
     readonly repoMappings?: readonly BridgeRepoMapping[] | null;
     readonly os?: string | null;
     readonly sandboxProfiles?: readonly string[] | null;
+    readonly runnerInstanceId?: string | null;
+    readonly trustDomainId?: string | null;
+    readonly sandboxRuntimes?: readonly string[] | null;
+    readonly sandboxRuntimeVersion?: string | null;
+    readonly sandboxFeatures?: SandboxFeatureMatrix | null;
+    readonly sandboxPublicationModes?: readonly string[] | null;
+    readonly sandboxAuthModes?: Readonly<Record<string, readonly string[]>> | null;
+    readonly maxConcurrentSandboxes?: number | null;
+    readonly reservedSandboxCount?: number | null;
+    readonly activeSandboxCount?: number | null;
+    readonly startingSandboxCount?: number | null;
+    readonly degradedReservationCount?: number | null;
+    readonly availableMemoryBytes?: number | null;
+    readonly availableCpuMillis?: number | null;
+    readonly availableWorkspaceBytes?: number | null;
+    readonly diskLow?: boolean | null;
+    readonly preflightGeneration?: number | null;
+    readonly sandboxUnavailableCode?: string | null;
+    readonly sandboxUnavailableReason?: string | null;
     readonly supportsApiSecretGrant?: boolean | null;
     readonly supportsManagedWorktrees?: boolean | null;
     readonly supportsManagedForgeArtifacts?: boolean | null;
     readonly supportsRunnerAuthoredPhaseArtifacts?: boolean | null;
     readonly supportsDraftRunOnce?: boolean | null;
+    readonly supportsDraftAttachments?: boolean | null;
+    readonly supportsDraftImageAttachments?: boolean | null;
 }
 export interface BridgeHelloRequest {
     readonly version: string;
     readonly protocolVersion: number;
     readonly capabilities: BridgeCapabilities;
     readonly minServerVersion?: string | null;
+    readonly runnerInstanceId: string;
+}
+export interface BridgePublishCredential {
+    readonly username: string;
+    readonly secret: string;
+    readonly remoteUrl: string;
+    readonly expiresAt: string;
+}
+export interface BridgePublishGrantRedemptionResponse {
+    readonly accepted: boolean;
+    readonly code?: string | null;
+    readonly message?: string | null;
+    readonly credential?: BridgePublishCredential | null;
 }
 export interface BridgeHeartbeatRequest {
     readonly status?: string | null;
@@ -78,17 +133,75 @@ export interface BridgeCallbackAck {
 export interface BridgeDispatchEventCallback {
     readonly leaseId: string;
     readonly fencingToken: string;
+    readonly dispatchAttemptId?: string | null;
+    readonly runnerInstanceId?: string | null;
     readonly event: RunnerDispatchEvent;
 }
 export interface BridgeDispatchResultCallback {
     readonly leaseId: string;
     readonly fencingToken: string;
+    readonly dispatchAttemptId?: string | null;
+    readonly runnerInstanceId?: string | null;
     readonly result: RunOnceResultPacket;
 }
+export interface BridgeOfferDecisionCallback {
+    readonly dispatchAttemptId: string;
+    readonly leaseId: string;
+    readonly fencingToken: string;
+    readonly runnerInstanceId: string;
+    readonly accepted: boolean;
+    readonly code?: string | null;
+    readonly message?: string | null;
+    readonly reservedUntil?: string | null;
+}
+export interface BridgeDispatchStartedCallback {
+    readonly dispatchAttemptId: string;
+    readonly leaseId: string;
+    readonly fencingToken: string;
+    readonly runnerInstanceId: string;
+}
+export interface BridgeSecretGrantRedemptionRequest {
+    readonly dispatchAttemptId: string;
+    readonly leaseId: string;
+    readonly fencingToken: string;
+    readonly runnerInstanceId: string;
+    readonly grantId: string;
+}
+export interface BridgeSecretGrantRedemptionResponse extends BridgeCallbackAck {
+    readonly grant?: ApiKeySecretGrant | null;
+}
+export interface BridgeLeaseUpdateRequest {
+    readonly dispatchAttemptId: string;
+    readonly leaseId: string;
+    readonly fencingToken: string;
+    readonly runnerInstanceId: string;
+    readonly expiresAt: string;
+}
 export interface BridgeCancelRequest {
     readonly leaseId: string;
     readonly fencingToken: string;
     readonly reason?: string | null;
 }
+export interface BridgeReapRequest {
+    readonly runnerId: string;
+    readonly runnerInstanceId: string;
+    readonly requestedAt: string;
+    readonly reason?: string | null;
+}
+export interface BridgeAttemptSnapshotItem {
+    readonly dispatchAttemptId: string;
+    readonly fencingToken: string;
+    readonly runnerInstanceId: string;
+    readonly status: string;
+    readonly expiresAt: string;
+}
+export interface BridgeAttemptSnapshotResponse extends BridgeCallbackAck {
+    readonly attempts?: readonly BridgeAttemptSnapshotItem[] | null;
+    readonly generatedAt?: string | null;
+}
 export type BridgeDispatchHandler = (dispatch: unknown) => Promise<void>;
+export type BridgeOfferHandler = (dispatch: unknown) => Promise<void>;
+export type BridgeStartHandler = (dispatch: unknown) => Promise<void>;
+export type BridgeLeaseUpdateHandler = (request: BridgeLeaseUpdateRequest) => Promise<void>;
 export type BridgeCancelHandler = (request: BridgeCancelRequest) => Promise<void>;
+export type BridgeReapHandler = (request: BridgeReapRequest) => Promise<void>;

package/dist/cli/cli.help.d.ts

@@ -0,0 +1,2 @@
+export declare function helpText(): string;
+export declare function commandHelpText(command: string): string;

package/dist/cli/cli.help.js

@@ -0,0 +1,183 @@
+import { defaultBridgeServiceConfig } from "../bridge/bridge.service.js";
+import { forgeBridgeVersion } from "../version.js";
+export function helpText() {
+    const version = defaultBridgeServiceConfig().version ?? forgeBridgeVersion;
+    return [
+        `🛠 Forge Bridge ${version} — Local provider runners for Forge.`,
+        "",
+        "Usage: forge-bridge [options] [command]",
+        "",
+        "Options:",
+        "  -h, --help       Display help for command",
+        "  -v, --version    Output the version number",
+        "",
+        "Commands:",
+        "  Hint: commands suffixed with * have detailed help. Run <command> --help for details.",
+        "  connect *        Start the runner bridge and wait for Forge dispatches",
+        "  pair *           Pair this machine with Forge and save runner credentials",
+        "  status *         Show config, runner identity, repos, provider CLIs, and updates",
+        "  add-repo *       Map a Forge repo label/name to a local checkout path",
+        "  remove-repo *    Remove a saved repo mapping",
+        "  cleanup *        Prune managed bridge worktrees",
+        "  sandbox *        Initialize, diagnose, or reap Docker sandboxes",
+        "  version *        Print the installed bridge package version",
+        "  help *           Display help for command",
+        "  run-once *       Internal: run one dispatch packet from JSON",
+        "  mcp *            Internal: run the phase-completion MCP server",
+        "",
+        "Examples:",
+        "  npm install -g @loucompanion/forge-bridge@next",
+        "  forge-bridge pair 1234-5678 --server https://srv1493013.tail66073d.ts.net:8443 --repo-root \"%USERPROFILE%\\ForgeRepos\"",
+        "  forge-bridge connect",
+        "  forge-bridge status --check-updates",
+        "  forge-bridge add-repo Forge D:\\Programming\\repos\\Forge",
+        "  forge-bridge cleanup --stale",
+        "",
+        "Troubleshooting:",
+        "  If Forge says the bridge is old: npm install -g @loucompanion/forge-bridge@next",
+        "  If connect shows 502/500: leave it open; it reconnects with backoff while dev restarts.",
+        "  If a provider is missing: run forge-bridge status --check-updates and verify CLI login.",
+        "",
+        "Docs:",
+        "  https://github.com/coleman399/Forge/tree/develop/tools/forge-bridge#readme",
+        "",
+    ].join("\n");
+}
+export function commandHelpText(command) {
+    switch (command) {
+        case "pair":
+            return [
+                "Forge Bridge — pair",
+                "Pair this machine with Forge and save runner credentials.",
+                "",
+                "Usage:",
+                "  forge-bridge pair [code] [options]",
+                "",
+                "Options:",
+                "  --server <url>              Forge server URL.",
+                "  --repo-root <path>          Folder where bridge-managed repos/worktrees live.",
+                "  --name <name>               Display name for this runner.",
+                "  --fingerprint <value>       Stable device fingerprint override.",
+                "  --cli-provider <list>       Comma-separated providers, e.g. codex,cursor.",
+                "  --cleanup-worktrees         Enable managed worktree cleanup.",
+                "  --no-cleanup-worktrees      Disable managed worktree cleanup.",
+                "",
+                "Example:",
+                "  forge-bridge pair 1234-5678 --server https://forge.example.com --repo-root \"%USERPROFILE%\\ForgeRepos\"",
+                "",
+            ].join("\n");
+        case "connect":
+            return [
+                "Forge Bridge — connect",
+                "Start the runner bridge and keep it connected for Forge dispatches.",
+                "",
+                "Usage:",
+                "  forge-bridge connect [options]",
+                "",
+                "Options:",
+                "  --server <url>              Forge server URL; saved config is used when omitted.",
+                "  --runner-id <id>            Runner id; saved config is used when omitted.",
+                "  --device-token <token>      Device token; saved config is used when omitted.",
+                "  --repo-root <path>          Override repo/worktree folder for this run.",
+                "  --cli-provider <list>       Comma-separated providers, e.g. codex,cursor.",
+                "  --heartbeat-interval-ms <n> Heartbeat interval in milliseconds.",
+                "  --cleanup-worktrees         Enable managed worktree cleanup for this run.",
+                "  --no-cleanup-worktrees      Disable managed worktree cleanup for this run.",
+                "",
+                "Example:",
+                "  forge-bridge connect",
+                "",
+            ].join("\n");
+        case "status":
+            return [
+                "Forge Bridge — status",
+                "Show saved configuration, paired runner identity, repo mappings, detected provider CLIs, and optional update info.",
+                "",
+                "Usage:",
+                "  forge-bridge status [--check-updates]",
+                "",
+                "Example:",
+                "  forge-bridge status --check-updates",
+                "",
+            ].join("\n");
+        case "add-repo":
+            return [
+                "Forge Bridge — add-repo",
+                "Map a Forge repo label/name to an existing local checkout.",
+                "",
+                "Usage:",
+                "  forge-bridge add-repo <label> <path>",
+                "",
+                "Example:",
+                "  forge-bridge add-repo Forge D:\\Programming\\repos\\Forge",
+                "",
+            ].join("\n");
+        case "remove-repo":
+            return [
+                "Forge Bridge — remove-repo",
+                "Remove a saved local repo mapping.",
+                "",
+                "Usage:",
+                "  forge-bridge remove-repo <label>",
+                "",
+            ].join("\n");
+        case "cleanup":
+            return [
+                "Forge Bridge — cleanup",
+                "Prune managed bridge worktrees under the configured repo folder.",
+                "",
+                "Usage:",
+                "  forge-bridge cleanup [--stale|--merged|--all] [--force]",
+                "",
+                "Examples:",
+                "  forge-bridge cleanup --stale",
+                "  forge-bridge cleanup --all --force",
+                "",
+            ].join("\n");
+        case "sandbox":
+            return [
+                "Forge Bridge — sandbox",
+                "Initialize or diagnose a repository-owned Forge sandbox contract.",
+                "",
+                "Usage:",
+                "  forge-bridge sandbox init [--repo <path>]",
+                "  forge-bridge sandbox doctor [--repo <path>] [--require-pinned-base]",
+                "  forge-bridge sandbox reap",
+                "",
+            ].join("\n");
+        case "run-once":
+            return [
+                "Forge Bridge — run-once",
+                "Internal command used by Forge to run a single dispatch packet.",
+                "",
+                "Usage:",
+                "  forge-bridge run-once --dispatch <dispatch-json-path> --result <result-json-path>",
+                "",
+            ].join("\n");
+        case "mcp":
+            return [
+                "Forge Bridge — mcp",
+                "Internal MCP server used by provider CLIs to report Forge phase artifacts.",
+                "",
+                "Usage:",
+                "  forge-bridge mcp --worktree <path> --work-item-id <id> --phase <phase>",
+                "",
+            ].join("\n");
+        case "version":
+            return [
+                "Forge Bridge — version",
+                "Print the installed bridge package version.",
+                "",
+                "Usage:",
+                "  forge-bridge version",
+                "",
+            ].join("\n");
+        default:
+            return [
+                `Unknown forge-bridge command: ${command}`,
+                "",
+                "Run `forge-bridge help` to see available commands.",
+                "",
+            ].join("\n");
+    }
+}

package/dist/cli/cli.service.d.ts

@@ -45,6 +45,18 @@ export declare function parseArgs(argv: readonly string[]): {
     readonly config: BridgeServiceConfig;
     readonly mode: CleanupMode;
     readonly force: boolean;
+} | {
+    readonly ok: true;
+    readonly command: "sandbox-init";
+    readonly repoPath: string;
+} | {
+    readonly ok: true;
+    readonly command: "sandbox-doctor";
+    readonly repoPath: string;
+    readonly requirePinnedBase: boolean;
+} | {
+    readonly ok: true;
+    readonly command: "sandbox-reap";
 } | {
     readonly ok: false;
     readonly error: string;