@noetic-tools/core 0.0.1 → 0.1.1

package/dist/unstable.js

@@ -6,19 +6,19 @@
  * They are intended for authors of custom memory layers, runtime backends,
  * and other framework extensions. Do not depend on them in application code.
  */
-/** @unstable Unsafe cast utility for bridging internal type boundaries. */
-export { frameworkCast } from './interpreter/framework-cast';
 /** @unstable Budget allocation and checking utilities. */
-export { allocateBudgets, checkBudget } from './memory/budget';
+export { allocateBudgets, checkBudget } from './memory/budget.js';
 /** @unstable Factory for creating layer state stores. */
-export { createLayerStateStore } from './memory/layer-lifecycle';
+export { createLayerStateStore } from './memory/layer-lifecycle.js';
 /** @unstable View assembly algorithm that converges memory layer outputs into the LLM context. */
-export { assembleView } from './memory/projector';
+export { assembleView } from './memory/projector.js';
 /** @unstable Factory for creating scoped storage wrappers around a StorageAdapter. */
-export { createScopedStorage } from './memory/scope';
+export { createScopedStorage } from './memory/scope.js';
 /**
  * @unstable Internal helper used by sync agent-spawn paths (worktree isolation)
  * to seed a child's cwd snapshot without touching `previousCwd`. Not part of
  * the public surface — call sites must hold exclusive use of the parent ctx.
  */
-export { retargetCwdForSpawn } from './runtime/cwd-helpers';
+export { retargetCwdForSpawn } from './runtime/cwd-helpers.js';
+/** @unstable Unsafe cast utility for bridging internal type boundaries. */
+export { frameworkCast } from './util/framework-cast.js';

package/dist/until/combinators.d.ts

