@noetic-tools/core 0.0.1

package/dist/adapters/local-fs-adapter.js

@@ -0,0 +1,43 @@
+//#region Helpers
+function toFsStats(s) {
+    return {
+        size: s.size,
+        isDirectory: () => s.isDirectory(),
+        isSymbolicLink: () => s.isSymbolicLink(),
+        isFile: () => s.isFile(),
+    };
+}
+//#endregion
+//#region Public API
+/** Create an FsAdapter backed by the local filesystem via `node:fs/promises`. */
+export function createLocalFsAdapter() {
+    const fs = () => import('node:fs/promises');
+    const fsConstants = () => import('node:fs');
+    return {
+        readFile: async (p) => (await fs()).readFile(p),
+        readFileText: async (p) => (await fs()).readFile(p, 'utf-8'),
+        writeFile: async (p, content) => (await fs()).writeFile(p, content, 'utf-8'),
+        writeFileBytes: async (p, content) => (await fs()).writeFile(p, content),
+        appendFile: async (p, content) => (await fs()).appendFile(p, content, 'utf-8'),
+        mkdir: async (dir) => {
+            await (await fs()).mkdir(dir, {
+                recursive: true,
+            });
+        },
+        rename: async (oldPath, newPath) => (await fs()).rename(oldPath, newPath),
+        rm: async (p, options) => {
+            await (await fs()).rm(p, options);
+        },
+        access: async (p, mode) => {
+            const [{ constants }, fsPromises] = await Promise.all([
+                fsConstants(),
+                fs(),
+            ]);
+            await fsPromises.access(p, mode ?? constants.R_OK);
+        },
+        stat: async (p) => toFsStats(await (await fs()).stat(p)),
+        lstat: async (p) => toFsStats(await (await fs()).lstat(p)),
+        readdir: async (p) => (await fs()).readdir(p),
+    };
+}
+//#endregion

package/dist/adapters/local-shell-adapter.d.ts

@@ -0,0 +1,51 @@
+import type { ShellAdapter } from '../types/shell-adapter';
+/**
+ * Options for `createLocalShellAdapter`.
+ *
+ * @public
+ */
+export interface CreateLocalShellAdapterOptions {
+    /**
+     * When `true`, every command is rewritten through `rtk rewrite`
+     * (https://github.com/rtk-ai/rtk) before exec to filter and summarize
+     * output for token efficiency. The rewrite is per-command — `rtk` decides
+     * which programs it knows how to filter and falls back to the raw command
+     * for unknown programs (exit 1, no output → original used).
+     *
+     * Defaults to `false` so non-CLI embedders keep raw shell semantics.
+     * `@noetic/cli` opts in via `createDefaultShellAdapter`.
+     *
+     * Resolved against `PATH` once at adapter creation; the result is exposed
+     * as `rtkAvailable` so callers can fail fast when this is required.
+     */
+    useRtk?: boolean;
+}
+/**
+ * Local shell adapter — a `ShellAdapter` plus introspection for the rtk
+ * wrapping decision so the harness factory can verify the binary is present
+ * before it starts running tools.
+ *
+ * @public
+ */
+export interface LocalShellAdapter extends ShellAdapter {
+    /** Whether `rtk` was found on PATH at adapter creation time. */
+    readonly rtkAvailable: boolean;
+    /** Resolved absolute path to `rtk`, or `null` when not on PATH. */
+    readonly rtkPath: string | null;
+    /** Whether wrapping with rtk is enabled (the constructor option). */
+    readonly useRtk: boolean;
+}
+/**
+ * Create a `ShellAdapter` backed by the local system shell via `Bun.spawn`.
+ *
+ * Defaults to plain `sh -c` execution. Pass `{ useRtk: true }` to wrap each
+ * command through `rtk rewrite` for token efficiency — best-effort: any
+ * failure (rtk missing, exit 1, timeout) falls through to the raw command.
+ * The CLI opts in via `createDefaultShellAdapter`; other embedders of
+ * `@noetic-tools/core` keep raw shell semantics unless they explicitly enable rtk.
+ *
+ * Call sites that want hard-fail semantics on missing rtk should read
+ * `rtkAvailable` on the returned adapter and refuse to boot when it is
+ * `false`.
+ */
+export declare function createLocalShellAdapter(opts?: CreateLocalShellAdapterOptions): LocalShellAdapter;

package/dist/adapters/local-shell-adapter.js

