@edukors/ai-cli 0.0.0-stage → 0.1.1

package/dist/platform/login.d.ts

@@ -0,0 +1,16 @@
+import type { AccountContext } from "../provider.js";
+import { type CommandSpec, type RunResult } from "./process.js";
+/**
+ * Runs a provider's sign-in command. Such commands open the browser and wait
+ * for it; when the browser cannot be opened they print an address instead,
+ * and some then wait for a code pasted on their input. The address goes to
+ * the application (`context.login.prompt`), and a code the user pastes goes
+ * to the command's input, so the whole flow works without a terminal.
+ */
+export interface LoginCommandOptions {
+    /** The sign-in address among everything the command prints. */
+    urlPattern: RegExp;
+    acceptsCode: boolean;
+    timeoutMs?: number;
+}
+export declare function runLoginCommand(spec: CommandSpec, context: AccountContext, options: LoginCommandOptions): Promise<RunResult>;

package/dist/platform/login.js

@@ -0,0 +1,42 @@
+import { AiCliError } from "../errors.js";
+import { ManagedProcess, readLines } from "./process.js";
+const MAX_OUTPUT = 64 << 10;
+export async function runLoginCommand(spec, context, options) {
+    const proc = new ManagedProcess(spec);
+    const spawnError = new Promise((resolve) => proc.child.once("error", resolve));
+    let stdout = "";
+    let offered = false;
+    const onLine = (line) => {
+        if (stdout.length < MAX_OUTPUT)
+            stdout += line + "\n";
+        if (offered)
+            return;
+        const url = line.match(options.urlPattern)?.[0];
+        if (!url)
+            return;
+        offered = true;
+        // Wait for the code before offering the address: an application may answer at once.
+        if (options.acceptsCode && context.login) {
+            context.login.code().then((code) => proc.child.stdin.write(`${code}\n`), () => undefined);
+        }
+        context.login?.prompt({ url, acceptsCode: options.acceptsCode });
+    };
+    readLines(proc.child.stdout, onLine);
+    readLines(proc.child.stderr, onLine);
+    let timedOut = false;
+    const timer = setTimeout(() => {
+        timedOut = true;
+        void proc.terminate(500);
+    }, options.timeoutMs ?? 10 * 60_000);
+    const onAbort = () => void proc.terminate(500);
+    context.signal?.addEventListener("abort", onAbort, { once: true });
+    const info = await proc.exited;
+    clearTimeout(timer);
+    context.signal?.removeEventListener("abort", onAbort);
+    if (info.code === null && info.signal === null)
+        throw new AiCliError("PROVIDER_START_FAILED", `could not start ${spec.file}`, { cause: await spawnError });
+    if (context.signal?.aborted)
+        throw new AiCliError("CANCELLED", "sign-in cancelled");
+    return { code: info.code, stdout, stderr: proc.stderr.toString(), timedOut };
+}
+//# sourceMappingURL=login.js.map

package/dist/platform/login.js.map

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

package/dist/platform/paths.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The per-OS-user EDUKORS data directory, shared by every EDUKORS application
+ * on this computer. Resolved by platform convention; `EDUKORS_AI_DATA_DIR`
+ * overrides it (tests, portable installs).
+ */
+export declare function defaultDataDir(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): string;
+/** Stable, filesystem-safe key for an arbitrary document identifier. */
+export declare const documentKey: (documentId: string) => string;
+export declare class DataPaths {
+    readonly root: string;
+    /** Always absolute: provider processes run in other working directories. */
+    constructor(root: string);
+    get registryFile(): string;
+    get locksDir(): string;
+    /** Stored relative to the root in the registry, so the root may move. */
+    accountHomeRelative(accountId: string): string;
+    resolve(relative: string): string;
+    sessionDir(appId: string, documentId: string, accountId: string): string;
+}

package/dist/platform/paths.js

