@noetic-tools/core 0.0.1 → 0.1.0

package/dist/adapters/in-memory-fs-adapter.js

@@ -1,4 +1,4 @@
-import { frameworkCast } from '../interpreter/framework-cast';
+import { frameworkCast } from '../util/framework-cast';
 function normalizePath(path) {
     const raw = path.trim();
     if (raw.length === 0) {

package/dist/adapters/in-memory-subprocess/manifest-persistence.d.ts

@@ -0,0 +1,8 @@
+import type { StorageAdapter } from '../../types/memory';
+import type { StepSubprocessRequest, SubprocessHandle } from '../../types/subprocess-adapter';
+import type { InMemoryStepManifest } from './types';
+export declare function isStepManifest(value: unknown): value is InMemoryStepManifest;
+export declare function persistStepManifest(storage: StorageAdapter, request: StepSubprocessRequest, handle: SubprocessHandle): Promise<void>;
+export declare function clearManifest(storage: StorageAdapter, handleId: string): Promise<void>;
+export declare function loadManifest(storage: StorageAdapter, handleId: string): Promise<InMemoryStepManifest | null>;
+export declare function listManifests(storage: StorageAdapter): Promise<InMemoryStepManifest[]>;

package/dist/adapters/in-memory-subprocess/manifest-persistence.js

@@ -0,0 +1,56 @@
+import { isRecord } from './metadata';
+//#region Key layout
+const IN_MEMORY_MANIFEST_PREFIX = 'inMemorySubprocess:manifest:';
+function manifestKey(handleId) {
+    return `${IN_MEMORY_MANIFEST_PREFIX}${handleId}`;
+}
+//#endregion
+//#region Guards
+export function isStepManifest(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    return (value.kind === 'step' &&
+        typeof value.handleId === 'string' &&
+        typeof value.stepId === 'string' &&
+        typeof value.executionId === 'string' &&
+        typeof value.startedAt === 'string' &&
+        isRecord(value.overrides));
+}
+//#endregion
+//#region CRUD
+export async function persistStepManifest(storage, request, handle) {
+    const manifest = {
+        kind: 'step',
+        handleId: handle.id,
+        stepId: request.stepId,
+        executionId: request.executionId,
+        serializedInput: request.serializedInput,
+        overrides: request.overrides,
+        startedAt: handle.startedAt,
+        reattachMode: 'replay',
+    };
+    await storage.set(manifestKey(handle.id), manifest);
+}
+export async function clearManifest(storage, handleId) {
+    await storage.delete(manifestKey(handleId));
+}
+export async function loadManifest(storage, handleId) {
+    const raw = await storage.get(manifestKey(handleId));
+    if (raw === null) {
+        return null;
+    }
+    return isStepManifest(raw) ? raw : null;
+}
+export async function listManifests(storage) {
+    const keys = await storage.list(IN_MEMORY_MANIFEST_PREFIX);
+    const out = [];
+    for (const key of keys) {
+        const raw = await storage.get(key);
+        if (isStepManifest(raw)) {
+            out.push(raw);
+        }
+    }
+    return out;
+}
+//#endregion

package/dist/adapters/in-memory-subprocess/metadata.d.ts

@@ -0,0 +1,12 @@
+import type { ProcessSubprocessRequest, SerializedError, StepSubprocessRequest, SubprocessHandleMetadata, SubprocessRequest } from '../../types/subprocess-adapter';
+export declare function nowIso(): string;
+export declare function isStepRequest(request: SubprocessRequest): request is StepSubprocessRequest;
+export declare function isProcessRequest(request: SubprocessRequest): request is ProcessSubprocessRequest;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/** Convert a thrown value into a `SerializedError`. `NoeticErrorImpl`
+ *  instances (and anything exposing `noeticError`) retain their structured
+ *  payload so consumers can rehydrate typed kinds without a brittle message
+ *  regex. */
+export declare function serializeError(err: unknown): SerializedError;
+export declare function buildProcessMetadata(request: ProcessSubprocessRequest): SubprocessHandleMetadata;
+export declare function buildStepMetadata(request: StepSubprocessRequest): SubprocessHandleMetadata;

package/dist/adapters/in-memory-subprocess/metadata.js

@@ -0,0 +1,58 @@
+//#region Time
+export function nowIso() {
+    return new Date().toISOString();
+}
+//#endregion
+//#region Type guards
+export function isStepRequest(request) {
+    return request.kind === 'step';
+}
+export function isProcessRequest(request) {
+    return request.kind !== 'step';
+}
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+//#endregion
+//#region Error serialisation
+/** Convert a thrown value into a `SerializedError`. `NoeticErrorImpl`
+ *  instances (and anything exposing `noeticError`) retain their structured
+ *  payload so consumers can rehydrate typed kinds without a brittle message
+ *  regex. */
+export function serializeError(err) {
+    if (err instanceof Error) {
+        const payload = {
+            message: err.message,
+            name: err.name,
+            stack: err.stack,
+        };
+        if (isRecord(err) && 'noeticError' in err) {
+            payload.noeticError = err.noeticError;
+        }
+        return payload;
+    }
+    return {
+        message: typeof err === 'string' ? err : String(err),
+    };
+}
+//#endregion
+//#region Metadata builders
+export function buildProcessMetadata(request) {
+    return {
+        ...(request.metadata ?? {}),
+        runtime: 'in-memory',
+        command: request.command,
+        args: request.args ?? [],
+        cwd: request.cwd,
+    };
+}
+export function buildStepMetadata(request) {
+    return {
+        ...(request.metadata ?? {}),
+        runtime: 'in-memory',
+        kind: 'step',
+        stepId: request.stepId,
+        executionId: request.executionId,
+    };
+}
+//#endregion

package/dist/adapters/in-memory-subprocess/step-completion.d.ts

@@ -0,0 +1,3 @@
+import type { CompleteProcessRunParams, CompleteStepRunParams } from './types';
+export declare function completeProcessRun({ request, handle, run, handles, active, save, clearIfDurable, }: CompleteProcessRunParams): Promise<void>;
+export declare function completeStepRun({ request, handle, stepRunner, handles, active, save, clearIfDurable, }: CompleteStepRunParams): Promise<void>;

package/dist/adapters/in-memory-subprocess/step-completion.js

@@ -0,0 +1,86 @@
+import { nowIso, serializeError } from './metadata';
+//#region Completion handlers
+export async function completeProcessRun({ request, handle, run, handles, active, save, clearIfDurable, }) {
+    try {
+        await run?.(request, handle);
+        const latest = handles.get(handle.id);
+        if (!latest || latest.status !== 'running') {
+            return;
+        }
+        active.delete(handle.id);
+        await save({
+            ...latest,
+            status: 'completed',
+            updatedAt: nowIso(),
+        });
+        // Clear the durable handle manifest once the run has terminated so
+        // `listLive()` stops returning this handle. Without this call the
+        // manifest would persist until `stop()` was called, making every
+        // completed step look live from the adapter's persistence layer.
+        await clearIfDurable(handle.id);
+    }
+    catch (err) {
+        active.delete(handle.id);
+        const latest = handles.get(handle.id) ?? handle;
+        await save({
+            ...latest,
+            status: 'failed',
+            updatedAt: nowIso(),
+            metadata: {
+                ...(latest.metadata ?? {}),
+                error: serializeError(err),
+            },
+        });
+        // Same rationale as the success branch above — clear the durable
+        // manifest so `listLive()` doesn't resurrect this handle on reboot.
+        await clearIfDurable(handle.id);
+    }
+}
+export async function completeStepRun({ request, handle, stepRunner, handles, active, save, clearIfDurable, }) {
+    try {
+        const executor = request._localExecutor;
+        let result;
+        if (executor) {
+            result = await executor();
+        }
+        else if (stepRunner) {
+            result = await stepRunner(request, handle);
+        }
+        else {
+            throw new Error(`In-memory subprocess adapter has no executor for step "${request.stepId}". ` +
+                'Provide a stepRunner option or dispatch via AgentHarness.');
+        }
+        const latest = handles.get(handle.id);
+        if (!latest || latest.status !== 'running') {
+            return;
+        }
+        active.delete(handle.id);
+        await save({
+            ...latest,
+            status: 'completed',
+            updatedAt: nowIso(),
+            metadata: {
+                ...(latest.metadata ?? {}),
+                result,
+            },
+        });
+        // Clear the durable step manifest once the run has terminated —
+        // see `completeProcessRun` above for the rationale.
+        await clearIfDurable(handle.id);
+    }
+    catch (err) {
+        active.delete(handle.id);
+        const latest = handles.get(handle.id) ?? handle;
+        await save({
+            ...latest,
+            status: 'failed',
+            updatedAt: nowIso(),
+            metadata: {
+                ...(latest.metadata ?? {}),
+                error: serializeError(err),
+            },
+        });
+        await clearIfDurable(handle.id);
+    }
+}
+//#endregion

package/dist/adapters/in-memory-subprocess/types.d.ts

@@ -0,0 +1,88 @@
+import type { StorageAdapter } from '../../types/memory';
+import type { ProcessSubprocessRequest, StepSubprocessRequest, SubprocessHandle, SubprocessHandleMetadata, SubprocessRequest } from '../../types/subprocess-adapter';
+/**
+ * @public
+ * Options for `createInMemorySubprocessAdapter`. All hooks are optional;
+ * when none is provided the adapter still handles `spawn` + `stop` +
+ * lifecycle transitions for test-double purposes.
+ */
+export interface CreateInMemorySubprocessAdapterOptions {
+    /**
+     * Invoked for `kind: 'process'` requests (the classic test-double hook).
+     * When absent the adapter marks the handle `completed` on the next
+     * microtask without running any body.
+     */
+    run?: (request: SubprocessRequest, handle: SubprocessHandle) => Promise<void>;
+    /**
+     * Invoked for `kind: 'step'` requests that do not already carry a
+     * `_localExecutor` closure. Callers swap this out to simulate step
+     * execution in tests; the default harness-bound adapter provides an
+     * implementation that invokes the in-process execute pipeline.
+     */
+    stepRunner?: (request: StepSubprocessRequest, handle: SubprocessHandle) => Promise<unknown>;
+    /**
+     * Optional synchronous metadata injector. Called during `spawn()` before
+     * the handle is returned, its result is merged on top of the adapter's
+     * intrinsic metadata (runtime, command/args/cwd, etc.). Use this to stamp
+     * pid / pidStarttime / test-only fields without having to wrap the adapter.
+     *
+     * Keys returned here win over the adapter's defaults — tests can override
+     * `runtime` if they need to simulate a different adapter variant.
+     */
+    metadataInjector?: (request: SubprocessRequest) => Partial<SubprocessHandleMetadata>;
+    /**
+     * Optional `StorageAdapter` that gives the in-memory adapter a durable
+     * handle manifest. When supplied, `spawn()` persists a manifest per
+     * handle and `reattach(handleId)` / `listLive()` consult it across adapter
+     * restarts. When absent the adapter is purely ephemeral — matching the
+     * test-double semantics established in Phase A.
+     *
+     * For in-memory the "reattached" handle is an idempotent re-run of the
+     * step from the persisted `serializedInput`. We're honest about that in
+     * the manifest (`reattachMode: 'replay'`) — this is the sanest in-memory
+     * semantic because there is no long-lived process to bind back to.
+     */
+    storage?: StorageAdapter;
+}
+export interface CompleteProcessRunParams {
+    request: ProcessSubprocessRequest;
+    handle: SubprocessHandle;
+    run: CreateInMemorySubprocessAdapterOptions['run'];
+    handles: Map<string, SubprocessHandle>;
+    active: Set<string>;
+    save: (handle: SubprocessHandle) => Promise<SubprocessHandle>;
+    /** Invoked on terminal transitions so the durable handle manifest
+     *  does not linger after the step is done — otherwise `listLive()`
+     *  would return phantom handles for every step ever completed
+     *  against this storage. No-op when no storage was configured. */
+    clearIfDurable: (handleId: string) => Promise<void>;
+}
+export interface CompleteStepRunParams {
+    request: StepSubprocessRequest;
+    handle: SubprocessHandle;
+    stepRunner: CreateInMemorySubprocessAdapterOptions['stepRunner'];
+    handles: Map<string, SubprocessHandle>;
+    active: Set<string>;
+    save: (handle: SubprocessHandle) => Promise<SubprocessHandle>;
+    /** See `CompleteProcessRunParams.clearIfDurable`. */
+    clearIfDurable: (handleId: string) => Promise<void>;
+}
+/**
+ * Persistable manifest for an in-memory handle. Written to the
+ * StorageAdapter on spawn and cleared on stop — a restart can list live
+ * handles via this prefix and re-run the step from `serializedInput`.
+ *
+ * Scoped to `step`-kind requests because `process`-kind handles carry no
+ * replayable body (they represent already-launched OS processes whose state
+ * is not ours to recreate).
+ */
+export interface InMemoryStepManifest {
+    kind: 'step';
+    handleId: string;
+    stepId: string;
+    executionId: string;
+    serializedInput: unknown;
+    overrides: StepSubprocessRequest['overrides'];
+    startedAt: string;
+    reattachMode: 'replay';
+}

package/dist/adapters/in-memory-subprocess/types.js

@@ -0,0 +1,2 @@
+export {};
+//#endregion

package/dist/adapters/in-memory-subprocess-adapter.d.ts

@@ -1,5 +1,13 @@
-import type { SubprocessAdapter, SubprocessHandle, SubprocessRequest } from '../types/subprocess-adapter';
-export interface CreateInMemorySubprocessAdapterOptions {
-    run?: (request: SubprocessRequest, handle: SubprocessHandle) => Promise<void>;
-}
+import type { SubprocessAdapter } from '../types/subprocess-adapter';
+import type { CreateInMemorySubprocessAdapterOptions } from './in-memory-subprocess/types';
+export type { CreateInMemorySubprocessAdapterOptions } from './in-memory-subprocess/types';
+/**
+ * @public
+ * In-memory `SubprocessAdapter` for tests and non-durable in-process
+ * step execution. When an optional `StorageAdapter` is supplied the
+ * adapter persists per-handle manifests so `reattach()` / `listLive()`
+ * work across adapter instances — the reattached handle is an idempotent
+ * re-run of the step from the persisted `serializedInput`, not a bind to
+ * a live process (there is none to bind to for in-memory).
+ */
 export declare function createInMemorySubprocessAdapter(options?: CreateInMemorySubprocessAdapterOptions): SubprocessAdapter;

package/dist/adapters/in-memory-subprocess-adapter.js

@@ -1,68 +1,135 @@
-function nowIso() {
-    return new Date().toISOString();
-}
-async function completeInMemoryRun({ request, handle, run, handles, active, save, }) {
-    try {
-        await run?.(request, handle);
-        const latest = handles.get(handle.id);
-        if (!latest || latest.status !== 'running') {
+import { clearManifest, listManifests, loadManifest, persistStepManifest, } from './in-memory-subprocess/manifest-persistence';
+import { buildProcessMetadata, buildStepMetadata, isProcessRequest, isStepRequest, nowIso, } from './in-memory-subprocess/metadata';
+import { completeProcessRun, completeStepRun } from './in-memory-subprocess/step-completion';
+//#region Factory
+/**
+ * @public
+ * In-memory `SubprocessAdapter` for tests and non-durable in-process
+ * step execution. When an optional `StorageAdapter` is supplied the
+ * adapter persists per-handle manifests so `reattach()` / `listLive()`
+ * work across adapter instances — the reattached handle is an idempotent
+ * re-run of the step from the persisted `serializedInput`, not a bind to
+ * a live process (there is none to bind to for in-memory).
+ */
+export function createInMemorySubprocessAdapter(options = {}) {
+    const handles = new Map();
+    const active = new Set();
+    const storage = options.storage;
+    async function save(handle) {
+        handles.set(handle.id, handle);
+        return handle;
+    }
+    /**
+     * Persist a step manifest after spawn so `reattach` and `listLive` can
+     * find this handle again on a subsequent adapter instance. Errors are
+     * logged rather than propagated — a failed manifest write must not break
+     * otherwise-successful step dispatch.
+     */
+    async function persistIfDurable(request, handle) {
+        if (!storage) {
             return;
         }
-        active.delete(handle.id);
-        await save({
-            ...latest,
-            status: 'completed',
-            updatedAt: nowIso(),
+        try {
+            await persistStepManifest(storage, request, handle);
+        }
+        catch (err) {
+            console.warn(`createInMemorySubprocessAdapter: failed to persist manifest for "${handle.id}":`, err);
+        }
+    }
+    async function clearIfDurable(handleId) {
+        if (!storage) {
+            return;
+        }
+        try {
+            await clearManifest(storage, handleId);
+        }
+        catch (err) {
+            console.warn(`createInMemorySubprocessAdapter: failed to clear manifest for "${handleId}":`, err);
+        }
+    }
+    function injectMetadata(request, intrinsic) {
+        if (!options.metadataInjector) {
+            return intrinsic;
+        }
+        return {
+            ...intrinsic,
+            ...options.metadataInjector(request),
+        };
+    }
+    async function spawnStepHandle(request) {
+        const now = nowIso();
+        const handle = {
+            id: `subprocess-${crypto.randomUUID()}`,
+            status: 'running',
+            startedAt: now,
+            updatedAt: now,
+            metadata: injectMetadata(request, buildStepMetadata(request)),
+        };
+        active.add(handle.id);
+        await save(handle);
+        await persistIfDurable(request, handle);
+        void completeStepRun({
+            request,
+            handle,
+            stepRunner: options.stepRunner,
+            handles,
+            active,
+            save,
+            clearIfDurable,
         });
+        return handle;
     }
-    catch (err) {
-        active.delete(handle.id);
-        const latest = handles.get(handle.id) ?? handle;
-        await save({
-            ...latest,
-            status: 'failed',
+    async function spawnProcessHandle(request) {
+        const now = nowIso();
+        const handle = {
+            id: `subprocess-${crypto.randomUUID()}`,
+            status: 'running',
+            startedAt: now,
+            updatedAt: now,
+            metadata: injectMetadata(request, buildProcessMetadata(request)),
+        };
+        active.add(handle.id);
+        await save(handle);
+        void completeProcessRun({
+            request,
+            handle,
+            run: options.run,
+            handles,
+            active,
+            save,
+            clearIfDurable,
+        });
+        return handle;
+    }
+    /**
+     * Build a hydrated handle from a persisted manifest. Status is `running`
+     * so consumers see the handle as live; a subsequent `reattach` call
+     * re-dispatches the step via the supplied `stepRunner`.
+     */
+    function handleFromManifest(manifest) {
+        return {
+            id: manifest.handleId,
+            status: 'running',
+            startedAt: manifest.startedAt,
             updatedAt: nowIso(),
             metadata: {
-                ...(latest.metadata ?? {}),
-                error: err instanceof Error ? err.message : String(err),
+                runtime: 'in-memory',
+                kind: 'step',
+                stepId: manifest.stepId,
+                executionId: manifest.executionId,
+                reattachMode: manifest.reattachMode,
             },
-        });
-    }
-}
-export function createInMemorySubprocessAdapter(options = {}) {
-    const handles = new Map();
-    const active = new Set();
-    async function save(handle) {
-        handles.set(handle.id, handle);
-        return handle;
+        };
     }
     return {
         async spawn(request) {
-            const now = nowIso();
-            const handle = {
-                id: `subprocess-${crypto.randomUUID()}`,
-                status: 'running',
-                startedAt: now,
-                updatedAt: now,
-                metadata: {
-                    ...(request.metadata ?? {}),
-                    runtime: 'in-memory',
-                    command: request.command,
-                    args: request.args ?? [],
-                    cwd: request.cwd,
-                },
-            };
-            active.add(handle.id);
-            await save(handle);
-            void completeInMemoryRun({
-                request,
-                handle,
-                run: options.run,
-                handles,
-                active,
-                save,
-            });
-            return handle;
+            if (isStepRequest(request)) {
+                return spawnStepHandle(request);
+            }
+            if (isProcessRequest(request)) {
+                return spawnProcessHandle(request);
+            }
+            throw new Error('Unsupported subprocess request variant.');
         },
         async get(handleId) {
             return handles.get(handleId) ?? null;
@@ -76,6 +143,7 @@ export function createInMemorySubprocessAdapter(options = {}) {
                 };
             }
             active.delete(handleId);
+            await clearIfDurable(handleId);
             const next = await save({
                 ...handle,
                 status: 'stopped',
@@ -122,5 +190,46 @@ export function createInMemorySubprocessAdapter(options = {}) {
         async isAlive(handle) {
             return active.has(handle.id);
         },
+        /**
+         * Idempotent re-run of a persisted step, not a "resume" — for in-memory
+         * there is no long-lived process to bind back to. The adapter's
+         * `reattachMode` on the manifest reflects this honestly. When no
+         * storage was configured we fall back to the ephemeral semantics
+         * established in Phase A (returning `null`).
+         */
+        async reattach(handleId) {
+            if (!storage) {
+                return null;
+            }
+            const manifest = await loadManifest(storage, handleId);
+            if (!manifest) {
+                return null;
+            }
+            const handle = handleFromManifest(manifest);
+            active.add(handle.id);
+            await save(handle);
+            return handle;
+        },
+        async listLive() {
+            const live = new Map();
+            for (const id of active) {
+                const handle = handles.get(id);
+                if (handle) {
+                    live.set(handle.id, handle);
+                }
+            }
+            if (storage) {
+                const manifests = await listManifests(storage);
+                for (const manifest of manifests) {
+                    if (!live.has(manifest.handleId)) {
+                        live.set(manifest.handleId, handleFromManifest(manifest));
+                    }
+                }
+            }
+            return [
+                ...live.values(),
+            ];
+        },
     };
 }
+//#endregion

package/dist/adapters/openrouter.d.ts

@@ -1,10 +1,11 @@
 import type * as OpenRouterAgent from '@openrouter/agent';
-import type { LLMResponse, Tool } from '../types/common';
+import type { LLMResponse } 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';
+import type { Tool } from '../types/tool';
 type ProviderOutputItem = OpenRouterAgent.OpenResponsesResult['output'][number];
 type OpenRouterInputItem = OpenRouterAgent.EasyInputMessage | OpenRouterAgent.FunctionCallItem | OpenRouterAgent.FunctionCallOutputItem | ProviderOutputItem;
 /** @internal */
@@ -28,6 +29,14 @@ export declare function itemsToInput(items: ReadonlyArray<Item>): OpenRouterInpu
 export declare function extractOutputItems(response: OpenRouterAgent.OpenResponsesResult): Item[];
 /** @internal */
 export declare function extractUsage(usage: OpenRouterAgent.Usage | null | undefined): LLMResponse['usage'];
+/**
+ * Provider APIs (Anthropic via OpenRouter) enforce tool names match
+ * `^[a-zA-Z0-9_-]{1,64}$`. Noetic's internal layer-tool names use `layerId/fn`
+ * which contains a forbidden `/`. We translate to a wire-safe form only at
+ * the SDK boundary; internal tool-name identity (and every codebase reference
+ * to names like `plan/updatePrd`) is preserved.
+ */
+export declare function sanitizeToolNameForWire(name: string): string;
 /** @internal */
 export declare function convertTools({ tools }: ConvertToolsParams): SdkTool[];
 /** @internal */
@@ -53,5 +62,5 @@ export declare function executeToolCall(params: ExecuteToolCallParams): Promise<
  * @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 declare function createOpenRouterEmbed(apiKey?: string, embeddingModel?: string): EmbedFn;
 export {};