@@ -0,0 +1,167 @@
+import { TIMEOUT_ERROR_PREFIX } from '../types/shell-adapter';
+//#endregion
+//#region Helpers
+const RTK_REWRITE_TIMEOUT_MS = 2e3;
+function readStream(stream, onData) {
+    const chunks = [];
+    const reader = stream.getReader();
+    async function pump() {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done) {
+                break;
+            }
+            const buf = Buffer.from(value);
+            chunks.push(buf);
+            onData?.(buf);
+        }
+        return Buffer.concat(chunks).toString('utf-8');
+    }
+    return pump();
+}
+/**
+ * Ask `rtk rewrite` to translate the raw command into its filtered form.
+ *
+ * Returns the rewritten command string when rtk knows how to wrap it
+ * (exit 0, non-empty stdout). Returns `null` on any other outcome — exit 1
+ * (rtk doesn't recognize the program), timeout, spawn failure — so the
+ * caller falls through to the raw command. This mirrors the documented
+ * hook contract: `REWRITTEN=$(rtk rewrite "$CMD") || exit 0`.
+ */
+async function rewriteWithRtk(rtkPath, command) {
+    try {
+        const proc = Bun.spawn([
+            rtkPath,
+            'rewrite',
+            command,
+        ], {
+            stdout: 'pipe',
+            stderr: 'ignore',
+        });
+        const timeoutHandle = setTimeout(() => {
+            proc.kill();
+        }, RTK_REWRITE_TIMEOUT_MS);
+        try {
+            const [stdout, exitCode] = await Promise.all([
+                readStream(proc.stdout),
+                proc.exited,
+            ]);
+            if (exitCode !== 0) {
+                return null;
+            }
+            const trimmed = stdout.trim();
+            return trimmed.length > 0 ? trimmed : null;
+        }
+        finally {
+            clearTimeout(timeoutHandle);
+        }
+    }
+    catch {
+        return null;
+    }
+}
+//#endregion
+//#region Public API
+/**
+ * Create a `ShellAdapter` backed by the local system shell via `Bun.spawn`.
+ *
+ * Defaults to plain `sh -c` execution. Pass `{ useRtk: true }` to wrap each
+ * command through `rtk rewrite` for token efficiency — best-effort: any
+ * failure (rtk missing, exit 1, timeout) falls through to the raw command.
+ * The CLI opts in via `createDefaultShellAdapter`; other embedders of
+ * `@noetic-tools/core` keep raw shell semantics unless they explicitly enable rtk.
+ *
+ * Call sites that want hard-fail semantics on missing rtk should read
+ * `rtkAvailable` on the returned adapter and refuse to boot when it is
+ * `false`.
+ */
+export function createLocalShellAdapter(opts) {
+    const useRtk = opts?.useRtk ?? false;
+    // Read PATH from process.env so tests can override it. `Bun.which(name)`
+    // without an explicit PATH ignores subsequent process.env.PATH mutations.
+    const rtkPath = useRtk
+        ? (Bun.which('rtk', {
+            PATH: process.env.PATH ?? '',
+        }) ?? null)
+        : null;
+    const rtkAvailable = rtkPath !== null;
+    async function exec(command, options) {
+        let effectiveCommand = command;
+        if (useRtk && rtkPath) {
+            const rewritten = await rewriteWithRtk(rtkPath, command);
+            if (rewritten) {
+                effectiveCommand = rewritten;
+            }
+        }
+        const proc = Bun.spawn([
+            'sh',
+            '-c',
+            effectiveCommand,
+        ], {
+            cwd: options.cwd,
+            env: options.env
+                ? {
+                    ...process.env,
+                    ...options.env,
+                }
+                : undefined,
+            stdin: options.stdin
+                ? new Blob([
+                    options.stdin,
+                ])
+                : undefined,
+            stdout: 'pipe',
+            stderr: 'pipe',
+        });
+        let timedOut = false;
+        let timeoutHandle;
+        const timeoutSeconds = options.timeout;
+        if (timeoutSeconds !== undefined && timeoutSeconds > 0) {
+            timeoutHandle = setTimeout(() => {
+                timedOut = true;
+                proc.kill();
+            }, timeoutSeconds * 1e3);
+        }
+        const abortHandler = () => {
+            proc.kill();
+        };
+        if (options.signal) {
+            options.signal.addEventListener('abort', abortHandler, {
+                once: true,
+            });
+        }
+        try {
+            const [stdout, stderr] = await Promise.all([
+                readStream(proc.stdout, options.onData),
+                readStream(proc.stderr, options.onData),
+            ]);
+            const exitCode = await proc.exited;
+            // Only timeout throws. Signal-driven aborts resolve normally so
+            // callers can decide via their own state whether the result is
+            // a real exit or a cancellation (see runUserShellCommand).
+            if (timedOut) {
+                throw new Error(`${TIMEOUT_ERROR_PREFIX}${timeoutSeconds}`);
+            }
+            return {
+                stdout,
+                stderr,
+                exitCode,
+            };
+        }
+        finally {
+            if (timeoutHandle) {
+                clearTimeout(timeoutHandle);
+            }
+            if (options.signal) {
+                options.signal.removeEventListener('abort', abortHandler);
+            }
+        }
+    }
+    return {
+        exec,
+        rtkAvailable,
+        rtkPath,
+        useRtk,
+    };
+}
+//#endregion