@@ -0,0 +1,46 @@
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+/**
+ * The per-OS-user EDUKORS data directory, shared by every EDUKORS application
+ * on this computer. Resolved by platform convention; `EDUKORS_AI_DATA_DIR`
+ * overrides it (tests, portable installs).
+ */
+export function defaultDataDir(env = process.env, platform = process.platform) {
+    const override = env.EDUKORS_AI_DATA_DIR;
+    if (override)
+        return resolve(override);
+    const home = env.HOME || env.USERPROFILE || homedir();
+    if (platform === "darwin")
+        return join(home, "Library", "Application Support", "EDUKORS");
+    // Local, not roaming: account directories hold machine-bound provider state.
+    if (platform === "win32")
+        return join(env.LOCALAPPDATA || join(home, "AppData", "Local"), "EDUKORS");
+    return join(env.XDG_DATA_HOME && isAbsolute(env.XDG_DATA_HOME) ? env.XDG_DATA_HOME : join(home, ".local", "share"), "edukors");
+}
+/** Stable, filesystem-safe key for an arbitrary document identifier. */
+export const documentKey = (documentId) => createHash("sha256").update(documentId).digest("hex").slice(0, 24);
+export class DataPaths {
+    root;
+    /** Always absolute: provider processes run in other working directories. */
+    constructor(root) {
+        this.root = resolve(root);
+    }
+    get registryFile() {
+        return join(this.root, "ai", "registry.json");
+    }
+    get locksDir() {
+        return join(this.root, "ai", "locks");
+    }
+    /** Stored relative to the root in the registry, so the root may move. */
+    accountHomeRelative(accountId) {
+        return join("ai", "accounts", accountId);
+    }
+    resolve(relative) {
+        return join(this.root, relative);
+    }
+    sessionDir(appId, documentId, accountId) {
+        return join(this.root, "ai", "sessions", appId, documentKey(documentId), accountId);
+    }
+}
+//# sourceMappingURL=paths.js.map

package/dist/platform/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/platform/paths.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEtD;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,MAAyB,OAAO,CAAC,GAAG,EAAE,WAA4B,OAAO,CAAC,QAAQ;IAC/G,MAAM,QAAQ,GAAG,GAAG,CAAC,mBAAmB,CAAC;IACzC,IAAI,QAAQ;QAAE,OAAO,OAAO,CAAC,QAAQ,CAAC,CAAC;IACvC,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,WAAW,IAAI,OAAO,EAAE,CAAC;IACtD,IAAI,QAAQ,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,qBAAqB,EAAE,SAAS,CAAC,CAAC;IAC1F,6EAA6E;IAC7E,IAAI,QAAQ,KAAK,OAAO;QAAE,OAAO,IAAI,CAAC,GAAG,CAAC,YAAY,IAAI,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,SAAS,CAAC,CAAC;IACrG,OAAO,IAAI,CAAC,GAAG,CAAC,aAAa,IAAI,UAAU,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,SAAS,CAAC,CAAC;AACjI,CAAC;AAED,wEAAwE;AACxE,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,UAAkB,EAAU,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAE9H,MAAM,OAAO,SAAS;IACX,IAAI,CAAS;IAEtB,4EAA4E;IAC5E,YAAY,IAAY;QACtB,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAED,IAAI,YAAY;QACd,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,eAAe,CAAC,CAAC;IAChD,CAAC;IAED,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IACxC,CAAC;IAED,yEAAyE;IACzE,mBAAmB,CAAC,SAAiB;QACnC,OAAO,IAAI,CAAC,IAAI,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC;IAC3C,CAAC;IAED,OAAO,CAAC,QAAgB;QACtB,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACnC,CAAC;IAED,UAAU,CAAC,KAAa,EAAE,UAAkB,EAAE,SAAiB;QAC7D,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,CAAC,UAAU,CAAC,EAAE,SAAS,CAAC,CAAC;IACtF,CAAC;CACF"}

package/dist/platform/process.d.ts

