@cjhyy/code-shell-core 0.7.0 → 0.8.0

package/dist/run/RunManager.js

@@ -13,7 +13,7 @@
 import { nanoid } from "nanoid";
 import { logger } from "../logging/logger.js";
 import { RunQueue } from "./RunQueue.js";
-import { EngineRunner } from "./EngineRunner.js";
+import { EngineRunner, } from "./EngineRunner.js";
 import { CheckpointWriter } from "./CheckpointWriter.js";
 import { ArtifactTracker } from "./ArtifactTracker.js";
 import { RunLock } from "./RunLock.js";
@@ -21,6 +21,8 @@ import { Heartbeat } from "./Heartbeat.js";
 import { NoopEvaluator } from "./Evaluator.js";
 import { assertSafeRunFileId, assertSafeRunId } from "./ids.js";
 import { VALID_TRANSITIONS } from "./types.js";
+import { composeArtifactDetectors, resolveCapabilities, } from "../capabilities/index.js";
+import { resolveAgentPreset } from "../preset/index.js";
 function hasOwnString(value, key) {
     return (value !== undefined &&
         Object.prototype.hasOwnProperty.call(value, key) &&
@@ -32,9 +34,19 @@ export class RunManager {
     runner;
     lock;
     heartbeat;
+    /**
+     * Page size for crash-recovery scans (see listAllByStatus).
+     *
+     * Deliberately NOT a constructor option: hosts have no reason to tune it, and
+     * exposing it would invite a caller to re-introduce the UI's 50-row default.
+     * Tests override it to exercise the multi-page loop cheaply.
+     */
+    recoverPageSize = 200;
     evaluator;
     defaultTags;
     defaultMetadata;
+    defaultPreset;
+    artifactDetectors;
     subscribers = new Map();
     abortControllers = new Map();
     /** Active execution handles — used to resolve pending approvals/input while Engine is suspended */
@@ -53,10 +65,13 @@ export class RunManager {
     constructor(config) {
         this.store = config.store;
         this.queue = new RunQueue({ concurrency: config.concurrency ?? 1 });
+        const localCapabilities = config.capabilities ??
+            (isRunExecutor(config.executor) ? [] : (config.executor.capabilities ?? []));
+        const capabilities = resolveCapabilities(localCapabilities);
         // Accept either a RunExecutor instance or an EngineRunnerConfig
         this.runner = isRunExecutor(config.executor)
             ? config.executor
-            : new EngineRunner(config.executor);
+            : new EngineRunner({ ...config.executor, capabilities });
         this.lock = new RunLock({
             runsDir: config.runsDir,
             staleMs: config.staleLockMs,
@@ -68,6 +83,8 @@ export class RunManager {
         this.evaluator = config.evaluator ?? new NoopEvaluator();
         this.defaultTags = config.defaultTags ?? [];
         this.defaultMetadata = config.defaultMetadata ?? {};
+        this.defaultPreset = resolveAgentPreset(undefined, capabilities).name;
+        this.artifactDetectors = composeArtifactDetectors(capabilities);
         // Wire queue executor
         this.queue.setExecutor((runId) => this.executeRun(runId));
     }
@@ -81,7 +98,7 @@ export class RunManager {
         const snapshot = {
             runId,
             objective: input.objective,
-            preset: input.preset ?? "terminal-coding",
+            preset: input.preset ?? this.defaultPreset,
             cwd: input.cwd ?? process.cwd(),
             status: "queued",
             createdAt: now,
@@ -280,14 +297,26 @@ export class RunManager {
      * Returns the IDs of recovered runs.
      */
     async recover() {
-        const runs = await this.store.list({ status: "running" });
+        const runs = await this.listAllByStatus("running");
         const recovered = [];
         for (const run of runs) {
             const processAlive = this.heartbeat.isProcessAlive(run.runId);
             const stale = this.heartbeat.isStale(run.runId);
-            if (processAlive && !stale) {
-                // Still actively running in another process — leave it alone
-                logger.info("run.recover.skip", { runId: run.runId, reason: "process alive" });
+            // Process liveness has VETO power: never recover a run whose owning
+            // process is still alive. A live process can miss a heartbeat window for
+            // benign reasons (a long synchronous tool call, GC pause, a suspended
+            // laptop), and recovering it force-unlocks the lock and re-queues work
+            // that is still executing — the same run then runs twice.
+            //
+            // This matches the documented contract above ("stale AND dead → recover").
+            // The old condition (`processAlive && !stale`) recovered a live-but-stale
+            // run, which was reproducible with a run owning the current PID and a
+            // 60s-old heartbeat.
+            if (processAlive || !stale) {
+                logger.info("run.recover.skip", {
+                    runId: run.runId,
+                    reason: processAlive ? "process alive" : "heartbeat recent",
+                });
                 continue;
             }
             // Process is dead or heartbeat is stale — recover
@@ -324,7 +353,7 @@ export class RunManager {
         }
         // Also check waiting runs with stale heartbeats (process died while waiting)
         for (const status of ["waiting_input", "waiting_approval"]) {
-            const waitingRuns = await this.store.list({ status });
+            const waitingRuns = await this.listAllByStatus(status);
             for (const run of waitingRuns) {
                 const stale = this.heartbeat.isStale(run.runId);
                 if (stale && !this.heartbeat.isProcessAlive(run.runId)) {
@@ -337,6 +366,45 @@ export class RunManager {
         }
         return recovered;
     }
+    /**
+     * Drain EVERY run with the given status, page by page.
+     *
+     * `store.list()` defaults to `limit: 50` because it backs a UI list. Crash
+     * recovery must not inherit a UI page size: with 55 stale running runs, the
+     * bare `list({ status })` call recovered the first 50 and left the remaining 5
+     * pinned in "running" forever (no later pass would revisit them, because
+     * recovery only runs at startup).
+     *
+     * Pages until a short page arrives. `maxPages` is a runaway guard for a store
+     * that ignores `offset` — without it a buggy store would loop forever.
+     */
+    async listAllByStatus(status) {
+        // Overridable so a test can force the multi-page path without creating more
+        // rows than the production page size (which cost ~30s under load).
+        const pageSize = this.recoverPageSize;
+        const maxPages = 10_000;
+        const all = [];
+        const seen = new Set();
+        for (let page = 0; page < maxPages; page += 1) {
+            const batch = await this.store.list({
+                status,
+                limit: pageSize,
+                offset: page * pageSize,
+            });
+            for (const run of batch) {
+                // Dedupe defensively: concurrent writes can shift the offset window and
+                // surface the same run twice, which would double-recover it.
+                if (seen.has(run.runId))
+                    continue;
+                seen.add(run.runId);
+                all.push(run);
+            }
+            if (batch.length < pageSize)
+                return all;
+        }
+        logger.warn("run.recover.page_limit", { status, scanned: all.length });
+        return all;
+    }
     /**
      * Graceful shutdown — stop all heartbeats and release all locks.
      */
@@ -388,7 +456,11 @@ export class RunManager {
             objective: run.objective,
             store: this.store,
         });
-        const artifactTracker = new ArtifactTracker({ runId, store: this.store });
+        const artifactTracker = new ArtifactTracker({
+            runId,
+            store: this.store,
+            detectors: this.artifactDetectors,
+        });
         // Build lifecycle hooks so Engine can notify us about approval/input needs
         const lifecycleHooks = {
             onApprovalNeeded: async (request) => {
@@ -413,8 +485,7 @@ export class RunManager {
                 // suppresses sub-agent session_started upstream (engine.ts:830-835),
                 // but a custom RunExecutor could forward sub-agent events — and only
                 // the MAIN run's session should identify the run, never a sub-agent's.
-                if (event.type === "session_started" &&
-                    !event.agentId) {
+                if (event.type === "session_started" && !event.agentId) {
                     try {
                         const run = await this.getOrThrow(runId);
                         if (run.sessionId !== event.sessionId) {

package/dist/run/factory.d.ts

@@ -20,6 +20,7 @@
 import type { LLMConfig, PermissionMode } from "../types.js";
 import type { EngineConfig, EngineHookConfig } from "../engine/types.js";
 import type { Evaluator } from "./Evaluator.js";
+import type { CapabilityModule } from "../capabilities/index.js";
 import { RunManager } from "./RunManager.js";
 export interface CreateRunManagerOptions {
     /** LLM configuration (required). */
@@ -63,6 +64,8 @@ export interface CreateRunManagerOptions {
      * the interactive run-aware backend.
      */
     approvalBackend?: import("../tool-system/permission.js").ApprovalBackend;
+    /** Product/domain capabilities installed into each Engine. */
+    capabilities?: readonly CapabilityModule[];
 }
 /**
  * Create a fully configured RunManager with one call.

package/dist/run/factory.js

@@ -41,6 +41,7 @@ export function createRunManager(options) {
             customSystemPrompt: options.customSystemPrompt,
             appendSystemPrompt: options.appendSystemPrompt,
             hooks: options.hooks,
+            capabilities: options.capabilities,
             ...(options.approvalBackend ? { approvalBackend: options.approvalBackend } : {}),
         },
         concurrency: options.concurrency ?? 1,
@@ -48,5 +49,6 @@ export function createRunManager(options) {
         evaluator: options.evaluator,
         defaultTags: options.defaultTags,
         defaultMetadata: options.defaultMetadata,
+        capabilities: options.capabilities,
     });
 }

package/dist/runtime/safe-spawn.d.ts

@@ -52,6 +52,12 @@ export interface SafeSpawnOptions {
     ioDrainGraceMs?: number;
     /** Optional cancellation signal. If already aborted, SafeSpawn resolves immediately without spawning. */
     signal?: AbortSignal;
+    /**
+     * POSIX only: launch the direct child as a process-group leader so timeout
+     * and abort terminate helpers such as git-remote-https as well. Windows
+     * already uses taskkill /T for direct children.
+     */
+    processGroup?: boolean;
 }
 export interface SafeSpawnShellOptions extends SafeSpawnOptions {
     /** Optional sandbox to wrap the command through. Required for shell-mode. If omitted, the command runs through `shell ?? /bin/bash -c`. */

package/dist/runtime/safe-spawn.js

@@ -35,7 +35,7 @@
  */
 import { spawn } from "node:child_process";
 import { StringDecoder } from "node:string_decoder";
-import { resolveSpawnTarget, defaultShellBinary, killChildTree, killProcessGroup } from "./spawn-common.js";
+import { resolveSpawnTarget, defaultShellBinary, killChildTree, killProcessGroup, } from "./spawn-common.js";
 export const DEFAULT_MAX_OUTPUT_BYTES = 1_000_000;
 export const DEFAULT_IO_DRAIN_GRACE_MS = 100;
 const TIMEOUT_SIGKILL_GRACE_MS = 2000;
@@ -51,6 +51,7 @@ export function safeSpawn(file, args, opts) {
         opts,
         cleanup: undefined,
         resolveMs: undefined,
+        detached: opts.processGroup === true && process.platform !== "win32",
     });
 }
 /**
@@ -85,7 +86,7 @@ export function safeSpawnShell(command, opts) {
         detached: true,
     });
 }
-function runLifecycle({ file, args, opts, cleanup, resolveMs, detached }) {
+function runLifecycle({ file, args, opts, cleanup, resolveMs, detached, }) {
     const maxBytes = opts.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
     const abortGrace = opts.ioDrainGraceMs ?? DEFAULT_IO_DRAIN_GRACE_MS;
     const lifecycleStartedAt = spawnProfileEnabled() ? performance.now() : 0;
@@ -225,11 +226,7 @@ function runLifecycle({ file, args, opts, cleanup, resolveMs, detached }) {
             // throw above, so we surface the same reason. If timeout or abort
             // fired concurrently, give those precedence — the user-facing cause
             // is the cancel/timeout, not the resulting process death.
-            const reason = timedOut
-                ? "timeout"
-                : aborted
-                    ? "aborted"
-                    : "spawn_failed";
+            const reason = timedOut ? "timeout" : aborted ? "aborted" : "spawn_failed";
             finish({
                 reason,
                 stdout,
@@ -268,11 +265,7 @@ function runLifecycle({ file, args, opts, cleanup, resolveMs, detached }) {
                     stderr += tailErr;
                 }
             }
-            const reason = timedOut
-                ? "timeout"
-                : aborted
-                    ? "aborted"
-                    : "ok";
+            const reason = timedOut ? "timeout" : aborted ? "aborted" : "ok";
             finish({
                 reason,
                 stdout,
@@ -305,7 +298,9 @@ function safeCleanup(cleanup) {
     try {
         cleanup();
     }
-    catch { /* best-effort */ }
+    catch {
+        /* best-effort */
+    }
 }
 function emptyResult(overrides) {
     return {

package/dist/services/auto-dream.d.ts

@@ -19,11 +19,23 @@ export declare function shouldAutoDream(config?: AutoDreamConfig): boolean;
 /**
  * Record that a session was completed (increment counter).
  */
+/**
+ * Sessions counted since the last consolidation.
+ *
+ * Callers snapshot this BEFORE starting an async dream run and pass it back to
+ * `recordDreamComplete`, so sessions finishing mid-run are not swallowed.
+ */
+export declare function sessionsSinceLastDream(): number;
 export declare function recordSession(): void;
 /**
  * Record that a dream run completed.
+ *
+ * `consumed` is how many sessions the finished run accounted for — captured
+ * BEFORE it started. Subtracting it (instead of zeroing) preserves sessions that
+ * completed while the run was in flight: `runDream()` is async, so blindly
+ * resetting to 0 threw away increments that belonged to the next cycle.
  */
-export declare function recordDreamComplete(): void;
+export declare function recordDreamComplete(consumed?: number): void;
 /**
  * System prompt for the auto-dream tool-call loop.
  *

package/dist/services/auto-dream.js

@@ -7,6 +7,7 @@
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { resolveMemoryBaseDir } from "../session/memory.js";
+import { mutateJsonFile } from "../utils/file-mutex.js";
 const DEFAULT_CONFIG = {
     minSessionsBetween: 5,
     minTimeBetween: 24 * 60 * 60 * 1000, // 24 hours
@@ -33,6 +34,33 @@ function saveState(state) {
     mkdirSync(resolveMemoryBaseDir(), { recursive: true });
     writeFileSync(stateFile, JSON.stringify(state, null, 2), "utf-8");
 }
+/**
+ * Read-modify-write the cadence state under a cross-process lock.
+ *
+ * The reload happens inside the lock, so a writer that lost the race still sees
+ * the winner's value and applies its own change on top instead of overwriting it.
+ */
+function mutateState(change) {
+    mkdirSync(resolveMemoryBaseDir(), { recursive: true });
+    mutateJsonFile(getStateFile(), {
+        parse: (raw) => {
+            if (raw === undefined)
+                return { lastDreamAt: null, sessionsSinceLastDream: 0 };
+            try {
+                const parsed = JSON.parse(raw);
+                return {
+                    lastDreamAt: parsed.lastDreamAt ?? null,
+                    sessionsSinceLastDream: Number(parsed.sessionsSinceLastDream) || 0,
+                };
+            }
+            catch {
+                return { lastDreamAt: null, sessionsSinceLastDream: 0 };
+            }
+        },
+        serialize: (state) => JSON.stringify(state, null, 2),
+        mutation: (current) => ({ value: change(current) }),
+    });
+}
 /**
  * Check if auto-dream should run.
  */
@@ -54,19 +82,39 @@ export function shouldAutoDream(config = DEFAULT_CONFIG) {
 /**
  * Record that a session was completed (increment counter).
  */
+/**
+ * Sessions counted since the last consolidation.
+ *
+ * Callers snapshot this BEFORE starting an async dream run and pass it back to
+ * `recordDreamComplete`, so sessions finishing mid-run are not swallowed.
+ */
+export function sessionsSinceLastDream() {
+    return loadState().sessionsSinceLastDream;
+}
 export function recordSession() {
-    const state = loadState();
-    state.sessionsSinceLastDream++;
-    saveState(state);
+    // Cross-process increment. Desktop worker, Desktop main/automation, TUI and a
+    // standalone agent server can share one CODE_SHELL_HOME, so this was a real
+    // multi-writer path: an unlocked read → +1 → write dropped nearly everything
+    // (48 concurrent processes recorded 1–2 increments). The cadence then never
+    // reached its threshold and auto-consolidation silently stopped happening.
+    mutateState((state) => ({
+        ...state,
+        sessionsSinceLastDream: state.sessionsSinceLastDream + 1,
+    }));
 }
 /**
  * Record that a dream run completed.
+ *
+ * `consumed` is how many sessions the finished run accounted for — captured
+ * BEFORE it started. Subtracting it (instead of zeroing) preserves sessions that
+ * completed while the run was in flight: `runDream()` is async, so blindly
+ * resetting to 0 threw away increments that belonged to the next cycle.
  */
-export function recordDreamComplete() {
-    const state = loadState();
-    state.lastDreamAt = new Date().toISOString();
-    state.sessionsSinceLastDream = 0;
-    saveState(state);
+export function recordDreamComplete(consumed) {
+    mutateState((state) => ({
+        lastDreamAt: new Date().toISOString(),
+        sessionsSinceLastDream: consumed === undefined ? 0 : Math.max(0, state.sessionsSinceLastDream - consumed),
+    }));
 }
 /**
  * System prompt for the auto-dream tool-call loop.

package/dist/services/dream-consolidation.d.ts

@@ -21,6 +21,7 @@
 import type { LLMClientBase } from "../llm/client-base.js";
 import type { ToolRegistry } from "../tool-system/registry.js";
 import type { ToolContext } from "../tool-system/context.js";
+import type { TokenUsage } from "../types.js";
 export interface DreamConsolidationInput {
     /** LLM client for the consolidation calls. */
     llmClient: LLMClientBase;
@@ -36,6 +37,8 @@ export interface DreamConsolidationInput {
     projectDir?: string;
     /** For log attribution. */
     sessionId?: string;
+    /** Owning Engine session/Goal recorder; process billing already happened. */
+    onUsage?: (usage: TokenUsage) => void;
 }
 export interface DreamConsolidationResult {
     /** True if the loop ran (with or without writes); false if it bailed early. */

package/dist/services/dream-consolidation.js

@@ -71,9 +71,12 @@ export async function runDreamConsolidation(input) {
             messages,
             tools: toolDefs,
             maxTokens: 2048,
-            recordUsage: false,
+            billingEnabled: true,
+            requestVisible: false,
             reasoning: { mode: "off" },
         });
+        if (resp.usage)
+            input.onUsage?.(resp.usage);
         if (resp.toolCalls.length === 0) {
             logger.info("memory.dream_finished", {
                 sessionId,
@@ -138,7 +141,10 @@ async function dispatchDreamTool(tc, toolRegistry, ctx, consumeWriteBudget) {
         }
     }
     try {
-        const dreamCtx = { ...ctx, __dreamLoop: true };
+        // Portable profile memory is intentionally not part of automatic dream
+        // routing. Normal profile-bound runs may manage it explicitly, but the
+        // consolidation loop remains limited to its existing global/project stores.
+        const dreamCtx = { ...ctx, profileMemoryDir: undefined, __dreamLoop: true };
         const result = await toolRegistry.executeTool(tc.toolName, tc.args, { ctx: dreamCtx });
         if (result.isError)
             return result.error ?? `Error executing ${tc.toolName}`;
@@ -156,6 +162,12 @@ function checkDreamWriteGuard(tc, ctx) {
             error: `Error: dream loop may only write to scope "dream" or "user", got "${scope}".`,
         };
     }
+    if (tc.args?.location === "profile") {
+        return {
+            ok: false,
+            error: "Error: dream loop does not manage portable profile memory.",
+        };
+    }
     const location = tc.args?.location === "global" ? "global" : "project";
     const mm = new MemoryManager({
         projectDir: location === "project" ? ctx.cwd : undefined,

package/dist/services/index.d.ts

@@ -2,7 +2,7 @@
  * Services index — re-exports all service modules.
  */
 export { analytics, trackEvent } from "./analytics.js";
-export { authorize, refreshToken, type OAuthConfig, type OAuthTokens } from "./oauth.js";
+export { authorize, refreshToken, generatePKCE, createHardenedOAuthFetch, type OAuthConfig, type OAuthTokens, type OAuthAuthorizeOptions, type OAuthRefreshOptions, type HardenedOAuthFetchOptions, } from "./oauth.js";
 export { notify, notifyComplete, notifyError } from "./notifier.js";
 export { diagnostics } from "./diagnostics.js";
 export { buildExtractionPrompt, parseExtractionResponse, type ExtractedMemory, } from "./extract-memories.js";

package/dist/services/index.js

@@ -8,7 +8,7 @@ export { analytics, trackEvent } from "./analytics.js";
 // `microCompact` that truncated long *messages* by char count, unrelated
 // to the tool_result-based microcompact in ContextManager). Removed to end
 // the "which microcompact?" ambiguity — the source of truth is ContextManager.
-export { authorize, refreshToken } from "./oauth.js";
+export { authorize, refreshToken, generatePKCE, createHardenedOAuthFetch, } from "./oauth.js";
 export { notify, notifyComplete, notifyError } from "./notifier.js";
 export { diagnostics } from "./diagnostics.js";
 export { buildExtractionPrompt, parseExtractionResponse, } from "./extract-memories.js";

package/dist/services/memory-orchestrator.js

@@ -17,7 +17,7 @@ import { buildExtractionPrompt, parseExtractionResponse, } from "./extract-memor
 import { saveSessionMemory, buildSessionMemoryPrompt } from "./session-memory.js";
 import { extractJSON } from "../utils/json.js";
 import { redactSecrets } from "../logging/sanitize-messages.js";
-import { shouldAutoDream, recordSession, recordDreamComplete, buildDreamSystemPrompt, buildDreamUserPrompt, } from "./auto-dream.js";
+import { shouldAutoDream, recordSession, recordDreamComplete, sessionsSinceLastDream, buildDreamSystemPrompt, buildDreamUserPrompt, } from "./auto-dream.js";
 import { applyGlobalDreamPromotionGate, detectUserDirectGlobalPreference, } from "./global-dream-promotion.js";
 import { logger } from "../logging/logger.js";
 export class MemoryOrchestrator {
@@ -259,13 +259,17 @@ export class MemoryOrchestrator {
                     ? new MemoryManager({ scope: "dream" }).loadScope("dream")
                     : [];
                 if (userMems.length + dreamMems.length + globalDreamMems.length > 0) {
+                    // Snapshot the cadence counter BEFORE the (async) run so sessions that
+                    // finish while it is in flight are carried into the next cycle rather
+                    // than being zeroed away on completion.
+                    const consumed = sessionsSinceLastDream();
                     const ran = await this.options.runDream({
                         systemPrompt: buildDreamSystemPrompt(),
                         userPrompt: buildDreamUserPrompt(userMems, dreamMems, globalDreamMems),
                         projectDir: this.options.projectDir,
                     });
                     if (ran) {
-                        recordDreamComplete();
+                        recordDreamComplete(consumed);
                         dreamTriggered = true;
                         logger.info("memory.auto_dream_done", {
                             sessionId,

package/dist/services/oauth.d.ts

@@ -1,27 +1,51 @@
-/**
- * OAuth service — OAuth 2.0 authorization code flow with PKCE.
- *
- * Supports browser-based login flow for API authentication.
- */
+/** OAuth 2.0 authorization-code + PKCE primitives for host applications. */
 export interface OAuthConfig {
     clientId: string;
+    clientSecret?: string;
     authorizationEndpoint: string;
     tokenEndpoint: string;
     redirectUri?: string;
     scopes?: string[];
+    resource?: string;
 }
 export interface OAuthTokens {
     accessToken: string;
     refreshToken?: string;
     expiresAt?: number;
     tokenType: string;
+    scope?: string;
+}
+export interface OAuthAuthorizeOptions {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    openExternal?: (url: string) => Promise<void> | void;
+    fetch?: typeof fetch;
+    callbackHost?: "127.0.0.1";
+    /** Zero asks the OS for an ephemeral port. */
+    callbackPort?: number;
+}
+export interface OAuthRefreshOptions {
+    fetch?: typeof fetch;
+    now?: number;
+}
+export interface HardenedOAuthFetchOptions {
+    /** Maximum redirects followed after the initial request. */
+    maxRedirects?: number;
 }
 /**
- * Run the OAuth authorization code flow.
- * Opens a browser for user login and waits for the callback.
+ * Wrap fetch with OAuth-specific redirect handling. Every hop is validated;
+ * POST/Authorization requests never cross origins, so authorization codes,
+ * verifiers, refresh tokens, client secrets, and revocation tokens cannot be
+ * forwarded by an upstream 30x response.
  */
-export declare function authorize(config: OAuthConfig): Promise<OAuthTokens>;
+export declare function createHardenedOAuthFetch(baseFetch?: typeof fetch, options?: HardenedOAuthFetchOptions): typeof fetch;
+export declare function generatePKCE(): {
+    verifier: string;
+    challenge: string;
+};
 /**
- * Refresh an access token using a refresh token.
+ * Run an OAuth authorization-code flow. The host owns browser launching and
+ * injects `openExternal`; core only listens on an ephemeral loopback port.
  */
-export declare function refreshToken(config: OAuthConfig, refreshTokenValue: string): Promise<OAuthTokens>;
+export declare function authorize(config: OAuthConfig, options?: OAuthAuthorizeOptions): Promise<OAuthTokens>;
+export declare function refreshToken(config: OAuthConfig, refreshTokenValue: string, options?: OAuthRefreshOptions): Promise<OAuthTokens>;