@tomradex/engine-claude-code 0.0.0-stage → 0.15.0

package/LICENSE

@@ -0,0 +1,204 @@
+Copyright 2026 Haoyuan Tang
+
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/availability.d.ts

@@ -0,0 +1,50 @@
+import type { Context } from "cordis";
+import type { EngineAvailability, EngineNeed } from "@tomradex/agent";
+import { type CliLocator } from "./locate.js";
+interface LocalEngine {
+    engineId: string;
+    title: string;
+    cli: CliLocator;
+    /** The English tail of "not found — …". */
+    install: string;
+    /**
+     * Whether the CLI can work yet: a run whose output answers, or the engine's own `ask` (null: no clear answer,
+     * taken as yes). `need` is what a "no" means (default: signing in).
+     */
+    signIn?: ({
+        args: string[];
+        says(output: string): boolean | null;
+    } | {
+        ask(command: string | undefined): Promise<boolean | null>;
+    }) & {
+        reason: string;
+        need?: EngineNeed;
+    };
+    /** Where the CLI reads its sign-in and settings from, shown when it is not signed in. */
+    configDir?(): string;
+    /** A desktop app of the same agent that does not include the CLI: named when the CLI is missing but the app is there. */
+    desktopApp?: DesktopApp;
+}
+export interface DesktopApp {
+    title: string;
+    /** macOS bundle names, looked for in /Applications and ~/Applications. */
+    mac?: string[];
+    /** Windows install folders, relative to %LOCALAPPDATA% or Program Files. */
+    windows?: string[];
+    /** Further places, as absolute paths. */
+    paths?: string[];
+}
+/** Where a desktop app may be installed on this machine, whether or not it is. */
+export declare function desktopAppPaths(app: DesktopApp, host?: {
+    platform: NodeJS.Platform;
+    env: NodeJS.ProcessEnv;
+    home: string;
+}): string[];
+/** The CLI path the person chose in Settings, if any. */
+export declare function chosenCommand(ctx: Context, engineId: string): string | undefined;
+/** A local agent is ready when its CLI runs, the MCP server it calls back on is up, and it is signed in. */
+export declare function localAvailability(ctx: Context, engine: LocalEngine): (opts?: {
+    fresh?: boolean;
+}) => Promise<EngineAvailability>;
+export {};
+//# sourceMappingURL=availability.d.ts.map

package/dist/cli.d.ts

@@ -0,0 +1,32 @@
+import type { ChildProcess } from "node:child_process";
+import { type CliLaunch, type CliLocator } from "./locate.js";
+/**
+ * Whether a CLI that is installed is also signed in. Only a clear "no" says
+ * so: a version without the subcommand, a timeout or an answer that cannot be
+ * read is taken as signed in, so the check never locks out an account it does
+ * not understand (an API key in the environment, a cloud provider).
+ */
+export declare function signedIn(cli: CliLocator, command: string | undefined, args: string[], says: (output: string) => boolean | null): Promise<boolean>;
+/** Claude Code cannot resume a session that is not under the current CLAUDE_CONFIG_DIR (moved, cleared, another folder). */
+export declare const lostConversation: (text: string | undefined) => boolean;
+/** `claude auth status` prints JSON with `loggedIn`; a first-party account that is not logged in cannot run. */
+export declare function claudeSignedIn(output: string): boolean | null;
+export interface CliRun {
+    child: ChildProcess;
+    /** Resolves when the process exits; each stdout line is handed to onLine as parsed JSON. */
+    done: Promise<{
+        code: number | null;
+        stderr: string;
+    }>;
+}
+/** Spawn a JSONL-speaking CLI: stdin closed, stdout parsed by line, SIGINT then SIGKILL on abort. */
+export declare function runJsonl(launch: CliLaunch, args: string[], opts: {
+    cwd: string;
+    env?: NodeJS.ProcessEnv;
+    stdin?: string;
+    signal: AbortSignal;
+    onLine(event: Record<string, unknown>): void;
+}): CliRun;
+/** Splits on LF only: readline also breaks on U+2028/U+2029, which are legal inside JSON strings. */
+export declare function lineSplitter(onLine: (line: string) => void): (chunk: Buffer) => void;
+//# sourceMappingURL=cli.d.ts.map