@@ -0,0 +1,55 @@
+import { type ChildProcessWithoutNullStreams } from "node:child_process";
+import type { Readable } from "node:stream";
+export interface CommandSpec {
+    file: string;
+    args?: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+}
+/** Keeps the last `limit` characters of a stream. */
+export declare class Tail {
+    private readonly limit;
+    private text;
+    constructor(limit?: number);
+    push(chunk: string): void;
+    toString(): string;
+}
+export interface ExitInfo {
+    code: number | null;
+    signal: NodeJS.Signals | null;
+}
+export declare class ManagedProcess {
+    readonly child: ChildProcessWithoutNullStreams;
+    readonly stderr: Tail;
+    readonly exited: Promise<ExitInfo>;
+    private exitInfo;
+    constructor(spec: CommandSpec);
+    get running(): boolean;
+    /** Writes one JSON object followed by a newline. Returns false if the process is gone. */
+    writeLine(message: unknown): boolean;
+    /** Ends the whole process tree: a polite signal, then a forced one after `graceMs`. */
+    terminate(graceMs?: number): Promise<ExitInfo>;
+}
+/** Kills every process this library started. Safe to call from `process.on("exit")`. */
+export declare function killAllSync(): void;
+export interface RunResult {
+    code: number | null;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+}
+/** Runs a short command to completion with a timeout and bounded output. Never rejects for a non-zero exit. */
+export declare function runCommand(spec: CommandSpec & {
+    timeoutMs?: number;
+    maxOutput?: number;
+    signal?: AbortSignal;
+    input?: string;
+}): Promise<RunResult>;
+/**
+ * Splits a stream into lines. A line longer than `maxLineBytes` is discarded
+ * and reported, so a misbehaving process cannot exhaust memory.
+ */
+export declare function readLines(stream: Readable, onLine: (line: string) => void, options?: {
+    maxLineBytes?: number;
+    onOverflow?: () => void;
+}): void;

package/dist/platform/process.js

