@mclawnet/backend-types 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,278 @@
+/**
+ * BackendAdapter — pluggable backend for AI model interaction.
+ *
+ * Implementations:
+ * - ClaudeCodeAdapter (@mclawnet/claude-adapter): spawn `claude` CLI
+ * - OpenClawAdapter: spawn `openclaw gateway` (legacy)
+ * - CodexAdapter: M3.S3 — `codex app-server --listen stdio://`
+ *
+ * M3.S1 introduces:
+ * - Typed permission flow (PermissionRequest / PermissionDecision)
+ * - Typed BackendOutput envelope replacing the historical `onOutput(msg: unknown)`
+ * - `backendSessionId` replaces the previous `claudeSessionId` (see plan D7).
+ */
+import type { BackendManifestEntry } from "@mclawnet/shared";
+export interface PermissionRequest {
+    /** Stable identifier for the pending tool call. */
+    callId: string;
+    /** Tool name as reported by the backend (e.g. 'shell', 'apply_patch', 'Write'). */
+    toolName: string;
+    /** Raw tool input as the backend supplied it. */
+    input: unknown;
+    /** Optional backend-supplied context (sandbox, cwd, reason, ...). */
+    meta?: {
+        backend?: "claude" | "codex" | string;
+        reason?: string;
+        cwd?: string;
+        [k: string]: unknown;
+    };
+}
+/**
+ * S0 finding: neither claude `--permission-mode default` (no wire channel)
+ * nor codex `ReviewDecision` supports "approve with modifiedInput", so the
+ * S1 contract is a 4-state enum. `allow_session` may degrade to `allow` for
+ * backends that don't track session-scoped approvals.
+ */
+export interface PermissionDecision {
+    callId: string;
+    decision: "allow" | "allow_session" | "deny" | "abort";
+    reason?: string;
+}
+export type BackendOutput = {
+    kind: "assistant_text";
+    text: string;
+} | {
+    kind: "tool_use";
+    toolName: string;
+    input: unknown;
+    callId: string;
+} | {
+    kind: "tool_result";
+    callId: string;
+    output: unknown;
+    isError?: boolean;
+} | {
+    kind: "system";
+    subtype: string;
+    data: unknown;
+}
+/**
+ * Adapter-internal diagnostic only. Hub and wire layers MUST NOT consume
+ * `raw` — promote a new typed variant instead when hub needs to read it.
+ */
+ | {
+    kind: "raw";
+    backend: string;
+    payload: unknown;
+};
+export interface BackendProcess {
+    /** Unique identifier (e.g., Claude session ID) */
+    id: string;
+    /** Working directory for this process */
+    workDir: string;
+    /**
+     * OS process id of the underlying backend process, if applicable.
+     *
+     * Optional because not every backend is a child process — a future in-process
+     * adapter (mock / stubbed / WASM) wouldn't have one. SessionManager uses pid
+     * for the PR-C checkpoint: a restart probes `process.kill(pid, 0)` to decide
+     * whether the recorded session is `dead` or an `orphan`. Adapters that omit
+     * pid forfeit the dead/orphan classification — checkpointed sessions will
+     * silently appear as "no longer here", which is also acceptable behavior.
+     */
+    pid?: number;
+    /** Kill the backend process */
+    kill(): Promise<void>;
+    /**
+     * Whether the backend process is still alive and capable of accepting input.
+     * Returns false if the process has exited, is being killed, or its stdin is no
+     * longer writable. Used by SessionManager.isHealthy() to detect stale entries.
+     */
+    isAlive(): boolean;
+}
+export interface SpawnOptions {
+    /** ClawNet session ID */
+    sessionId: string;
+    /** Working directory for the backend process */
+    workDir?: string;
+    /** Resume a previous session (e.g., Claude --resume UUID) */
+    resumeId?: string;
+    /** System prompt to append (e.g., role prompt for swarm mode) */
+    systemPrompt?: string;
+    /** Load BrainCore + CoreSkill via --add-dir */
+    useBrainCore?: boolean;
+    /** Path to MCP config JSON file for --mcp-config */
+    mcpConfigPath?: string;
+    /** Memory system role ID. When set, SessionManager auto-injects memory prompt + MCP config */
+    roleId?: string;
+    /**
+     * Optional first user input. When set, SessionManager uses this as the
+     * semantic-retrieval query for `buildMemorySection` (Pipeline A) so the
+     * injected memory section is relevant to what the user is about to ask.
+     * Falls back to an empty query (importance-top-K) when omitted.
+     */
+    initialUserInput?: string;
+    /** Extra directories to mount via --add-dir */
+    additionalDirs?: string[];
+    /** Optional allowlist of tool names to forward to the backend (PR3.5). */
+    allowedTools?: string[];
+    /** Optional denylist of tool names to forward to the backend (PR3.5). */
+    disallowedTools?: string[];
+    /**
+     * Override CLAUDE_CODE_MAX_OUTPUT_TOKENS for this spawn. Drives the
+     * server-side hard limit (200k − maxOutputTokens) and the CLI's own
+     * effective window. Lower = wider prompt budget. SessionManager pulls this
+     * from `getRecommendedMaxOutputTokens()` on each spawn so the ladder
+     * (32k → 16k → 8k) survives across `--resume` restarts.
+     *
+     * Optional: when omitted the CLI uses its own default — adapters that
+     * don't honour it lose D-lite escalation but never crash.
+     */
+    maxOutputTokens?: number;
+    /**
+     * Optional backend kind for this spawn. When set, SessionManager resolves
+     * an adapter via its `resolveAdapter` hook (typically `createBackendAdapter`)
+     * and uses it for this process instead of the default constructor adapter.
+     * Omitted = use the default adapter (back-compat).
+     */
+    backend?: "claude" | "codex";
+    /**
+     * Per-role sandbox level. Each adapter maps to its own permission model:
+     *   - codex-adapter: `-c sandbox_mode="<value>"` (OS-level seatbelt /
+     *     landlock — strong enforcement)
+     *   - claude-adapter: `--permission-mode` (LLM-soft approval; UI should
+     *     tooltip that claude has no real OS sandbox)
+     *
+     * Values: "read-only" | "workspace-write" | "full-access".
+     * Default (undefined): adapter-specific — claude uses constructor
+     * permissionMode (typically bypassPermissions), codex uses
+     * "workspace-write".
+     */
+    sandbox?: "read-only" | "workspace-write" | "full-access";
+    /**
+     * Extra env vars merged onto `process.env` for the spawned subprocess.
+     * M6 T7: SwarmCoordinator forwards `CLAWNET_PROJECT_ROOT` here so MCP
+     * tools running inside the role can resolve back to the original
+     * project root even though the role's cwd points to a worktree.
+     * Adapters must merge (not replace) `process.env`.
+     */
+    env?: Record<string, string>;
+    /** Sticky session-level model code. Adapter maps to CLI flag. */
+    model?: string;
+    /** Sticky session-level mode code (permission-mode / sandbox-mode / operating-mode). */
+    mode?: string;
+    /**
+     * Per-turn override applied ONLY to this spawn; not persisted to DB.
+     *
+     * Precedence: turnOverride.{model,mode} wins over sticky model/mode
+     * field-by-field — omitted fields fall through to the sticky value.
+     *
+     * Adapters SHOULD NOT read this field directly. SessionManager merges
+     * it into the top-level `model`/`mode` before calling spawn(), so the
+     * adapter only ever sees the resolved values.
+     */
+    turnOverride?: {
+        model?: string;
+        mode?: string;
+    };
+}
+export interface BackendAdapter {
+    /** Backend type identifier */
+    type: string;
+    /** Spawn a new backend process */
+    spawn(options: SpawnOptions): Promise<BackendProcess>;
+    /** Stop a running backend process */
+    stop(process: BackendProcess): Promise<void>;
+    /** Send user input to the backend process */
+    send(process: BackendProcess, input: string): void;
+    /**
+     * Register output handler. Handler receives `unknown` today (legacy claude
+     * stream-json frames); adapters are migrating to emit `BackendOutput`
+     * envelopes. Consumers that need typed output should narrow with the
+     * `BackendOutput` discriminator.
+     */
+    onOutput(process: BackendProcess, handler: (msg: unknown) => void): void;
+    /**
+     * M3.S1 — Optional permission flow.
+     * - codex-adapter (S3): implemented; maps from `ReviewDecision` wire format.
+     * - claude-adapter: M3 stays on `bypassPermissions` and does NOT implement
+     *   these. M4+ will add via an MCP permission-prompt tool.
+     */
+    onPermissionRequest?(process: BackendProcess, handler: (req: PermissionRequest) => void): void;
+    respondToPermission?(process: BackendProcess, decision: PermissionDecision): Promise<void>;
+    /** Turn-complete handler. */
+    onTurnComplete?(process: BackendProcess, handler: (info: {
+        backendSessionId?: string;
+        cost?: number;
+        duration?: number;
+        contextUsage?: {
+            used: number;
+            total: number;
+        };
+        backendMeta?: Record<string, unknown>;
+    }) => void): void;
+    /** Register error handler */
+    onError?(process: BackendProcess, handler: (error: Error) => void): void;
+    /**
+     * Register a handler that fires the moment the backend reports its session
+     * is initialized (e.g. Claude CLI's `system/init` frame, codex `thread_id`).
+     * Used by hub to persist `backendSessionId` early — without this we have to
+     * wait for `turn_complete`, and a mid-turn crash would leave db's
+     * backend_session_id NULL despite a valid jsonl file existing on disk.
+     *
+     * Optional: adapters that don't implement this lose the early-backfill
+     * capability — db's backend_session_id will only be populated on
+     * `turn_complete`, so any session whose first turn crashes will be
+     * unrecoverable via `--resume`. Other backends (codex, openclaw) should
+     * implement this if they have an analogous "session ready" signal.
+     */
+    onSessionStarted?(process: BackendProcess, handler: (info: {
+        backendSessionId: string;
+    }) => void): void;
+    /**
+     * Register a handler that fires when the underlying process exits on its
+     * own (crash, EPIPE, OOM, manual SIGKILL from outside) — *not* when we
+     * deliberately call kill() ourselves. Used by SessionManager to auto-evict
+     * dead Map entries and notify hub via onSessionError.
+     *
+     * Optional: adapters that don't implement this lose auto-eviction —
+     * SessionManager's Map will keep the dead entry, isHealthy() will still
+     * fall back to BackendProcess.isAlive() so the unhealthy-fallback-resume
+     * branch in hub-connection.ts still works, but the orphan Map entry will
+     * accumulate until the next abortSession/closeSession call.
+     */
+    onExit?(process: BackendProcess, handler: (code: number | null) => void): void;
+    /**
+     * Register a handler for token-budget warnings. Fires when the backend
+     * estimates the prompt is approaching the server-side hard limit.
+     * SessionManager uses this to escalate the max_output_tokens ladder so
+     * the next spawn gets a wider budget.
+     *
+     * Optional: adapters that can't introspect token usage simply skip this —
+     * the ladder stays at index 0 forever, falling back to claude-code's own
+     * auto-compact (which works most of the time, just less defensively).
+     */
+    onTokenBudgetWarning?(process: BackendProcess, handler: (info: {
+        used: number;
+        hardLimit: number;
+        threshold: number;
+        distanceToHard: number;
+        maxOutputTokens: number;
+    }) => void): void;
+    /**
+     * Report this adapter's capability manifest. Called by the agent on
+     * startup (and again on manifest-refresh requests) to populate the
+     * AgentManifestPayload sent to hub.
+     *
+     * Implementations must:
+     *   - Be idempotent — safe to call multiple times.
+     *   - Catch ALL detection errors internally (missing binary, EACCES,
+     *     hanging --version, etc.) and surface them via `unavailableReason`
+     *     with `installed: false`. Never reject.
+     *
+     * Agents still register the kind even when installed=false so UI can
+     * show it greyed-out with the unavailableReason as tooltip.
+     */
+    getManifest(): Promise<BackendManifestEntry>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,15 @@
+/**
+ * BackendAdapter — pluggable backend for AI model interaction.
+ *
+ * Implementations:
+ * - ClaudeCodeAdapter (@mclawnet/claude-adapter): spawn `claude` CLI
+ * - OpenClawAdapter: spawn `openclaw gateway` (legacy)
+ * - CodexAdapter: M3.S3 — `codex app-server --listen stdio://`
+ *
+ * M3.S1 introduces:
+ * - Typed permission flow (PermissionRequest / PermissionDecision)
+ * - Typed BackendOutput envelope replacing the historical `onOutput(msg: unknown)`
+ * - `backendSessionId` replaces the previous `claudeSessionId` (see plan D7).
+ */
+export {};
+//# 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;;;;;;;;;;;;GAYG"}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@mclawnet/backend-types",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@mclawnet/shared": "0.1.9"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.3"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist"
+  }
+}