package/dist/engine.d.ts

@@ -0,0 +1,32 @@
+import type { Context } from "cordis";
+import { z } from "zod";
+import type { Engine } from "@tomradex/agent";
+export declare const ClaudeCodeOptions: z.ZodObject<{
+    command: z.ZodDefault<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+    effort: z.ZodOptional<z.ZodString>;
+    maxTurns: z.ZodDefault<z.ZodNumber>;
+    maxBudgetUsd: z.ZodOptional<z.ZodNumber>;
+    allowTools: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    codeMaxTurns: z.ZodOptional<z.ZodNumber>;
+    codePermissionMode: z.ZodOptional<z.ZodEnum<{
+        default: "default";
+        acceptEdits: "acceptEdits";
+        bypassPermissions: "bypassPermissions";
+        dontAsk: "dontAsk";
+        auto: "auto";
+        plan: "plan";
+    }>>;
+}, z.core.$strip>;
+export type ClaudeCodeOptions = z.infer<typeof ClaudeCodeOptions>;
+/** Why Claude Code is sending a request again (its `api_retry` message), in a few words. */
+export declare function retryReason(message: {
+    error_status: number | null;
+    error: string;
+    no_response?: {
+        waited_ms: number;
+    };
+}): string;
+/** Everything about the Claude Code engine except how a turn runs: identity, options, availability, setup. */
+export declare function claudeCodeEngineInfo(ctx: Context): Omit<Engine, "turn">;
+//# sourceMappingURL=engine.d.ts.map

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+import type { Context } from "cordis";
+import type { Engine } from "@tomradex/agent";
+export declare function createClaudeCodeEngine(ctx: Context): Engine;
+declare const _default: {
+    name: string;
+    inject: string[];
+    apply(ctx: Context): void;
+};
+export default _default;
+export { ClaudeCodeOptions, claudeCodeEngineInfo, retryReason } from "./engine.js";
+export { claudeSignedIn, lineSplitter, runJsonl, signedIn } from "./cli.js";
+export { localAvailability, chosenCommand, desktopAppPaths, type DesktopApp } from "./availability.js";
+export { claudeLentModel, LENT_IDLE_MS } from "./lend.js";
+export { cliLentModel, NotSignedIn, SIGN_IN_RECHECK_MS, type CliAnswer } from "./lend-cli.js";
+export { MCP_NAME, claudeConfigDirOf, claudeConfigDirs, claudeMcpLink, claudeProfileEnv, claudeProjectServerApproval, claudeUserFile, userMcpLink, type UserMcpConfig } from "./mcp-link.js";
+export { bashRuleMatches, claudeCommands, userSettingsFile } from "./permissions.js";
+export { CliLocator, localCli, launchFor, bundledLaunch, spawnCli, stopCli, cliReason, describeRun, fileNames, shimTarget, cmdArgument, cmdLine, parseRegPath, expandWindowsVars, splitPath, knownDirs, type BundledCli, type CliHost, type CliLaunch, type CliRunResult } from "./locate.js";
+export { promptOf, sessionSystem, staticSystem, turnPrompt } from "./system.js";
+export { RuntimePool, runtimeFingerprint, runtimeDirectory, bindTurn, type Runtime } from "./runtime.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/lend-cli.d.ts

