@schlenkr/ragents 0.1.5 → 0.1.7

package/packages/agent/src/utils/shell.ts

@@ -1,48 +1,15 @@
 import { existsSync } from "node:fs";
-import { delimiter } from "node:path";
 import { spawn, spawnSync } from "child_process";
-import { getBinDir } from "../config.ts";
 
 export interface ShellConfig {
 	shell: string;
 	args: string[];
-	commandTransport?: "argv" | "stdin";
 }
 
-/**
- * Find bash executable on PATH (cross-platform)
- */
-function isLegacyWslBashPath(path: string): boolean {
-	const normalized = path.replace(/\//g, "\\").toLowerCase();
-	return /^[a-z]:\\windows\\(?:system32|sysnative)\\bash\.exe$/.test(normalized);
-}
+/** No startup file of the user reaches a command; BASH_ENV, the one file `bash -c` reads, is the caller's business. */
+const BASH_ARGS: readonly string[] = ["--noprofile", "--norc", "-c"];
 
-function getBashShellConfig(shell: string): ShellConfig {
-	return isLegacyWslBashPath(shell) ? { shell, args: ["-s"], commandTransport: "stdin" } : { shell, args: ["-c"] };
-}
-
-function findBashOnPath(platform: NodeJS.Platform): string | null {
-	if (platform === "win32") {
-		// Windows: Use 'where' and verify file exists (where can return non-existent paths)
-		try {
-			const result = spawnSync("where", ["bash.exe"], {
-				encoding: "utf-8",
-				timeout: 5000,
-				windowsHide: true,
-			});
-			if (result.status === 0 && result.stdout) {
-				const firstMatch = result.stdout.trim().split(/\r?\n/)[0];
-				if (firstMatch && existsSync(firstMatch)) {
-					return firstMatch;
-				}
-			}
-		} catch {
-			// Ignore errors
-		}
-		return null;
-	}
-
-	// Unix: Use 'which' and trust its output (handles Termux and special filesystems)
+function findBashOnPath(): string | null {
 	try {
 		const result = spawnSync("which", ["bash"], { encoding: "utf-8", timeout: 5000 });
 		if (result.status === 0 && result.stdout) {
@@ -58,140 +25,30 @@ function findBashOnPath(platform: NodeJS.Platform): string | null {
 }
 
 /**
- * Resolve shell configuration based on platform and an optional explicit shell path.
+ * Resolve the bash to run commands with.
  * Resolution order:
- * 1. User-specified shellPath
- * 2. On Windows: Git Bash in known locations, then bash on PATH
- * 3. On Unix: /bin/bash, then bash on PATH, then fallback to sh
+ * 1. The explicit shell path
+ * 2. On Windows: nothing, the caller brings its own bash and names it
+ * 3. On Unix: /bin/bash, then bash on PATH
  */
 export function getShellConfig(customShellPath?: string, platform: NodeJS.Platform = process.platform): ShellConfig {
-	// 1. Check user-specified shell path
 	if (customShellPath) {
 		if (existsSync(customShellPath)) {
-			return getBashShellConfig(customShellPath);
+			return { shell: customShellPath, args: [...BASH_ARGS] };
 		}
 		throw new Error(`Custom shell path not found: ${customShellPath}`);
 	}
-
 	if (platform === "win32") {
-		// 2. Try Git Bash in known locations
-		const paths: string[] = [];
-		const programFiles = process.env.ProgramFiles;
-		if (programFiles) {
-			paths.push(`${programFiles}\\Git\\bin\\bash.exe`);
-		}
-		const programFilesX86 = process.env["ProgramFiles(x86)"];
-		if (programFilesX86) {
-			paths.push(`${programFilesX86}\\Git\\bin\\bash.exe`);
-		}
-
-		for (const path of paths) {
-			if (existsSync(path)) {
-				return getBashShellConfig(path);
-			}
-		}
-
-		// 3. Fallback: search bash.exe on PATH (Cygwin, MSYS2, WSL, etc.)
-		const bashOnPath = findBashOnPath(platform);
-		if (bashOnPath) {
-			return getBashShellConfig(bashOnPath);
-		}
-
-		throw new Error(
-			`No bash shell found. Options:\n` +
-				`  1. Install Git for Windows: https://git-scm.com/download/win\n` +
-				`  2. Add your bash to PATH (Cygwin, MSYS2, etc.)\n` +
-				"  3. Set shellPath in settings.json\n\n" +
-				`Searched Git Bash in:\n${paths.map((p) => `  ${p}`).join("\n")}`,
-		);
+		throw new Error("No bash path given. On Windows the bash is never searched for; the caller has to name the bash it brings along.");
 	}
-
-	// Unix: try /bin/bash, then bash on PATH, then fallback to sh
 	if (existsSync("/bin/bash")) {
-		return getBashShellConfig("/bin/bash");
+		return { shell: "/bin/bash", args: [...BASH_ARGS] };
 	}
-
-	const bashOnPath = findBashOnPath(platform);
+	const bashOnPath = findBashOnPath();
 	if (bashOnPath) {
-		return getBashShellConfig(bashOnPath);
-	}
-
-	return { shell: "sh", args: ["-c"] };
-}
-
-export function getShellEnv(): NodeJS.ProcessEnv {
-	const binDir = getBinDir();
-	const pathKey = Object.keys(process.env).find((key) => key.toLowerCase() === "path") ?? "PATH";
-	const currentPath = process.env[pathKey] ?? "";
-	const pathEntries = currentPath.split(delimiter).filter(Boolean);
-	const hasBinDir = pathEntries.includes(binDir);
-	const updatedPath = hasBinDir ? currentPath : [binDir, currentPath].filter(Boolean).join(delimiter);
-
-	return {
-		...process.env,
-		[pathKey]: updatedPath,
-	};
-}
-
-/**
- * Sanitize binary output for display/storage.
- * Removes characters that crash string-width or cause display issues:
- * - Control characters (except tab, newline, carriage return)
- * - Lone surrogates
- * - Unicode Format characters (crash string-width due to a bug)
- * - Characters with undefined code points
- */
-export function sanitizeBinaryOutput(str: string): string {
-	// Use Array.from to properly iterate over code points (not code units)
-	// This handles surrogate pairs correctly and catches edge cases where
-	// codePointAt() might return undefined
-	return Array.from(str)
-		.filter((char) => {
-			// Filter out characters that cause string-width to crash
-			// This includes:
-			// - Unicode format characters
-			// - Lone surrogates (already filtered by Array.from)
-			// - Control chars except \t \n \r
-			// - Characters with undefined code points
-
-			const code = char.codePointAt(0);
-
-			// Skip if code point is undefined (edge case with invalid strings)
-			if (code === undefined) return false;
-
-			// Allow tab, newline, carriage return
-			if (code === 0x09 || code === 0x0a || code === 0x0d) return true;
-
-			// Filter out control characters (0x00-0x1F, except 0x09, 0x0a, 0x0x0d)
-			if (code <= 0x1f) return false;
-
-			// Filter out Unicode format characters
-			if (code >= 0xfff9 && code <= 0xfffb) return false;
-
-			return true;
-		})
-		.join("");
-}
-
-/**
- * Detached child processes must be tracked so they can be killed on parent
- * shutdown signals (SIGHUP/SIGTERM).
- */
-const trackedDetachedChildPids = new Set<number>();
-
-export function trackDetachedChildPid(pid: number): void {
-	trackedDetachedChildPids.add(pid);
-}
-
-export function untrackDetachedChildPid(pid: number): void {
-	trackedDetachedChildPids.delete(pid);
-}
-
-export function killTrackedDetachedChildren(): void {
-	for (const pid of trackedDetachedChildPids) {
-		killProcessTree(pid);
+		return { shell: bashOnPath, args: [...BASH_ARGS] };
 	}
-	trackedDetachedChildPids.clear();
+	throw new Error("No bash found: neither /bin/bash nor bash on the PATH.");
 }
 
 /**

package/packages/ai/dist/api/ai-sdk-messages.d.ts

@@ -0,0 +1,9 @@
+import type { ModelMessage } from "ai";
+import type { Api, Context, Model } from "../types.ts";
+type CacheControl = {
+    type: "ephemeral";
+    ttl?: "1h";
+};
+export declare function convertMessages(context: Context, model: Model<Api>, cacheControl?: CacheControl): ModelMessage[];
+export {};
+//# sourceMappingURL=ai-sdk-messages.d.ts.map

package/packages/ai/dist/api/ai-sdk-transport.d.ts

@@ -0,0 +1,13 @@
+import type { Model, ProviderHeaders } from "../types.ts";
+interface SdkOptions<TModel> {
+    apiKey?: string;
+    headers?: ProviderHeaders;
+    onPayload?: (payload: unknown, model: TModel) => unknown | Promise<unknown>;
+    onResponse?: (response: {
+        status: number;
+        headers: Record<string, string>;
+    }, model: TModel) => void | Promise<void>;
+}
+export declare function createSdkProvider<TModel extends Model<string>>(model: TModel, options?: SdkOptions<TModel>): import("@openrouter/ai-sdk-provider").OpenRouterProvider;
+export {};
+//# sourceMappingURL=ai-sdk-transport.d.ts.map

package/packages/ai/dist/api/ai-sdk.d.ts

@@ -0,0 +1,15 @@
+import type { SimpleStreamOptions, StreamFunction, StreamOptions } from "../types.ts";
+export interface OpenRouterOptions extends StreamOptions {
+    toolChoice?: "auto" | "none" | "required" | {
+        type: "function";
+        function: {
+            name: string;
+        };
+    };
+    reasoningEffort?: "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+}
+export declare const stream: StreamFunction<"openai-completions", OpenRouterOptions>;
+/** Counts cache_control blocks anywhere in the request body, as the provider counts them. */
+export declare const cacheMarksOf: (value: unknown) => number;
+export declare const streamSimple: StreamFunction<"openai-completions", SimpleStreamOptions>;
+//# sourceMappingURL=ai-sdk.d.ts.map

package/packages/ai/dist/api/ai-sdk.lazy.d.ts

@@ -0,0 +1,3 @@
+import type { ProviderStreams } from "../types.ts";
+export declare const aiSdkApi: () => ProviderStreams;
+//# sourceMappingURL=ai-sdk.lazy.d.ts.map

package/packages/ai/dist/api/lazy.d.ts

@@ -0,0 +1,15 @@
+import type { Api, AssistantMessageEvent, Model, ProviderStreams } from "../types.ts";
+import { AssistantMessageEventStream } from "../utils/event-stream.ts";
+/**
+ * Returns a stream synchronously while running async setup (auth resolution,
+ * lazy module loading) behind it. Setup failures terminate the stream with an
+ * error event.
+ */
+export declare function lazyStream(model: Model<Api>, setup: () => Promise<AsyncIterable<AssistantMessageEvent>>): AssistantMessageEventStream;
+/**
+ * Wraps a dynamically imported API implementation module as `ProviderStreams`.
+ * The module loads on first stream call; the host's import cache deduplicates
+ * loads. Load failures terminate the returned stream with an error event.
+ */
+export declare function lazyApi(load: () => Promise<ProviderStreams>): ProviderStreams;
+//# sourceMappingURL=lazy.d.ts.map

package/packages/ai/dist/api/simple-options.d.ts

@@ -0,0 +1,4 @@
+import type { Api, Context, Model, SimpleStreamOptions, StreamOptions } from "../types.ts";
+export declare function clampMaxTokensToContext(model: Model<Api>, context: Context, maxTokens: number): number;
+export declare function buildBaseOptions(model: Model<Api>, context: Context, options?: SimpleStreamOptions, apiKey?: string): StreamOptions;
+//# sourceMappingURL=simple-options.d.ts.map

package/packages/ai/dist/api/transform-messages.d.ts

@@ -0,0 +1,8 @@
+import type { Api, AssistantMessage, Message, Model } from "../types.ts";
+/**
+ * Normalize tool call ID for cross-provider compatibility.
+ * OpenAI Responses API generates IDs that are 450+ chars with special characters like `|`.
+ * Anthropic APIs require IDs matching ^[a-zA-Z0-9_-]+$ (max 64 chars).
+ */
+export declare function transformMessages<TApi extends Api>(messages: Message[], model: Model<TApi>, normalizeToolCallId?: (id: string, model: Model<TApi>, source: AssistantMessage) => string): Message[];
+//# sourceMappingURL=transform-messages.d.ts.map

package/packages/ai/dist/api-registry.d.ts

@@ -0,0 +1,25 @@
+import { type FauxProviderRegistration, type RegisterFauxProviderOptions } from "./providers/faux.ts";
+import type { Api, AssistantMessage, AssistantMessageEventStream, Context, Model, ProviderStreamOptions, SimpleStreamOptions, StreamFunction, StreamOptions } from "./types.ts";
+export type ApiStreamFunction = (model: Model<Api>, context: Context, options?: StreamOptions) => AssistantMessageEventStream;
+export type ApiStreamSimpleFunction = (model: Model<Api>, context: Context, options?: SimpleStreamOptions) => AssistantMessageEventStream;
+export interface ApiProvider<TApi extends Api = Api, TOptions extends StreamOptions = StreamOptions> {
+    api: TApi;
+    stream: StreamFunction<TApi, TOptions>;
+    streamSimple: StreamFunction<TApi, SimpleStreamOptions>;
+}
+interface ApiProviderInternal {
+    api: Api;
+    stream: ApiStreamFunction;
+    streamSimple: ApiStreamSimpleFunction;
+}
+export declare function registerApiProvider<TApi extends Api, TOptions extends StreamOptions>(provider: ApiProvider<TApi, TOptions>, sourceId?: string): void;
+export declare function getApiProvider(api: Api): ApiProviderInternal | undefined;
+export declare function unregisterApiProviders(sourceId: string): void;
+export declare function registerFauxProvider(options?: RegisterFauxProviderOptions): FauxProviderRegistration;
+export declare function registerBuiltInApiProviders(): void;
+export declare function stream<TApi extends Api>(model: Model<TApi>, context: Context, options?: ProviderStreamOptions): AssistantMessageEventStream;
+export declare function complete<TApi extends Api>(model: Model<TApi>, context: Context, options?: ProviderStreamOptions): Promise<AssistantMessage>;
+export declare function streamSimple<TApi extends Api>(model: Model<TApi>, context: Context, options?: SimpleStreamOptions): AssistantMessageEventStream;
+export declare function completeSimple<TApi extends Api>(model: Model<TApi>, context: Context, options?: SimpleStreamOptions): Promise<AssistantMessage>;
+export {};
+//# sourceMappingURL=api-registry.d.ts.map

package/packages/ai/dist/auth/context.d.ts

@@ -0,0 +1,4 @@
+import type { AuthContext } from "./types.ts";
+/** Default auth context: env vars from `process.env` (undefined in browsers). */
+export declare function defaultProviderAuthContext(): AuthContext;
+//# sourceMappingURL=context.d.ts.map

package/packages/ai/dist/auth/helpers.d.ts

@@ -0,0 +1,4 @@
+import type { ApiKeyAuth } from "./types.ts";
+/** Standard api-key auth: an explicitly given key wins, otherwise the first set env var resolves. */
+export declare function envApiKeyAuth(name: string, envVars: readonly string[]): ApiKeyAuth;
+//# sourceMappingURL=helpers.d.ts.map

package/packages/ai/dist/auth/resolve.d.ts

@@ -0,0 +1,19 @@
+import type { ProviderEnv } from "../types.ts";
+import type { AuthContext, AuthResult, ProviderAuth } from "./types.ts";
+export type ModelsErrorCode = "provider" | "stream" | "auth";
+export interface AuthResolutionOverrides {
+    apiKey?: string;
+    env?: ProviderEnv;
+}
+export declare class ModelsError extends Error {
+    readonly code: ModelsErrorCode;
+    constructor(code: ModelsErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Auth resolution of the `Models` collection: an explicit request key wins, otherwise the provider resolves its key. */
+export declare function resolveProviderAuth(provider: {
+    id: string;
+    auth: ProviderAuth;
+}, authContext: AuthContext, overrides?: AuthResolutionOverrides): Promise<AuthResult | undefined>;
+//# sourceMappingURL=resolve.d.ts.map

package/packages/ai/dist/auth/types.d.ts

@@ -0,0 +1,51 @@
+import type { ProviderEnv, ProviderHeaders } from "../types.ts";
+/**
+ * Request auth for a single model request. If a value cannot be expressed as
+ * `apiKey`, `headers`, or `baseUrl`, it is provider config, not auth.
+ */
+export interface ModelAuth {
+    apiKey?: string;
+    headers?: ProviderHeaders;
+    baseUrl?: string;
+}
+/** An explicitly given API key, with provider-scoped environment values. */
+export interface ApiKeyCredential {
+    type: "api_key";
+    key?: string;
+    env?: ProviderEnv;
+}
+/** Environment access for auth resolution. Injectable for tests and browsers. */
+export interface AuthContext {
+    env(name: string): Promise<string | undefined>;
+}
+/** Result of resolving auth for a model. */
+export interface AuthResult {
+    auth: ModelAuth;
+    /** Provider-scoped environment/config values resolved from the credential and ambient context. */
+    env?: ProviderEnv;
+    /** Human-readable label of the key source, e.g. "OPENROUTER_API_KEY". */
+    source?: string;
+}
+export interface AuthCheck {
+    source?: string;
+    type: "api_key";
+}
+/** Api-key auth: an explicitly given key, otherwise ambient sources such as environment variables. */
+export interface ApiKeyAuth {
+    /** Display name, e.g. "OpenRouter API key". */
+    name: string;
+    /** Optional side-effect-free availability check; missing means Models resolves the key. */
+    check?(input: {
+        ctx: AuthContext;
+        credential?: ApiKeyCredential;
+    }): Promise<AuthCheck | undefined>;
+    /** Resolve auth from the given credential and/or ambient sources; undefined = not configured. */
+    resolve(input: {
+        ctx: AuthContext;
+        credential?: ApiKeyCredential;
+    }): Promise<AuthResult | undefined>;
+}
+export interface ProviderAuth {
+    apiKey: ApiKeyAuth;
+}
+//# sourceMappingURL=types.d.ts.map

package/packages/ai/dist/env-api-keys.d.ts

@@ -0,0 +1,8 @@
+import type { KnownProvider, ProviderEnv } from "./types.ts";
+/**
+ * Get the API key for a provider from its known environment variable, e.g. OPENROUTER_API_KEY.
+ * Unknown providers and empty values yield undefined.
+ */
+export declare function getEnvApiKey(provider: KnownProvider, env?: ProviderEnv): string | undefined;
+export declare function getEnvApiKey(provider: string, env?: ProviderEnv): string | undefined;
+//# sourceMappingURL=env-api-keys.d.ts.map

package/packages/ai/dist/index.d.ts

@@ -0,0 +1,19 @@
+export type { Static, TSchema } from "typebox";
+export { Type } from "typebox";
+export * from "./api/lazy.ts";
+export type { OpenRouterOptions } from "./api/ai-sdk.ts";
+export * from "./api-registry.ts";
+export * from "./auth/context.ts";
+export * from "./auth/helpers.ts";
+export * from "./auth/types.ts";
+export * from "./models.ts";
+export * from "./providers/faux.ts";
+export * from "./types.ts";
+export * from "./utils/diagnostics.ts";
+export * from "./utils/event-stream.ts";
+export * from "./utils/json-parse.ts";
+export * from "./utils/overflow.ts";
+export * from "./utils/retry.ts";
+export * from "./utils/typebox-helpers.ts";
+export * from "./utils/validation.ts";
+//# sourceMappingURL=index.d.ts.map

package/packages/ai/dist/models.d.ts

@@ -0,0 +1,71 @@
+import { type AuthResolutionOverrides } from "./auth/resolve.ts";
+import type { AuthCheck, AuthResult, ProviderAuth } from "./auth/types.ts";
+import type { Api, ApiStreamOptions, AssistantMessage, AssistantMessageEventStream, Context, Model, ModelThinkingLevel, ProviderHeaders, ProviderStreams, SimpleStreamOptions, Usage } from "./types.ts";
+export { ModelsError, type ModelsErrorCode } from "./auth/resolve.ts";
+/**
+ * A provider is the concrete runtime unit. It owns id/name/base metadata,
+ * API-key auth, the model list, and stream behavior.
+ */
+export interface Provider<TApi extends Api = Api> {
+    readonly id: string;
+    readonly name: string;
+    readonly baseUrl?: string;
+    readonly headers?: ProviderHeaders;
+    /** Every provider resolves an API key, even from ambient sources; unresolved means unconfigured. */
+    readonly auth: ProviderAuth;
+    /** The models of the provider. Must not throw; `Models` treats a throwing implementation as having no models. */
+    getModels(): readonly Model<TApi>[];
+    stream<T extends TApi>(model: Model<T>, context: Context, options?: ApiStreamOptions<T>): AssistantMessageEventStream;
+    streamSimple(model: Model<TApi>, context: Context, options?: SimpleStreamOptions): AssistantMessageEventStream;
+}
+/**
+ * Runtime collection of providers plus auth application and stream
+ * convenience. Providers own stream behavior; `Models` resolves auth and
+ * delegates each request to the provider that owns the model.
+ */
+export interface Models {
+    getProvider(id: string): Provider | undefined;
+    /** Models of one provider or of all providers; a provider whose `getModels()` throws yields none. */
+    getModels(provider?: string): readonly Model<Api>[];
+    getModel(provider: string, id: string): Model<Api> | undefined;
+    /** Whether a provider resolves an API key. */
+    checkAuth(providerId: string): Promise<AuthCheck | undefined>;
+    /**
+     * Resolve provider auth by provider id, or provider auth plus static model
+     * headers when passed a model. Resolves `undefined` when the provider is
+     * unknown or unconfigured, rejects with `ModelsError` code "auth" when
+     * the key cannot be resolved.
+     */
+    getAuth(providerId: string, overrides?: AuthResolutionOverrides): Promise<AuthResult | undefined>;
+    getAuth(model: Model<Api>, overrides?: AuthResolutionOverrides): Promise<AuthResult | undefined>;
+    stream<TApi extends Api>(model: Model<TApi>, context: Context, options?: ApiStreamOptions<TApi>): AssistantMessageEventStream;
+    complete<TApi extends Api>(model: Model<TApi>, context: Context, options?: ApiStreamOptions<TApi>): Promise<AssistantMessage>;
+    streamSimple(model: Model<Api>, context: Context, options?: SimpleStreamOptions): AssistantMessageEventStream;
+    completeSimple(model: Model<Api>, context: Context, options?: SimpleStreamOptions): Promise<AssistantMessage>;
+}
+export interface MutableModels extends Models {
+    /** Upsert/replace by provider.id. Provider ids are unique. */
+    setProvider(provider: Provider): void;
+}
+export declare function createModels(): MutableModels;
+export interface CreateProviderOptions<TApi extends Api = Api> {
+    id: string;
+    /** Display name. Default: `id`. */
+    name?: string;
+    baseUrl?: string;
+    headers?: ProviderHeaders;
+    auth: ProviderAuth;
+    models: readonly Model<TApi>[];
+    /** Single implementation, or map keyed by `model.api` for mixed-API providers. */
+    api: ProviderStreams | Partial<Record<TApi, ProviderStreams>>;
+}
+/**
+ * Builds a provider from parts. A single `api` streams all models; an `api`
+ * map dispatches on `model.api`, and a model whose api has no entry produces
+ * a stream error.
+ */
+export declare function createProvider<TApi extends Api = Api>(input: CreateProviderOptions<TApi>): Provider<TApi>;
+export declare function calculateCost<TApi extends Api>(model: Model<TApi>, usage: Usage): Usage["cost"];
+export declare function getSupportedThinkingLevels<TApi extends Api>(model: Model<TApi>): ModelThinkingLevel[];
+export declare function clampThinkingLevel<TApi extends Api>(model: Model<TApi>, level: ModelThinkingLevel): ModelThinkingLevel;
+//# sourceMappingURL=models.d.ts.map