package/dist/adapters/local-subprocess-adapter.d.ts

@@ -0,0 +1,16 @@
+import type { ChildProcess, SpawnOptions } from 'node:child_process';
+import type { SubprocessAdapter } from '../types/subprocess-adapter';
+export type SubprocessSignal = 'SIGTERM' | 'SIGSTOP' | 'SIGCONT';
+export interface ProcessSignaller {
+    kill(target: number, signal: SubprocessSignal): void;
+    isAlive(pid: number): boolean;
+    startTime(pid: number): string | null;
+}
+export interface CreateLocalSubprocessAdapterOptions {
+    spawnFn?: (command: string, args: ReadonlyArray<string>, options: SpawnOptions) => Pick<ChildProcess, 'pid' | 'unref'> & {
+        on(event: 'error', listener: (err: Error) => void): unknown;
+    };
+    signaller?: ProcessSignaller;
+}
+export declare const defaultProcessSignaller: ProcessSignaller;
+export declare function createLocalSubprocessAdapter(options?: CreateLocalSubprocessAdapterOptions): SubprocessAdapter;

package/dist/adapters/local-subprocess-adapter.js

@@ -0,0 +1,187 @@
+import { execFileSync, spawn } from 'node:child_process';
+function isErrnoException(err) {
+    return typeof err === 'object' && err !== null && 'code' in err;
+}
+function readPidStartTime(pid) {
+    try {
+        const out = execFileSync('ps', [
+            '-p',
+            String(pid),
+            '-o',
+            'lstart=',
+        ], {
+            stdio: [
+                'ignore',
+                'pipe',
+                'ignore',
+            ],
+            encoding: 'utf8',
+        }).trim();
+        return out.length === 0 ? null : out;
+    }
+    catch {
+        return null;
+    }
+}
+export const defaultProcessSignaller = {
+    kill(target, signal) {
+        process.kill(target, signal);
+    },
+    isAlive(pid) {
+        try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch (err) {
+            return isErrnoException(err) && err.code === 'EPERM';
+        }
+    },
+    startTime(pid) {
+        return readPidStartTime(pid);
+    },
+};
+function nowIso() {
+    return new Date().toISOString();
+}
+export function createLocalSubprocessAdapter(options = {}) {
+    const signaller = options.signaller ?? defaultProcessSignaller;
+    const spawnFn = options.spawnFn ?? ((command, args, opts) => spawn(command, args.slice(), opts));
+    const handles = new Map();
+    async function save(handle) {
+        handles.set(handle.id, handle);
+        return handle;
+    }
+    async function patch(handle, status) {
+        return save({
+            ...handle,
+            status,
+            updatedAt: nowIso(),
+        });
+    }
+    function pidFor(handle) {
+        return typeof handle.metadata?.pid === 'number' ? handle.metadata.pid : null;
+    }
+    return {
+        async spawn(request) {
+            let asyncSpawnError = null;
+            const child = spawnFn(request.command, request.args ?? [], {
+                cwd: request.cwd,
+                detached: request.detached ?? false,
+                stdio: 'ignore',
+                env: request.env
+                    ? {
+                        ...process.env,
+                        ...request.env,
+                    }
+                    : undefined,
+            });
+            child.on('error', (err) => {
+                asyncSpawnError = err;
+            });
+            child.unref();
+            if (child.pid === undefined || !signaller.isAlive(child.pid)) {
+                throw new Error(asyncSpawnError instanceof Error
+                    ? asyncSpawnError.message
+                    : `Subprocess failed to start: ${request.command}`);
+            }
+            const now = nowIso();
+            return save({
+                id: `subprocess-${crypto.randomUUID()}`,
+                status: 'running',
+                startedAt: now,
+                updatedAt: now,
+                metadata: {
+                    ...(request.metadata ?? {}),
+                    runtime: 'local',
+                    pid: child.pid,
+                    pidStarttime: signaller.startTime(child.pid),
+                    command: request.command,
+                    args: request.args ?? [],
+                    cwd: request.cwd,
+                    detached: request.detached ?? false,
+                },
+            });
+        },
+        async get(handleId) {
+            return handles.get(handleId) ?? null;
+        },
+        async stop(handleId, reason) {
+            const handle = handles.get(handleId);
+            if (!handle) {
+                return {
+                    kind: 'not_found',
+                    handleId,
+                };
+            }
+            const pid = pidFor(handle);
+            if (pid !== null) {
+                try {
+                    signaller.kill(handle.metadata?.detached === true ? -pid : pid, 'SIGTERM');
+                }
+                catch {
+                    /* process may already be gone */
+                }
+            }
+            const next = await patch({
+                ...handle,
+                metadata: {
+                    ...(handle.metadata ?? {}),
+                    stopReason: reason,
+                },
+            }, 'stopped');
+            return {
+                kind: 'stopped',
+                handleId,
+                handle: next,
+            };
+        },
+        async pause(handleId) {
+            const handle = handles.get(handleId);
+            if (!handle) {
+                return {
+                    kind: 'not_found',
+                    handleId,
+                };
+            }
+            const pid = pidFor(handle);
+            if (pid === null) {
+                return {
+                    kind: 'unsupported',
+                    handle,
+                    message: 'Subprocess handle has no pid metadata.',
+                };
+            }
+            signaller.kill(handle.metadata?.detached === true ? -pid : pid, 'SIGSTOP');
+            return {
+                kind: 'ok',
+                handle: await patch(handle, 'paused'),
+            };
+        },
+        async resume(handleId) {
+            const handle = handles.get(handleId);
+            if (!handle) {
+                return {
+                    kind: 'not_found',
+                    handleId,
+                };
+            }
+            const pid = pidFor(handle);
+            if (pid === null) {
+                return {
+                    kind: 'unsupported',
+                    handle,
+                    message: 'Subprocess handle has no pid metadata.',
+                };
+            }
+            signaller.kill(handle.metadata?.detached === true ? -pid : pid, 'SIGCONT');
+            return {
+                kind: 'ok',
+                handle: await patch(handle, 'running'),
+            };
+        },
+        async isAlive(handle) {
+            const pid = pidFor(handle);
+            return pid !== null && signaller.isAlive(pid);
+        },
+    };
+}