@@ -0,0 +1,30 @@
+import { type ChatRequest, type LentModel } from "@tomradex/llm";
+/** The CLI said, in its own words, that it is not signed in. */
+export declare class NotSignedIn extends Error {
+}
+export interface CliAnswer {
+    text: string;
+    /** All of the input, what the cache read included. */
+    inputTokens: number;
+    cacheReadTokens?: number;
+    outputTokens: number;
+}
+/** A CLI found signed out, or whose check said nothing clear, is asked again after this long. */
+export declare const SIGN_IN_RECHECK_MS = 30000;
+/**
+ * A lent model over a CLI with no sign-in status command, each call a process
+ * of its own. Whether it is signed in is learned by asking: one tiny prompt the
+ * first time (a signed-out CLI refuses it at once, before any model call), then
+ * what each call says. Only a clear "not signed in" makes it unready.
+ */
+export declare function cliLentModel(opts: {
+    id: string;
+    title: string;
+    rank?: number;
+    /** Whether the CLI is there to run. */
+    found(): Promise<boolean>;
+    /** One answer; throws NotSignedIn when the CLI says it is not signed in. */
+    ask(request: ChatRequest, signal?: AbortSignal): Promise<CliAnswer>;
+    recheckMs?: number;
+}): LentModel;
+//# sourceMappingURL=lend-cli.d.ts.map

package/dist/lend.d.ts

@@ -0,0 +1,14 @@
+import type { Context } from "cordis";
+import { type LentModel } from "@tomradex/llm";
+/** A kept session that answered nothing for this long exits; the next call starts one again. */
+export declare const LENT_IDLE_MS: number;
+/**
+ * The signed-in Claude Code answering worker calls. One session is kept warm
+ * between calls; a call arriving while it is busy runs in a process of its own.
+ */
+export declare function claudeLentModel(ctx: Context, ready: () => Promise<boolean>, opts?: {
+    idleMs?: number;
+}): LentModel & {
+    close(): void;
+};
+//# sourceMappingURL=lend.d.ts.map

package/dist/locate.d.ts