@@ -1,4 +1,4 @@
-import type { Until } from '../types/step';
+import type { Until } from '../types/step.js';
 /**
  * Combines predicates with OR semantics; stops the loop when any predicate says stop.
  *

package/dist/until/never.d.ts

@@ -1,4 +1,4 @@
-import type { Until } from '../types/step';
+import type { Until } from '../types/step.js';
 /**
  * Termination predicate that never stops the loop. Use with `every`-like
  * forever-loops or with explicit cancellation paths.

package/dist/until/predicates.d.ts

@@ -1,7 +1,7 @@
-import type { EmbedFn } from '../types/embed';
-import type { StorageAdapter } from '../types/memory';
-import type { Until } from '../types/step';
-import { never } from './never';
+import type { EmbedFn } from '../types/embed.js';
+import type { StorageAdapter } from '../types/memory.js';
+import type { Until } from '../types/step.js';
+import { never } from './never.js';
 /** @public Async verification function that checks loop output and optionally returns feedback. */
 export type VerifyFn = (output: unknown) => Promise<{
     pass: boolean;
@@ -38,6 +38,15 @@ export declare const until: {
     converged(opts: ConvergeConfig): Until;
     /** Stops the loop when the last output text contains the given marker string. @public */
     outputContains(marker: string): Until;
+    /**
+     * Stops the loop when the last output text exactly equals the given
+     * sentinel string. Prefer this over `outputContains` when the marker is a
+     * dedicated exit sentinel produced by a terminator step — exact equality
+     * avoids substring collisions with unrelated step output that happens to
+     * quote the sentinel.
+     * @public
+     */
+    outputEquals(sentinel: string): Until;
     /** Wraps an arbitrary `Until` function as a named predicate. @public */
     custom(fn: Until): Until;
 };

package/dist/until/predicates.js

@@ -1,5 +1,5 @@
-import { cosineSimilarity } from '../conditions/cosine-similarity';
-import { never } from './never';
+import { cosineSimilarity } from '../conditions/cosine-similarity.js';
+import { never } from './never.js';
 const CONVERGE_CACHE_KEY = 'converge:previousVector';
 /**
  * Namespace of built-in loop termination predicates.
@@ -119,6 +119,20 @@ export const until = {
             reason: snap.lastText.includes(marker) ? `Output contains marker: ${marker}` : undefined,
         });
     },
+    /**
+     * Stops the loop when the last output text exactly equals the given
+     * sentinel string. Prefer this over `outputContains` when the marker is a
+     * dedicated exit sentinel produced by a terminator step — exact equality
+     * avoids substring collisions with unrelated step output that happens to
+     * quote the sentinel.
+     * @public
+     */
+    outputEquals(sentinel) {
+        return (snap) => ({
+            stop: snap.lastText === sentinel,
+            reason: snap.lastText === sentinel ? `Output matched sentinel: ${sentinel}` : undefined,
+        });
+    },
     /** Wraps an arbitrary `Until` function as a named predicate. @public */
     custom(fn) {
         return fn;

package/dist/util/message-helpers.d.ts

@@ -0,0 +1,17 @@
+import type { LLMResponse } from '../types/common.js';
+import type { Context } from '../types/context.js';
+import type { InputMessageItem, Item, MessageItem } from '../types/items.js';
+export declare function isAssistantMessage(item: unknown): item is MessageItem;
+export declare function isUserMessage(item: unknown): item is MessageItem;
+export declare function isOutputText(part: {
+    type: string;
+}): part is {
+    type: 'output_text';
+    text: string;
+};
+export declare function createMessage(text: string, role: 'user' | 'developer'): InputMessageItem;
+export declare function extractAssistantText(items: ReadonlyArray<Item>): string;
+/** Naive token estimate: ~4 chars per token */
+export declare function estimateTokens(text: string): number;
+/** Accumulate token usage and cost from an LLM response onto a mutable context. */
+export declare function trackUsage(ctx: Context, response: LLMResponse): void;

package/dist/util/message-helpers.js

@@ -0,0 +1,64 @@
+function canTrackUsage(ctx) {
+    const desc = Object.getOwnPropertyDescriptor(ctx, 'stepCount');
+    return desc !== undefined && desc.writable !== false;
+}
+export function isAssistantMessage(item) {
+    return (typeof item === 'object' &&
+        item !== null &&
+        'type' in item &&
+        item.type === 'message' &&
+        'role' in item &&
+        item.role === 'assistant');
+}
+export function isUserMessage(item) {
+    return (typeof item === 'object' &&
+        item !== null &&
+        'type' in item &&
+        item.type === 'message' &&
+        'role' in item &&
+        item.role === 'user');
+}
+export function isOutputText(part) {
+    return part.type === 'output_text';
+}
+export function createMessage(text, role) {
+    return {
+        id: crypto.randomUUID(),
+        status: 'completed',
+        type: 'message',
+        role,
+        content: [
+            {
+                type: 'input_text',
+                text,
+            },
+        ],
+    };
+}
+export function extractAssistantText(items) {
+    const lastMsg = items.findLast(isAssistantMessage);
+    if (!lastMsg) {
+        return '';
+    }
+    return (lastMsg.content
+        ?.filter(isOutputText)
+        ?.map((c) => c.text)
+        ?.join('') ?? '');
+}
+/** Naive token estimate: ~4 chars per token */
+export function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+/** Accumulate token usage and cost from an LLM response onto a mutable context. */
+export function trackUsage(ctx, response) {
+    if (!canTrackUsage(ctx)) {
+        return;
+    }
+    ctx.tokens.input += response.usage.inputTokens;
+    ctx.tokens.output += response.usage.outputTokens;
+    ctx.tokens.total += response.usage.inputTokens + response.usage.outputTokens;
+    ctx.tokens.cached = (ctx.tokens.cached ?? 0) + (response.usage.cachedTokens ?? 0);
+    if (response.cost) {
+        ctx.cost = ctx.cost + response.cost;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noetic-tools/core",
-  "version": "0.0.1",
+  "version": "0.1.1",
   "type": "module",
   "description": "Step primitives, interpreter, runtime, and memory layer contract for Noetic agents.",
   "license": "Apache-2.0",
@@ -39,7 +39,8 @@
     "./internal/test": {
       "types": "./dist/internal-test.d.ts",
       "default": "./dist/internal-test.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "dist",
@@ -67,8 +68,9 @@
     "zod": "^4.0.0"
   },
   "scripts": {
-    "build": "bunx tsc -p tsconfig.build.json",
-    "prepublishOnly": "rm -rf dist && bun run build",
+    "build": "bunx tsc -p tsconfig.build.json && bun scripts/add-js-extensions.ts",
+    "verify:esm": "bun scripts/verify-node-esm.ts",
+    "prepublishOnly": "rm -rf dist && bun run build && bun run verify:esm",
     "test": "bun test",
     "test:coverage": "bun test --coverage --coverage-reporter=text --coverage-reporter=json",
     "test:ci": "bun test --coverage --coverage-reporter=json",

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

@@ -1,3 +0,0 @@
-import type { FsAdapter } from '../types/fs-adapter';
-/** Create an FsAdapter backed by the local filesystem via `node:fs/promises`. */
-export declare function createLocalFsAdapter(): FsAdapter;

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

@@ -1,43 +0,0 @@
-//#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

@@ -1,51 +0,0 @@
-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

@@ -1,167 +0,0 @@
-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

@@ -1,16 +0,0 @@
-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

@@ -1,187 +0,0 @@
-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);
-        },
-    };
-}