hankweave 0.5.7 → 0.6.2

package/dist/shim-process-manager.d.ts

@@ -0,0 +1,98 @@
+import { BaseProcessManager } from "./base-process-manager.js";
+import type { ClaudeLogParser } from "./claude-log-parser.js";
+import type { Codon, ShimSelfTestResult } from "./types/types.js";
+import { type Logger } from "./utils.js";
+/**
+ * Manages shim subprocess lifecycle, including spawning, monitoring, and cleanup.
+ * Handles log stream creation and process argument building.
+ * Works with any shim that supports the standardized argument interface.
+ */
+export declare class ShimProcessManager extends BaseProcessManager {
+    private executionPath;
+    private agentRootPath;
+    private anthropicBaseUrl?;
+    private globalSystemPrompt?;
+    private defaultShimIdleTimeout?;
+    private process;
+    private logStream;
+    private stdoutReader;
+    private killed;
+    private promptBuilder;
+    constructor(executionPath: string, agentRootPath: string, logger: Logger, logParser: ClaudeLogParser, anthropicBaseUrl?: string | undefined, globalSystemPrompt?: string | null | undefined, defaultShimIdleTimeout?: number | undefined);
+    /** Frontmatter metadata from the prompt file (if any) */
+    get promptFrontmatter(): import("./prompt-frontmatter.js").PromptFrontmatter | undefined;
+    /**
+     * Spawn a shim process for the given codon configuration.
+     * Sets up logging, environment, and process monitoring.
+     *
+     * This unified method handles both normal codon execution and exhaustion extensions.
+     * From the shim's perspective, both are identical: resume a session with a new prompt.
+     * The difference is only where the prompt comes from.
+     *
+     * @param command - Command to execute (e.g., ["claude"] or ["bun", "run", "shims/gemini/dist/index.mjs"])
+     * @param codon - Codon configuration (not Loop - loops must be expanded first)
+     * @param sessionToResume - Session ID to resume (if any)
+     * @param options - Optional spawn configuration
+     * @param options.logPath - Custom log file path (defaults to .hankweave/logs/)
+     * @param options.exhaustionPrompt - If provided, activates exhaustion mode: uses this prompt
+     *                                   instead of codon config, appends to log.
+     */
+    spawn(command: string[], codon: Codon, sessionToResume: string | null, options?: {
+        logPath?: string;
+        exhaustionPrompt?: string;
+    }): Promise<string>;
+    /**
+     * Build environment variables for the shim process.
+     */
+    private buildEnvironment;
+    /**
+     * Build command line arguments for shim.
+     * Only includes arguments supported by all shims.
+     *
+     * @param codon - Codon configuration
+     * @param previousSessionId - Session ID to resume (if any)
+     * @param isExhaustionMode - True if this is an extension (exhaustion mode)
+     */
+    private buildShimArgs;
+    /**
+     * Set up process event handlers.
+     */
+    private setupProcessHandlers;
+    /**
+     * Kill the shim process gracefully.
+     * Sends SIGTERM and waits up to PROCESS_KILL_GRACE_MS for the process to exit.
+     * If the process doesn't exit in time, escalates to SIGKILL.
+     */
+    kill(signal?: NodeJS.Signals): Promise<void>;
+    /**
+     * Force-kill the shim process immediately with SIGKILL.
+     * Used by forceShutdown() when the user presses q/Ctrl+C a second time.
+     */
+    forceKill(): Promise<void>;
+    /**
+     * Clean up resources.
+     */
+    private cleanup;
+    /**
+     * Check if process is running.
+     */
+    isRunning(): boolean;
+    /**
+     * Get process PID.
+     */
+    getPid(): number | undefined;
+    /**
+     * Close log stream explicitly (for external cleanup).
+     */
+    closeLogStream(): Promise<void>;
+    /**
+     * Run the shim's self-test to verify environment setup.
+     * Executes the shim with --self-test flag and returns the results.
+     *
+     * @param command - Command to execute shim (e.g., ["bun", "shims/gemini/index.js"])
+     * @param providerId - Optional provider ID (e.g., "openai", "google") to set up provider-specific requirements
+     * @returns Promise resolving to self-test results
+     * @throws Error if self-test execution fails or returns invalid JSON
+     */
+    runSelfTest(command: string[], providerId?: string): Promise<ShimSelfTestResult>;
+}