@@ -0,0 +1,186 @@
+import { spawn, spawnSync } from "node:child_process";
+import { AiCliError } from "../errors.js";
+/**
+ * Process lifecycle for provider CLIs: bounded output, timeouts and reliable
+ * termination of the whole process tree.
+ */
+const WINDOWS = process.platform === "win32";
+/** Windows batch shims (npm installs `.cmd` files) cannot be spawned without a shell. */
+const needsShell = (file) => WINDOWS && /\.(cmd|bat)$/i.test(file);
+/** Quotes an argument for cmd.exe. Arguments come from adapters, never from users. */
+const cmdQuote = (arg) => (/^[\w\-./:=@\\]+$/.test(arg) ? arg : `"${arg.replace(/(\\*)"/g, '$1$1\\"').replace(/%/g, "%%")}"`);
+function spawnRaw(spec) {
+    const args = spec.args ?? [];
+    const shell = needsShell(spec.file);
+    return spawn(shell ? `"${spec.file}"` : spec.file, shell ? args.map(cmdQuote) : args, {
+        env: spec.env ?? process.env,
+        cwd: spec.cwd,
+        shell,
+        windowsHide: true,
+        // Own process group on POSIX, so the whole tree can be signalled.
+        detached: !WINDOWS,
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+}
+/** Keeps the last `limit` characters of a stream. */
+export class Tail {
+    limit;
+    text = "";
+    constructor(limit = 16_384) {
+        this.limit = limit;
+    }
+    push(chunk) {
+        this.text += chunk;
+        if (this.text.length > this.limit)
+            this.text = this.text.slice(-this.limit);
+    }
+    toString() {
+        return this.text;
+    }
+}
+const live = new Set();
+export class ManagedProcess {
+    child;
+    stderr = new Tail();
+    exited;
+    exitInfo = null;
+    constructor(spec) {
+        this.child = spawnRaw(spec);
+        this.child.stderr.setEncoding("utf8").on("data", (chunk) => this.stderr.push(chunk));
+        this.child.stdin.on("error", () => undefined);
+        live.add(this);
+        this.exited = new Promise((resolve) => {
+            const done = (info) => {
+                if (this.exitInfo)
+                    return;
+                this.exitInfo = info;
+                live.delete(this);
+                resolve(info);
+            };
+            this.child.once("exit", (code, signal) => done({ code, signal }));
+            this.child.once("error", () => done({ code: null, signal: null }));
+        });
+    }
+    get running() {
+        return this.exitInfo === null;
+    }
+    /** Writes one JSON object followed by a newline. Returns false if the process is gone. */
+    writeLine(message) {
+        if (!this.running || this.child.stdin.destroyed)
+            return false;
+        this.child.stdin.write(JSON.stringify(message) + "\n");
+        return true;
+    }
+    /** Ends the whole process tree: a polite signal, then a forced one after `graceMs`. */
+    async terminate(graceMs = 2_000) {
+        if (!this.running)
+            return this.exitInfo;
+        try {
+            this.child.stdin.end();
+        }
+        catch {
+            /* already closed */
+        }
+        killTree(this.child.pid, "SIGTERM");
+        const timer = new Promise((r) => setTimeout(() => r(null), graceMs).unref());
+        if ((await Promise.race([this.exited, timer])) === null)
+            killTree(this.child.pid, "SIGKILL");
+        return this.exited;
+    }
+}
+function killTree(pid, signal) {
+    if (!pid)
+        return;
+    if (WINDOWS) {
+        spawnSync("taskkill", ["/pid", String(pid), "/T", "/F"], { windowsHide: true, stdio: "ignore" });
+        return;
+    }
+    try {
+        process.kill(-pid, signal);
+    }
+    catch {
+        try {
+            process.kill(pid, signal);
+        }
+        catch {
+            /* already gone */
+        }
+    }
+}
+/** Kills every process this library started. Safe to call from `process.on("exit")`. */
+export function killAllSync() {
+    for (const proc of live)
+        killTree(proc.child.pid, "SIGKILL");
+    live.clear();
+}
+process.once("exit", killAllSync);
+/** Runs a short command to completion with a timeout and bounded output. Never rejects for a non-zero exit. */
+export async function runCommand(spec) {
+    const maxOutput = spec.maxOutput ?? 1 << 20;
+    let proc;
+    try {
+        proc = new ManagedProcess(spec);
+    }
+    catch (e) {
+        throw new AiCliError("PROVIDER_START_FAILED", `could not start ${spec.file}`, { cause: e });
+    }
+    let stdout = "";
+    proc.child.stdout.setEncoding("utf8").on("data", (chunk) => {
+        if (stdout.length < maxOutput)
+            stdout += chunk.slice(0, maxOutput - stdout.length);
+    });
+    if (spec.input !== undefined)
+        proc.child.stdin.end(spec.input);
+    let timedOut = false;
+    const timer = setTimeout(() => {
+        timedOut = true;
+        void proc.terminate(500);
+    }, spec.timeoutMs ?? 15_000);
+    const onAbort = () => void proc.terminate(500);
+    spec.signal?.addEventListener("abort", onAbort, { once: true });
+    const spawnError = new Promise((resolve) => proc.child.once("error", resolve));
+    const info = await proc.exited;
+    clearTimeout(timer);
+    spec.signal?.removeEventListener("abort", onAbort);
+    if (info.code === null && info.signal === null) {
+        throw new AiCliError("PROVIDER_START_FAILED", `could not start ${spec.file}`, { cause: await spawnError });
+    }
+    if (spec.signal?.aborted)
+        throw new AiCliError("CANCELLED", "cancelled");
+    return { code: info.code, stdout, stderr: proc.stderr.toString(), timedOut };
+}
+/**
+ * Splits a stream into lines. A line longer than `maxLineBytes` is discarded
+ * and reported, so a misbehaving process cannot exhaust memory.
+ */
+export function readLines(stream, onLine, options = {}) {
+    const max = options.maxLineBytes ?? 8 << 20;
+    let buffer = "";
+    let discarding = false;
+    stream.setEncoding("utf8");
+    stream.on("data", (chunk) => {
+        let start = 0;
+        for (let i = chunk.indexOf("\n"); i !== -1; i = chunk.indexOf("\n", start)) {
+            const piece = chunk.slice(start, i);
+            if (!discarding)
+                onLine((buffer + piece).replace(/\r$/, ""));
+            buffer = "";
+            discarding = false;
+            start = i + 1;
+        }
+        if (discarding)
+            return;
+        buffer += chunk.slice(start);
+        if (buffer.length > max) {
+            buffer = "";
+            discarding = true;
+            options.onOverflow?.();
+        }
+    });
+    stream.on("end", () => {
+        if (buffer && !discarding)
+            onLine(buffer);
+        buffer = "";
+    });
+}
+//# sourceMappingURL=process.js.map

package/dist/platform/process.js.map

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

package/dist/provider.d.ts

@@ -0,0 +1,156 @@
+import type { ActivityPhase, Usage } from "./events.js";
+import type { ScopedLog } from "./diagnostics.js";
+import type { ToolResult, ToolSpec } from "./tools.js";
+/**
+ * The contract each provider adapter implements. Adapters translate one
+ * provider's CLI and protocol into this; the library handles accounts,
+ * session identity, late events, tool routing and errors around it.
+ *
+ * Optional operations are capabilities, not simulations: an adapter that
+ * cannot report usage says so, and the library reports usage as unavailable.
+ */
+export type DetectionStatus = "ready" | "missing" | "incompatible" | "error";
+export interface Detection {
+    providerId: string;
+    status: DetectionStatus;
+    executable?: string;
+    version?: string;
+    /** The minimum version this adapter supports, when the installed one is too old. */
+    requiredVersion?: string;
+    detail?: string;
+}
+export interface Capabilities {
+    /** How the user signs in. `external` means the provider's own tooling must be used. */
+    login: "browser" | "terminal" | "external";
+    /** Account state can be read without sending a model request. */
+    accountStatus: boolean;
+    /** Separate accounts of this provider are verified to be isolated. */
+    multiAccount: boolean;
+    logout: boolean;
+    /** Conversations can be resumed after the provider process ends. */
+    persistentSessions: boolean;
+    models: boolean;
+    efforts: boolean;
+    usage: boolean;
+    tools: boolean;
+    questions: boolean;
+    /** Model or effort can change in an open session. */
+    liveOptions: boolean;
+}
+export type AccountState = "connected" | "disconnected" | "expired" | "unknown";
+export interface AccountStatus {
+    state: AccountState;
+    /** A display identity (e-mail, organization) only when the provider exposes one. */
+    identity?: string;
+    detail?: string;
+}
+export interface ModelInfo {
+    id: string;
+    label?: string;
+    efforts?: string[];
+    default?: boolean;
+}
+export interface SessionOptions {
+    model?: string;
+    effort?: string;
+}
+/** An address the user can open to sign in, offered while a sign-in runs. */
+export interface LoginPrompt {
+    url: string;
+    /** The page ends with a code the user pastes back (see `AiCli.submitLoginCode`). */
+    acceptsCode: boolean;
+}
+/** How a sign-in reaches the user while it runs. Present only during `connectAccount`. */
+export interface LoginChannel {
+    prompt(prompt: LoginPrompt): void;
+    /** Resolves with the code the user pasted; rejects if the sign-in is cancelled. */
+    code(): Promise<string>;
+}
+/** What an adapter receives for anything account-related. */
+export interface AccountContext {
+    accountId: string;
+    label: string;
+    /** An application-managed directory reserved for this account's provider configuration and credentials. */
+    homeDir: string;
+    detection: Detection;
+    log: ScopedLog;
+    signal?: AbortSignal;
+    login?: LoginChannel;
+}
+/** One of the user's MCP servers, already connected by the library, as a provider offers it. */
+export interface ExternalServer {
+    /** Letters, digits, `_` and `-`: the name the model sees (`mcp__<name>__<tool>`). */
+    name: string;
+    tools: ToolSpec[];
+}
+export interface SessionContext extends AccountContext {
+    appId: string;
+    documentId: string;
+    /** Scratch space for this application, document and account; never shared between documents. */
+    workDir: string;
+    instructions: string;
+    tools: ToolSpec[];
+    /** The user's MCP servers; calls to them go through `TurnSink.callExternal`. */
+    externalServers: ExternalServer[];
+    /** A folder of skills (`<name>/SKILL.md`) the application offers; no other skill is enabled. */
+    skillsDir?: string;
+    options: SessionOptions;
+    /** The provider's own session identifier to resume, when the capability allows it. */
+    resumeId?: string;
+}
+export interface SessionHooks {
+    /** The provider process ended outside of a request. */
+    exited(error: Error): void;
+}
+export interface TurnInput {
+    requestId: string;
+    text: string;
+    /** Latest document context the application chose to include with this request. */
+    context?: string;
+}
+/**
+ * Bound to a single request. After the request is interrupted or replaced,
+ * every call becomes a no-op (or is refused), so late output from a provider
+ * cannot reach the application.
+ */
+export interface TurnSink {
+    readonly signal: AbortSignal;
+    text(delta: string): void;
+    activity(phase: ActivityPhase, detail?: string): void;
+    usage(usage: Omit<Usage, "observedAt"> & {
+        observedAt?: string;
+    }): void;
+    callTool(name: string, args: unknown): Promise<ToolResult>;
+    /** A tool of one of the user's MCP servers, authorized by the application first. */
+    callExternal(server: string, tool: string, args: unknown): Promise<ToolResult>;
+    ask(question: {
+        prompt: string;
+        options?: string[];
+    }): Promise<string>;
+}
+export type TurnOutcome = "completed" | "cancelled";
+export interface ProviderSession {
+    /** The provider's own conversation id, used to resume. */
+    readonly resumeId: string | undefined;
+    /** Resolves when the turn ends; rejects with an AiCliError on failure. */
+    send(input: TurnInput, sink: TurnSink): Promise<TurnOutcome>;
+    /** Asks the provider to stop; the pending `send` should settle soon after. */
+    interrupt(): Promise<void>;
+    updateOptions?(options: SessionOptions): Promise<void>;
+    /** Releases everything, including the process tree. Must settle any pending `send`. */
+    close(): Promise<void>;
+}
+export interface ProviderAdapter {
+    readonly id: string;
+    readonly displayName: string;
+    /** Where the user installs the CLI from, for guided setup. */
+    readonly installUrl?: string;
+    detect(log: ScopedLog): Promise<Detection>;
+    capabilities(detection: Detection): Capabilities;
+    connectAccount(context: AccountContext): Promise<AccountStatus>;
+    accountStatus(context: AccountContext): Promise<AccountStatus>;
+    logout?(context: AccountContext): Promise<void>;
+    listModels?(context: AccountContext): Promise<ModelInfo[]>;
+    readUsage?(context: AccountContext): Promise<Usage | null>;
+    openSession(context: SessionContext, hooks: SessionHooks): Promise<ProviderSession>;
+}

package/dist/provider.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":""}

package/dist/providers/claude/adapter.d.ts

@@ -0,0 +1,43 @@
+import type { Options, Query, SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";
+import type { ProviderAdapter } from "../../provider.js";
+/**
+ * Claude Code, through the Claude Agent SDK driving the user's own `claude`.
+ *
+ * Each account is a Claude Code configuration directory of its own
+ * (CLAUDE_CONFIG_DIR, the account's managed home). Claude Code keys its
+ * macOS Keychain entry by that directory, which is what isolates accounts;
+ * this is to be confirmed with live accounts (docs/compatibility.md).
+ *
+ * The session gets the application's tools (in-process MCP server) and
+ * AskUserQuestion, nothing else by default: no shell, no files, no personal
+ * settings, skills or MCP servers.
+ */
+export interface ClaudeProviderOptions {
+    /** Absolute path to `claude`, from advanced settings. */
+    executable?: string;
+    minVersion?: string;
+    /** Claude Code's built-in tools offered besides the application's. */
+    builtInTools?: string[];
+    /** Extra variables for the provider process (advanced settings, tests). */
+    env?: Record<string, string>;
+    /** For tests: an SDK stand-in. */
+    loadSdk?: () => Promise<ClaudeSdk>;
+    /** For tests: where to look for `claude`. */
+    searchEnv?: NodeJS.ProcessEnv;
+    startupTimeoutMs?: number;
+}
+export interface ClaudeSdk {
+    query(params: {
+        prompt: AsyncIterable<SDKUserMessage>;
+        options?: Options;
+    }): Query;
+}
+/** Logged out, Claude Code still reports `tokenSource: "none"`; a source counts only when it names one. */
+export declare function signedIn(account: {
+    email?: string;
+    subscriptionType?: string;
+    tokenSource?: string;
+    apiKeySource?: string;
+    apiProvider?: string;
+} | null | undefined): boolean;
+export declare function createClaudeProvider(options?: ClaudeProviderOptions): ProviderAdapter;