@@ -0,0 +1,146 @@
+import { type ChildProcess, type SpawnOptions } from "node:child_process";
+import type { CliCheck, LocalCliStatus } from "@tomradex/agent";
+/**
+ * Finding a local agent's CLI the way a person's terminal would, and starting
+ * it the way that terminal would. An app opened from the Dock or the Start menu
+ * has a thinner PATH than the terminal the CLI was installed from, and on
+ * Windows npm installs `codex.cmd`, which Node can neither find without PATHEXT
+ * nor start without a shell.
+ */
+/** What the locator needs from the machine; tests swap it for a fake one. */
+export interface CliHost {
+    platform: NodeJS.Platform;
+    arch: string;
+    env: NodeJS.ProcessEnv;
+    home: string;
+    /** PATH as a new terminal would see it now: the registry on Windows, a login shell elsewhere. */
+    freshPath(): Promise<string[]>;
+    /** Where `npm i -g` puts commands, if npm answers. */
+    npmPrefix(): Promise<string | null>;
+    /** The CLI's path inside WSL, when Windows has WSL and the CLI is installed there. */
+    wsl(name: string): Promise<string | null>;
+    /** Where Windows' installed-apps list says apps whose display name matches were installed; none elsewhere. */
+    installs(displayName: RegExp): Promise<string[]>;
+    run(launch: CliLaunch, args: string[], timeoutMs: number): Promise<CliRunResult>;
+}
+export interface CliRunResult {
+    code: number | null;
+    stdout: string;
+    stderr: string;
+    /** Set when there was no exit to report: the file did not start, or it was stopped for taking too long. */
+    error?: {
+        code?: string | number | null;
+        killed?: boolean;
+        message: string;
+    };
+}
+/** How to start one resolved CLI file. */
+export interface CliLaunch {
+    file: string;
+    /** The program and arguments that run `file` with these arguments. */
+    argv(args: string[]): {
+        command: string;
+        args: string[];
+        verbatim?: boolean;
+    };
+    /** The environment to start it with: the CLI's own folder (and its node) first on PATH. */
+    env(base?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+}
+export declare function splitPath(value: string | undefined, platform: NodeJS.Platform): string[];
+/** The file names a bare command may have in one directory: PATHEXT's runnable kinds on Windows. */
+export declare function fileNames(name: string, platform: NodeJS.Platform, pathext?: string): string[];
+/** `%APPDATA%\npm` → the folder itself. Unknown names stay as written, like cmd does. */
+export declare function expandWindowsVars(value: string, env: NodeJS.ProcessEnv): string;
+/** The Path value out of `reg query … /v Path`. */
+export declare function parseRegPath(output: string): string | null;
+/**
+ * The install folders in `reg query …\Uninstall /s` output of the apps whose
+ * DisplayName matches: InstallLocation, else the folder of the icon or the uninstaller.
+ */
+export declare function parseRegInstalls(output: string, displayName: RegExp): string[];
+/**
+ * npm, pnpm and yarn install a command on Windows as a `.cmd` file that runs
+ * `node <script> %*`. Read the script out of it, so the CLI can be started as
+ * node + script — no cmd.exe in between to mangle arguments or outlive a cancel.
+ */
+export declare function shimTarget(shim: string, text: string): string | null;
+/** One argument for `cmd /s /c "…"` reaching a batch file that hands `%*` on — the escaping cross-spawn uses. */
+export declare function cmdArgument(arg: string): string;
+export declare function cmdLine(file: string, args: string[]): string;
+/** How to start `file` on this platform, with `dirs` put ahead of PATH for the CLI and whatever it starts. */
+export declare function launchFor(file: string, host: Pick<CliHost, "platform" | "env">, dirs?: string[], depth?: number): CliLaunch;
+/** A CLI shipped inside a desktop app as a Node script, which that app's own Electron binary runs as Node. */
+export interface BundledCli {
+    file: string;
+    /** The app's binary that runs `file` as Node; absent when `file` is the app's own launcher script, run as it is. */
+    runtime?: string;
+}
+/** Where a desktop app may keep its copy of the CLI — every place looked, installed there or not. */
+export type BundledApps = (host: CliHost) => BundledCli[] | Promise<BundledCli[]>;
+/** How to start a bundled CLI: the app's binary with `ELECTRON_RUN_AS_NODE`, so the machine needs no Node of its own. */
+export declare function bundledLaunch(cli: Required<BundledCli>, host: Pick<CliHost, "platform" | "env">): CliLaunch;
+/** Start a resolved CLI: no console window on Windows, its own folder first on PATH. */
+export declare function spawnCli(launch: CliLaunch, args: string[], options?: SpawnOptions & {
+    env?: NodeJS.ProcessEnv;
+}): ChildProcess;
+/** On Windows a signal reaches only the process itself; a CLI's own children (node → codex.exe) need the tree taken down. */
+export declare function stopCli(child: ChildProcess, signal?: NodeJS.Signals): void;
+/** The login shell did not answer in time, so the folders its startup files add to PATH are unknown. */
+export declare class ShellTimeout extends Error {
+    readonly shell: string;
+    constructor(shell: string);
+}
+export declare const machineHost: () => CliHost;
+/** Where installers and version managers put commands when PATH does not (yet) say so. */
+export declare function knownDirs(host: CliHost): Promise<string[]>;
+/** The version a CLI printed, or why it did not answer — short enough for a settings row. */
+export declare function describeRun(result: CliRunResult, timeoutMs: number): {
+    ok: boolean;
+    detail: string;
+};
+/**
+ * One locator per CLI for the whole app, so the engine's views and its turns
+ * share what was found. `bundled` names copies that ship inside a desktop app,
+ * tried after every folder a terminal would search.
+ */
+export declare function localCli(name: string, opts?: {
+    bundled?: BundledApps;
+}): CliLocator;
+/**
+ * Looks for one CLI — `claude`, `codex` — in the order a person would expect:
+ * the path they chose, PATH, PATH as a new terminal sees it, then the folders
+ * installers use. Each file found is run with `--version`; the first that
+ * answers wins. Results are kept briefly so every view and turn does not spawn.
+ */
+export declare class CliLocator {
+    readonly name: string;
+    private host;
+    private timeoutMs;
+    private bundled;
+    private cache;
+    private pending;
+    constructor(name: string, host?: CliHost, timeoutMs?: number, bundled?: BundledApps);
+    private apps?;
+    findBundled(bundled: BundledApps): void;
+    private bundledApps;
+    /** How to start `file`: through its app's runtime when it is a bundled copy, the way a terminal would otherwise. */
+    private launchOf;
+    /** A command setting that names something other than the default is the person's choice. */
+    manualOf(command: string | undefined): string | undefined;
+    locate(opts?: {
+        manual?: string;
+        fresh?: boolean;
+    }): Promise<LocalCliStatus>;
+    /** How a turn starts the CLI that `command` names — the located file when there is one. */
+    launch(command?: string): Promise<CliLaunch>;
+    check(file: string): Promise<CliCheck>;
+    /** Runs `args` on the CLI `command` names — a sign-in check. */
+    run(command: string | undefined, args: string[], timeoutMs: number, envFor?: (env: NodeJS.ProcessEnv) => NodeJS.ProcessEnv): Promise<CliRunResult>;
+    private found;
+    private manualCandidates;
+    private inDirs;
+    private search;
+}
+/** The English line for logs and errors; the app words each state itself. */
+export declare function cliReason(title: string, cli: LocalCliStatus, install: string): string;
+//# sourceMappingURL=locate.d.ts.map

package/dist/mcp-link.d.ts

@@ -0,0 +1,45 @@
+import type { Context } from "cordis";
+import type { EngineMcpLink } from "@tomradex/agent";
+import type { CliLocator } from "./locate.js";
+export declare const MCP_NAME = "tomrade";
+/** What a person (or a test) needs to know about one agent's user-level MCP configuration. */
+export interface UserMcpConfig {
+    /** The file the agent keeps it in. */
+    file(profile?: string): string;
+    /** The address its `tomrade` entry names; null when there is none; throws when the file cannot be read. */
+    configuredUrl(profile?: string): string | null;
+    add(url: string): string[];
+    remove(): string[];
+    cli: CliLocator;
+    engineId: string;
+    /** An agent with several configuration folders: each one, the agent's own first. */
+    profiles?(): string[];
+    /** The environment that points the CLI at `profile`, and the same as a shell prefix (empty for the agent's own). */
+    profileEnv?(profile: string): {
+        env(base: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+        prefix: string;
+    };
+}
+/** Status reads the agent's file; changes go through its own CLI, which owns that file's format. */
+export declare function userMcpLink(ctx: Context, config: UserMcpConfig): EngineMcpLink;
+/** Claude Code keeps user-scope servers in `.claude.json`, beside CLAUDE_CONFIG_DIR's settings or in the home folder. */
+export declare function claudeUserFile(env?: NodeJS.ProcessEnv): string;
+/** The environment Claude Code needs to run under one config folder: none for the default `~/.claude`. */
+export declare function claudeProfileEnv(dir: string, home?: string): NodeJS.ProcessEnv;
+/** The config folder a session ran under, from its transcript: `<dir>/projects/<folder>/<session>.jsonl`. */
+export declare function claudeConfigDirOf(transcript: string): string | null;
+/**
+ * Every Claude Code config folder in use here, the one this process would use
+ * first. Several accounts are often one alias each (`CLAUDE_CONFIG_DIR=~/.claude-work claude`),
+ * which an app opened from the Dock never sees: such folders are found beside
+ * the default one, and from the transcripts sessions report through their hooks.
+ */
+export declare function claudeConfigDirs(env?: NodeJS.ProcessEnv, home?: string, seen?: Iterable<string>): string[];
+export declare function claudeMcpLink(ctx: Context, cli: CliLocator): EngineMcpLink;
+/**
+ * Whether Claude Code will load a repository's `.mcp.json` server: it asks
+ * once per folder, and remembers the answer in `.claude.json` or in a
+ * settings file. `pending` until the person answers.
+ */
+export declare function claudeProjectServerApproval(dir: string, name?: string, env?: NodeJS.ProcessEnv): "approved" | "rejected" | "pending";
+//# sourceMappingURL=mcp-link.d.ts.map

package/dist/permissions.d.ts

@@ -0,0 +1,7 @@
+import type { EngineCommands } from "@tomradex/agent";
+export declare const userSettingsFile: () => string;
+/** Claude Code's Bash rule forms: `Bash`, `Bash(cmd)`, `Bash(prefix:*)` and `*` wildcards (`Bash(gh pr merge *)`). */
+export declare function bashRuleMatches(rule: string, command: string): boolean;
+/** Read Claude Code's own settings files the way the CLI layers them, and add an allow rule to the user's. */
+export declare const claudeCommands: EngineCommands;
+//# sourceMappingURL=permissions.d.ts.map

package/dist/runtime.d.ts

@@ -0,0 +1,48 @@
+import type { Context } from "cordis";
+import { type TurnInput, type TurnIO, type TurnResult } from "@tomradex/agent";
+export interface Runtime {
+    readonly token: string;
+    readonly cwd: string;
+    alive: boolean;
+    busy: boolean;
+    session?: string;
+    close(): void;
+    turn(input: TurnInput, io: TurnIO, warm: boolean): Promise<TurnResult>;
+}
+/**
+ * Warm runtimes per thread. `limit` bounds the idle ones: a turn is never refused for a slot,
+ * and once turns finish the least recently used idle runtimes past it are closed.
+ * Session history belongs to the provider on disk.
+ */
+export declare class RuntimePool<T extends Runtime> {
+    private readonly limit;
+    private readonly idleMs;
+    private entries;
+    constructor(limit?: number, idleMs?: number);
+    run(key: string, fingerprint: string, create: () => T, input: TurnInput, io: TurnIO): Promise<TurnResult>;
+    /** Close the least recently used idle runtimes past `limit`. */
+    private trim;
+    evict(key: string): void;
+    close(): void;
+}
+/** Hash secrets; never persist or log the fingerprint inputs. */
+export declare function runtimeFingerprint(input: TurnInput, io: TurnIO, url: string | null): string;
+export declare function runtimeDirectory(input: TurnInput): {
+    token: string;
+    cwd: string;
+    dispose(): void;
+};
+export declare function bindTurn(ctx: Context, token: string, io: TurnIO, input: TurnInput): {
+    asked: () => boolean;
+    release(): Promise<void>;
+};
+/** Producer remains open between user turns; closing releases a waiting reader. */
+export declare class MessageQueue<T> implements AsyncIterable<T> {
+    private values;
+    private waiter?;
+    private closed;
+    push(value: T): void;
+    close(): void;
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+}
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.js

@@ -0,0 +1 @@
+throw new Error("@tomradex/engine-claude-code is Tomrade's own code: a full-mode plugin gets the running app's copy, so load the plugin in Tomrade");

package/dist/sdk.d.ts

@@ -0,0 +1,37 @@
+import { type Options } from "@anthropic-ai/claude-agent-sdk";
+import type { Context } from "cordis";
+import type { TurnIO, TurnInput, TurnResult } from "@tomradex/agent";
+import { type CliLaunch } from "./locate.js";
+import { type Runtime } from "./runtime.js";
+/**
+ * The SDK starts a native path itself; a Windows `.cmd` shim needs our launch
+ * (node + script), which the SDK only takes as a custom spawn.
+ */
+export declare function sdkLaunch(launch: CliLaunch, onStderr?: (data: string) => void): Pick<Options, "pathToClaudeCodeExecutable" | "spawnClaudeCodeProcess">;
+export declare class ClaudeRuntime implements Runtime {
+    private ctx;
+    token: string;
+    cwd: string;
+    alive: boolean;
+    busy: boolean;
+    session?: string;
+    /** The files index this session was opened with, so a later turn can notice it went stale. */
+    indexDigest: string | null;
+    private queue;
+    private query?;
+    private onMessage?;
+    private onFailure?;
+    private cost;
+    /** This session was started without resume and has not had its first message yet. */
+    private fresh;
+    /** Cumulative counters from the last result; the SDK reports running totals, so a turn is the difference. */
+    private tokens;
+    private activeIO?;
+    private stderr;
+    private keepStderr;
+    constructor(ctx: Context, input: TurnInput);
+    close(): void;
+    turn(input: TurnInput, io: TurnIO, warm: boolean): Promise<TurnResult>;
+    private consume;
+}
+//# sourceMappingURL=sdk.d.ts.map

package/dist/system.d.ts

@@ -0,0 +1,18 @@
+import { type TurnIO, type TurnInput } from "@tomradex/agent";
+export declare function staticSystem(agentName: string): string;
+/**
+ * What an external agent is told once, when its session opens: its identity,
+ * the house rules, and the index of the project's files. The index belongs
+ * here and not in the per-turn prompt — this text is cached by the provider,
+ * while everything in a user message is paid for again on every turn.
+ */
+export declare function sessionSystem(input: TurnInput, agentName: string): string;
+/**
+ * The per-turn state. `staleIndex` is set when the files have moved on since
+ * the session's index was written, which is one line rather than a fresh copy.
+ */
+export declare const turnPrompt: (input: TurnInput, io: TurnIO, opts?: {
+    staleIndex?: boolean;
+}) => string;
+export declare const promptOf: (input: TurnInput) => string;
+//# sourceMappingURL=system.d.ts.map

package/dist/usage.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Token accounting for a Claude Code turn. Live numbers come from the API's
+ * own streaming events: message_start carries the request's prompt tokens,
+ * cache included, and message_delta the reply so far. Final numbers come from
+ * the result's modelUsage — every model call, cumulative across the turns one
+ * process serves, so a turn is the difference from the previous result — with
+ * the main-loop `usage` as the fallback for builds that lack it. Input means
+ * every prompt token the model processed: cached ones are context, not free.
+ */
+export interface Tokens {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+}
+export interface ApiUsage {
+    input_tokens?: number | null;
+    output_tokens?: number | null;
+    cache_read_input_tokens?: number | null;
+    cache_creation_input_tokens?: number | null;
+}
+interface ModelTokens {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadInputTokens: number;
+    cacheCreationInputTokens: number;
+}
+export interface ResultCounters {
+    usage?: ApiUsage;
+    modelUsage?: Record<string, ModelTokens>;
+}
+/** Every prompt token the model read this turn, cached or not. */
+export declare const promptTokens: (t: Tokens) => number;
+/** Whether the provider said anything about caching; absent fields stay absent in the metrics. */
+export declare const cacheKnown: (r: ResultCounters) => boolean;
+/**
+ * This turn's counters, and the cumulative figure to diff the next result
+ * against (null when the result carried no modelUsage).
+ */
+export declare function turnTokens(result: ResultCounters, previous: Tokens | null): {
+    turn: Tokens;
+    cumulative: Tokens | null;
+};
+/**
+ * The running total of one turn, fed by streaming events as they arrive. Each
+ * stream (the main loop, every subagent) has one open request at a time. One
+ * that drops mid-stream is sent again whole, so its figures leave the total
+ * when the retry is announced instead of counting the prompt twice.
+ */
+export declare class LiveUsage {
+    private prompt;
+    private finished;
+    /** Each stream's open request: its prompt, and its reply so far. */
+    private open;
+    /** The total after this event, or null when the event says nothing about tokens. */
+    observe(event: {
+        type?: string;
+        message?: {
+            usage?: ApiUsage;
+        };
+        usage?: ApiUsage;
+    } | undefined, stream?: string | null): {
+        inputTokens: number;
+        outputTokens: number;
+    } | null;
+    /** The main loop's open request failed and will be sent again. */
+    retry(): {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    private close;
+    private total;
+}
+export {};
+//# sourceMappingURL=usage.d.ts.map

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@tomradex/engine-claude-code",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.15.0",
+  "type": "module",
+  "author": "Haoyuan Tang",
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "Apache-2.0",
+  "description": "Claude Agent SDK conductor with one reusable local runtime per hot thread, MCP tools, and resumable sessions — declarations for full-mode plugins; Tomrade provides the code at run time",
+  "keywords": [
+    "tomrade",
+    "tomrade-plugin",
+    "types"
+  ],
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/runtime.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@tomradex/agent": "0.15.0",
+    "@tomradex/llm": "0.15.0",
+    "@tomradex/mcp": "0.15.0",
+    "cordis": "4.0.0-rc.8",
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "@anthropic-ai/claude-agent-sdk": "0.3.263"
+  },
+  "peerDependenciesMeta": {
+    "@anthropic-ai/claude-agent-sdk": {
+      "optional": true
+    }
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.