package/dist/shim-runtime-extractor.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Shim Runtime Extractor
+ *
+ * This module handles the extraction of bundled shim files at runtime for
+ * standalone executables. When compiled with Bun, shim files are embedded
+ * in the executable and need to be extracted to disk before they can be
+ * spawned as subprocesses.
+ *
+ * The extraction is done to a versioned directory to avoid re-extraction
+ * on every run and to handle version updates cleanly.
+ *
+ * Build Process:
+ * The build script (scripts/build-executable.ts) embeds shim files using:
+ *   bun build --compile --embed shims/gemini/index.js ...
+ *
+ * Note: We use .js extension instead of .mjs for better embedding compatibility.
+ *
+ * At runtime, these embedded files are accessible via Bun.file() using their
+ * original paths.
+ */
+declare const SHIM_NAMES: readonly ["gemini", "codex", "pi", "opencode"];
+type ShimName = (typeof SHIM_NAMES)[number];
+/**
+ * Get the extraction directory path for shims.
+ * Uses ~/.hankweave/shims/<version>/ by default.
+ */
+export declare function getShimExtractionDir(): string;
+/**
+ * Get the path to an extracted shim file.
+ * Note: We use .js extension for embedding compatibility, even though the
+ * source file is .mjs. The file works the same regardless of extension.
+ */
+export declare function getExtractedShimPath(shimName: ShimName): string;
+/**
+ * Check if extraction is needed for a specific shim.
+ * Returns true if the file doesn't exist or is outdated.
+ */
+export declare function needsShimExtraction(shimName: ShimName): boolean;
+/**
+ * Extract embedded shim files to the cache directory.
+ * This should be called when running from a compiled executable.
+ *
+ * Shims are embedded as .bundle (not .js) because Bun's --embed flag
+ * rebundles .js files instead of preserving raw bytes, which truncates
+ * large bundles like the Pi shim (10 MB → 28 KB). The .bundle extension
+ * bypasses this behaviour. We write them back out as .js on extraction.
+ *
+ * @returns Path to the extracted gemini shim (for backward compatibility)
+ */
+export declare function extractShimFiles(): Promise<string>;
+export {};

package/dist/shims/codex/README.md