package/dist/adapters/openrouter.d.ts

@@ -0,0 +1,57 @@
+import type * as OpenRouterAgent from '@openrouter/agent';
+import type { LLMResponse, Tool } from '../types/common';
+import type { Context } from '../types/context';
+import type { EmbedFn } from '../types/embed';
+import type { Item } from '../types/items';
+import type { MemoryLayer } from '../types/memory';
+import type { AgentHarnessContract } from '../types/runtime';
+type ProviderOutputItem = OpenRouterAgent.OpenResponsesResult['output'][number];
+type OpenRouterInputItem = OpenRouterAgent.EasyInputMessage | OpenRouterAgent.FunctionCallItem | OpenRouterAgent.FunctionCallOutputItem | ProviderOutputItem;
+/** @internal */
+export type SdkTool = OpenRouterAgent.Tool;
+/** @internal */
+export interface ConvertToolsParams {
+    tools: ReadonlyArray<Tool>;
+}
+/** @internal Extracts system messages from items and returns them as a single instructions string. */
+export declare function extractSystemInstruction(items: ReadonlyArray<Item>): {
+    instructions: string | undefined;
+    remaining: Item[];
+};
+/** @internal Converts Noetic Items to OpenRouter SDK input format. */
+export declare function itemsToInput(items: ReadonlyArray<Item>): OpenRouterInputItem[];
+/**
+ * @internal Extracts output items from an SDK response, passing them through directly
+ * as Open Responses compliant items. Falls back to creating a message from `outputText`
+ * when the output array contains no message items.
+ */
+export declare function extractOutputItems(response: OpenRouterAgent.OpenResponsesResult): Item[];
+/** @internal */
+export declare function extractUsage(usage: OpenRouterAgent.Usage | null | undefined): LLMResponse['usage'];
+/** @internal */
+export declare function convertTools({ tools }: ConvertToolsParams): SdkTool[];
+/** @internal */
+export interface ExecuteToolCallParams {
+    toolName: string;
+    args: unknown;
+    tools: ReadonlyArray<Tool>;
+    context: Context;
+    harness: AgentHarnessContract;
+    layers?: MemoryLayer[];
+}
+/** @internal Execute a single tool call with steering checks. */
+export declare function executeToolCall(params: ExecuteToolCallParams): Promise<{
+    output: string;
+    result?: unknown;
+    error?: boolean;
+}>;
+/**
+ * Creates an `EmbedFn` that calls the OpenRouter embeddings API.
+ *
+ * @public
+ * @param apiKey - OpenRouter API key.
+ * @param embeddingModel - Model identifier (default: `'openai/text-embedding-3-small'`).
+ * @returns An `EmbedFn` that produces embedding vectors for the given texts.
+ */
+export declare function createOpenRouterEmbed(apiKey: string, embeddingModel?: string): EmbedFn;
+export {};