@@ -0,0 +1,129 @@
+# codex-shim
+
+A self-contained Hankweave shim for OpenAI Codex built on `@openai/codex-sdk`.
+
+The directory is packaged so it can be:
+- dropped directly into Hankweave with `index.js` at the root
+- rebuilt independently with `./rebuild.sh`
+
+## Directory layout
+
+```text
+shim/
+├── index.js          # drop-in bundle used by Hankweave
+├── dist/index.js     # build output
+├── src/              # shim source
+├── common/           # vendored @shims/common
+├── docs/             # usage, architecture, and verification notes
+├── rebuild.sh        # reinstall + rebuild helper
+├── VERSION           # resolved primary SDK version
+└── THIRDPARTY.md     # third-party notices
+```
+
+## Requirements
+
+- Node.js 18+
+- Bun 1.1+
+- Codex CLI available either on `PATH` or via `CODEX_PATH_OVERRIDE`
+- Authentication configured via one of:
+  - `OPENAI_API_KEY`
+  - `CODEX_API_KEY`
+  - `~/.codex/auth.json`
+
+## Quick start
+
+```bash
+cd shim
+./rebuild.sh
+
+echo "Say hello" | node ./index.js --model gpt-5.1-codex-max
+```
+
+## Common usage
+
+Basic prompt:
+
+```bash
+echo "Summarize this repository" | node ./index.js --model gpt-5.1-codex-max
+```
+
+Resume a previous shim session:
+
+```bash
+echo "Continue" | node ./index.js --model gpt-5.1-codex-max --resume <session_uuid>
+```
+
+Capture raw debug artifacts:
+
+```bash
+echo "Inspect app startup" | node ./index.js \
+  --model gpt-5.1-codex-max \
+  --debug-dir ./debug-run
+```
+
+Run the environment self-test:
+
+```bash
+node ./index.js --self-test
+```
+
+## Supported flags
+
+- `--model <model>`
+- `--resume <session_id>`
+- `--verbose`
+- `--append-system-prompt <text>`
+- `--idle-timeout <seconds>`
+- `--debug-dir <path>`
+- `--sandbox <none|standard|strict>`
+- `--self-test`
+- `--version`
+- `--help`
+
+## Model handling
+
+The shim preserves the public model string in output while mapping it into Codex SDK options.
+
+Examples:
+- `gpt-5.1-codex-max` → used directly
+- `openai/gpt-5.2-high` → public output stays prefixed, SDK model becomes `gpt-5.2`, reasoning effort becomes `high`
+- `gpt-5.2-xhigh` → SDK model `gpt-5.2`, reasoning effort `xhigh`
+
+## Tool normalization
+
+Codex often reports file work as shell commands. The shim normalizes common patterns into structured shim tools:
+
+- `cat file.txt` → `Read`
+- `ls ...` → `LS`
+- `rg ...` / `grep ...` → `Grep`
+- `find ...` / `fd ...` → `Glob`
+- `printf '...' > file.txt` → `Write`
+- heredoc file writes → `Write`
+- unknown shell commands → `Bash`
+- Codex web tooling may surface as `WebSearch`, `WebFetch`, or passthrough MCP tool names
+
+## Session storage
+
+- With `--debug-dir`, shim session mappings are stored in `<debug-dir>/sessions/`
+- Without `--debug-dir`, mappings are stored outside the project tree in `~/.shim/sessions/`
+
+This preserves resume support without creating unexpected files in the workspace.
+
+## More documentation
+
+- `docs/usage.md`
+- `docs/architecture.md`
+- `docs/verification.md`
+
+## Rebuild
+
+```bash
+./rebuild.sh
+```
+
+`rebuild.sh`:
+1. runs `bun install`
+2. runs `bun run build`
+3. updates `VERSION`
+4. ensures `dist/index.js` has a Node shebang and executable bit
+5. copies `dist/index.js` to root `index.js`

package/dist/shims/codex/THIRDPARTY.md

@@ -0,0 +1,18 @@
+# Third-Party Notices
+
+This shim bundles and/or depends on third-party code.
+
+## Primary SDK dependency
+
+### `@openai/codex-sdk` 0.112.0
+- License: Apache-2.0
+- Copyright holder: OpenAI
+- Source: https://github.com/openai/codex/tree/main/sdk/typescript
+- Package: https://www.npmjs.com/package/@openai/codex-sdk
+
+The full license text can be found in the published npm package (for example under `node_modules/@openai/codex-sdk/LICENSE` after `bun install`) or in the upstream source repository.
+
+## Vendored shared shim utilities
+
+### `@shims/common`
+`@shims/common` is vendored into `shim/common/` as first-party shared code from the shim workspace rather than as a third-party package.

package/dist/shims/codex/VERSION

@@ -0,0 +1 @@
+0.112.0

package/dist/shims/codex/common/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@shims/common",
+  "version": "1.0.0",
+  "description": "Shared utilities for agent shims",
+  "type": "module",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./args": "./src/args.ts",
+    "./messages": "./src/messages.ts",
+    "./tools": "./src/tools.ts",
+    "./sessions": "./src/sessions.ts",
+    "./timeout": "./src/timeout.ts"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "clean": "echo 'No build artifacts to clean'"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.3.0"
+  }
+}