@noetic-tools/core 5.3.0 → 5.4.1

package/dist/deprecated.d.ts

@@ -1,30 +0,0 @@
-/**
- * Deprecated aliases from the "memory layer" era of the framework.
- *
- * The layer system assembles the model's *context window* — recall, budget
- * allocation, history projection, the item-append pipeline — so it is named
- * after context, not memory. Every name below still resolves to its
- * replacement; nothing here changes behaviour.
- *
- * Most of these are plain pass-throughs: the alias and its replacement already
- * live in `@noetic-tools/types` / `@noetic-tools/context`, and re-exporting
- * carries each name's `@deprecated` pointer along with it. Only the renaming
- * aliases — where core exports a symbol under a *different* name than its
- * source package does — are declared here.
- *
- * The matching runtime aliases (the `memory:` config key on `provide`/`spawn`/
- * `tool`/`react`/`AgentHarness`, and the `ctx.memory` accessor) are handled at
- * their call sites — see `resolveContextOption`.
- *
- * Scheduled for removal in the next major of `@noetic-tools/core`.
- */
-export type { ObservationalMemoryConfig, PlanMemoryConfig, TemporalMemoryConfig, WorkingMemoryConfig, WorkingMemoryState, } from '@noetic-tools/context';
-export { observationalMemory, planMemory, temporalMemory, toolMemoryLayer, workingMemory, } from '@noetic-tools/context';
-export type { ContextMemory, InferMemory, InferMemoryShape, MemoryCallModelRequest, MemoryConfig, MemoryHooks, MemoryLayer, MemoryScope, MemoryTraceSpan, ToolMemory, ToolMemoryDeclaration, } from '@noetic-tools/types';
-export { 
-/**
- * @public
- * @deprecated Renamed to `context`. Declared here rather than re-exported
- * because the builder itself lives in core under its new name.
- */
-context as memory, } from './builders/context-builder.js';

package/dist/deprecated.js

@@ -1,28 +0,0 @@
-/**
- * Deprecated aliases from the "memory layer" era of the framework.
- *
- * The layer system assembles the model's *context window* — recall, budget
- * allocation, history projection, the item-append pipeline — so it is named
- * after context, not memory. Every name below still resolves to its
- * replacement; nothing here changes behaviour.
- *
- * Most of these are plain pass-throughs: the alias and its replacement already
- * live in `@noetic-tools/types` / `@noetic-tools/context`, and re-exporting
- * carries each name's `@deprecated` pointer along with it. Only the renaming
- * aliases — where core exports a symbol under a *different* name than its
- * source package does — are declared here.
- *
- * The matching runtime aliases (the `memory:` config key on `provide`/`spawn`/
- * `tool`/`react`/`AgentHarness`, and the `ctx.memory` accessor) are handled at
- * their call sites — see `resolveContextOption`.
- *
- * Scheduled for removal in the next major of `@noetic-tools/core`.
- */
-export { observationalMemory, planMemory, temporalMemory, toolMemoryLayer, workingMemory, } from '@noetic-tools/context';
-export { 
-/**
- * @public
- * @deprecated Renamed to `context`. Declared here rather than re-exported
- * because the builder itself lives in core under its new name.
- */
-context as memory, } from './builders/context-builder.js';

package/dist/interpreter/execute-sub-harness.d.ts

@@ -1,8 +0,0 @@
-/**
- * SubHarness step handler: drives an external coding-agent harness
- * (Claude Code, Codex, opencode, pi) for one agentic turn and folds its output
- * back into the Noetic execution context — the harness analogue of
- * `executeLLM`.
- */
-import type { Context, StepSubHarness } from '@noetic-tools/types';
-export declare function executeSubHarness<TContext, I, O>(step: StepSubHarness<TContext, I, O>, input: I, ctx: Context<TContext>): Promise<O>;

package/dist/interpreter/execute-sub-harness.js

@@ -1,241 +0,0 @@
-/**
- * SubHarness step handler: drives an external coding-agent harness
- * (Claude Code, Codex, opencode, pi) for one agentic turn and folds its output
- * back into the Noetic execution context — the harness analogue of
- * `executeLLM`.
- */
-import { createMessage, extractAssistantText, frameworkCast, NoeticConfigError, NoeticErrorImpl, } from '@noetic-tools/types';
-import { ZodError } from 'zod';
-import { resolveLazy } from './execute-action.js';
-import { trackUsage } from './message-helpers.js';
-import { SubHarnessEventBridge } from './sub-harness-events.js';
-import { isContextImpl, isFunctionCall, isMutableContext } from './typeguards.js';
-//#endregion
-//#region Helpers
-function sessionStore(ctx) {
-    return frameworkCast(ctx.harness).subHarnessSessions;
-}
-async function resolveSubHarness(step, ctx) {
-    const resolved = await resolveLazy(step.harness, ctx);
-    if (!resolved) {
-        throw new NoeticConfigError({
-            code: 'MISSING_SUB_HARNESS',
-            message: `step.${step.kind}(${JSON.stringify(step.id)}) resolved no harness adapter.`,
-            hint: 'Pass a harness factory result, e.g. harness: claudeCode({ model }).',
-        });
-    }
-    if (resolved.harnessId !== step.kind) {
-        throw new NoeticConfigError({
-            code: 'SUB_HARNESS_KIND_MISMATCH',
-            message: `step.${step.kind}(${JSON.stringify(step.id)}) was given a '${resolved.harnessId}' harness.`,
-            hint: `Use the matching builder for this adapter, e.g. step.${resolved.harnessId}({ ... }).`,
-        });
-    }
-    return resolved;
-}
-function resolveTurnText(resolvedPrompt, input) {
-    if (resolvedPrompt && resolvedPrompt.length > 0) {
-        return resolvedPrompt;
-    }
-    return typeof input === 'string' ? input : '';
-}
-/**
- * Abort signal of the executing context, when it is a framework context. Handed
- * to the adapter so `ctx.abort()` / `harness.cancel()` stops the coding agent's
- * in-flight turn instead of leaving a sub-process running until it finishes.
- */
-function abortSignalOf(ctx) {
-    return isContextImpl(ctx) ? ctx.abortSignal : undefined;
-}
-function buildRunContext(ctx) {
-    return {
-        cwd: ctx.cwdState.cwd,
-        fs: ctx.fs,
-        shell: ctx.shell,
-        subprocess: ctx.subprocess,
-        threadId: ctx.threadId,
-        signal: abortSignalOf(ctx),
-    };
-}
-function toLlmResponse(result) {
-    const usage = result.usage;
-    return {
-        items: result.items,
-        usage: {
-            inputTokens: usage?.input ?? 0,
-            outputTokens: usage?.output ?? 0,
-            cachedTokens: usage?.cached,
-        },
-        cost: result.cost,
-    };
-}
-function applyTurnResult(ctx, result) {
-    const toolCalls = [];
-    for (const item of result.items) {
-        ctx.itemLog.append(item);
-        if (isFunctionCall(item)) {
-            toolCalls.push(item);
-        }
-    }
-    const llmResponse = toLlmResponse(result);
-    trackUsage(ctx, llmResponse);
-    const meta = {
-        toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
-        usage: result.usage ? llmResponse.usage : undefined,
-        cost: result.cost,
-        responseItems: result.items,
-    };
-    if (isMutableContext(ctx)) {
-        ctx.lastStepMeta = meta;
-    }
-}
-async function teardownSession(session, mode) {
-    if (mode === 'detach' && session.doDetach) {
-        await session.doDetach();
-        return;
-    }
-    if (mode === 'destroy' && session.doDestroy) {
-        await session.doDestroy();
-        return;
-    }
-    await session.doStop();
-}
-async function startOrReuseSession(step, harness, ctx, baseCtx, history) {
-    const reuseKey = step.session?.reuse;
-    const store = sessionStore(baseCtx);
-    if (reuseKey) {
-        const existing = store.get(reuseKey);
-        if (existing) {
-            return {
-                session: existing,
-                reuseKey,
-            };
-        }
-    }
-    const session = await harness.doStart({
-        settings: step.settings,
-        instructions: await resolveLazy(step.instructions, ctx),
-        history,
-        ctx: buildRunContext(baseCtx),
-        signal: abortSignalOf(baseCtx),
-    });
-    if (reuseKey) {
-        store.set(reuseKey, session);
-    }
-    return {
-        session,
-        reuseKey,
-    };
-}
-/**
- * Tear the session down per policy after a successful turn. Reused sessions
- * stay alive by default; an explicit `onComplete` overrides that.
- */
-async function finalizeSession(resolution, policy, baseCtx) {
-    const { session, reuseKey } = resolution;
-    if (!reuseKey) {
-        await teardownSession(session, policy?.onComplete ?? 'stop');
-        return;
-    }
-    const mode = policy?.onComplete;
-    if (mode === 'stop' || mode === 'destroy') {
-        await teardownSession(session, mode);
-        sessionStore(baseCtx).delete(reuseKey);
-        return;
-    }
-    if (mode === 'detach') {
-        await teardownSession(session, 'detach');
-    }
-    // Default for a reused session: keep it alive in the store.
-}
-//#endregion
-//#region Public API
-export async function executeSubHarness(step, input, ctx) {
-    const baseCtx = frameworkCast(ctx);
-    const harness = await resolveSubHarness(step, ctx);
-    const resolvedPrompt = await resolveLazy(step.prompt, ctx);
-    const turnText = resolveTurnText(resolvedPrompt, input);
-    if (turnText.trim() === '') {
-        throw new NoeticConfigError({
-            code: 'MISSING_PROMPT',
-            message: `step.${step.kind}(${JSON.stringify(step.id)}) resolved an empty prompt.`,
-            hint: 'Provide a non-empty `prompt`, or pass a string input to the step.',
-        });
-    }
-    // Capture the conversation so far (from earlier LLM/sub-harness steps and
-    // turns) BEFORE appending this turn's prompt, so a fresh session is seeded
-    // with full context of the conversation.
-    const priorHistory = [
-        ...baseCtx.itemLog.items,
-    ];
-    baseCtx.itemLog.append(createMessage(turnText, 'user'));
-    const resolution = await startOrReuseSession(step, harness, ctx, baseCtx, priorHistory);
-    const bridge = new SubHarnessEventBridge(step, baseCtx);
-    bridge.begin();
-    let result;
-    try {
-        result = await resolution.session.doPromptTurn({
-            prompt: turnText,
-            emit: (part) => bridge.forward(part),
-            // Per-turn signal, so a session reused across turns is cancelled by the
-            // context running the CURRENT turn rather than the one that started it.
-            signal: abortSignalOf(baseCtx),
-        });
-    }
-    catch (e) {
-        // Best-effort teardown of a fresh session before surfacing the failure;
-        // reused sessions are left intact for a later step to retry against.
-        if (!resolution.reuseKey) {
-            await teardownSession(resolution.session, 'destroy').catch(() => undefined);
-        }
-        if (e instanceof NoeticErrorImpl) {
-            throw e;
-        }
-        // An adapter interrupted by the abort signal rejects with whatever its SDK
-        // throws; the context is the authority on why the turn ended.
-        if (baseCtx.aborted) {
-            throw new NoeticErrorImpl({
-                kind: 'cancelled',
-                reason: baseCtx.abortReason ?? 'context aborted',
-            });
-        }
-        throw new NoeticErrorImpl({
-            kind: 'step_failed',
-            stepId: step.id,
-            cause: e instanceof Error ? e : new Error(String(e)),
-            retriesExhausted: false,
-        });
-    }
-    bridge.finalize(result);
-    applyTurnResult(baseCtx, result);
-    await finalizeSession(resolution, step.session, baseCtx);
-    const lastText = result.text.length > 0 ? result.text : extractAssistantText(result.items);
-    if (step.output) {
-        try {
-            const parsed = JSON.parse(lastText);
-            return step.output.parse(parsed);
-        }
-        catch (e) {
-            if (e instanceof SyntaxError || e instanceof ZodError) {
-                throw new NoeticErrorImpl({
-                    kind: 'llm_parse_error',
-                    stepId: step.id,
-                    raw: lastText,
-                    schema: step.output,
-                    zodError: e instanceof ZodError
-                        ? e
-                        : new ZodError([
-                            {
-                                code: 'custom',
-                                message: `Invalid JSON: ${e.message}`,
-                                path: [],
-                            },
-                        ]),
-                });
-            }
-            throw e;
-        }
-    }
-    return frameworkCast(lastText);
-}
-//#endregion

package/dist/interpreter/sub-harness-events.d.ts

@@ -1,48 +0,0 @@
-/**
- * Maps a sub-harness turn's output onto the harness's observable event surface.
- *
- * A sub-harness adapter emits {@link SubHarnessStreamPart}s; this bridge
- * translates each one into the same `source: 'sdk'` broadcaster events the
- * model-call path emits, so a coding agent's text, reasoning, and tool calls
- * flow through `getTextStream()` / `getReasoningStream()` / `getItemStream()` /
- * `getFullStream()` exactly like an LLM step's output. It also re-emits the raw
- * part as a `sub_harness_event` framework event for harness-native consumers.
- *
- * `finalize()` guarantees a turn always emits its output: if an adapter returns
- * a result without streaming any text/tool parts, the result's content is
- * synthesized into events.
- */
-import type { Context, ContextData, StepSubHarness, SubHarnessStreamPart, SubHarnessTurnResult } from '@noetic-tools/types';
-export declare class SubHarnessEventBridge {
-    private readonly broadcaster?;
-    private readonly agentName;
-    private readonly stepId;
-    private readonly stepKind;
-    private readonly emitOption;
-    private started;
-    private completed;
-    private nextOutputIndex;
-    private messageOutputIndex;
-    private sawText;
-    private sawToolCall;
-    constructor(step: Pick<StepSubHarness, 'id' | 'kind' | 'emit'>, ctx: Context<ContextData>);
-    /**
-     * Open the turn on the event surface. Emits `response.created` so every turn
-     * always brackets with a lifecycle marker — even a custom adapter that
-     * streams nothing still emits output.
-     */
-    begin(): void;
-    /** Forward one stream part: a structured framework event + the mapped sdk events. */
-    forward(part: SubHarnessStreamPart): void;
-    /**
-     * Ensure the turn's output reached the event surface. For adapters that
-     * return a result without streaming, synthesize events from the result.
-     */
-    finalize(result: SubHarnessTurnResult): void;
-    private sdk;
-    private start;
-    private openMessage;
-    private closeMessage;
-    private emitToolCall;
-    private translate;
-}

package/dist/interpreter/sub-harness-events.js

@@ -1,208 +0,0 @@
-/**
- * Maps a sub-harness turn's output onto the harness's observable event surface.
- *
- * A sub-harness adapter emits {@link SubHarnessStreamPart}s; this bridge
- * translates each one into the same `source: 'sdk'` broadcaster events the
- * model-call path emits, so a coding agent's text, reasoning, and tool calls
- * flow through `getTextStream()` / `getReasoningStream()` / `getItemStream()` /
- * `getFullStream()` exactly like an LLM step's output. It also re-emits the raw
- * part as a `sub_harness_event` framework event for harness-native consumers.
- *
- * `finalize()` guarantees a turn always emits its output: if an adapter returns
- * a result without streaming any text/tool parts, the result's content is
- * synthesized into events.
- */
-import { emitFrameworkEvent, getBroadcaster, shouldEmit } from '../runtime/broadcaster-utils.js';
-import { isFunctionCall } from './typeguards.js';
-export class SubHarnessEventBridge {
-    broadcaster;
-    agentName;
-    stepId;
-    stepKind;
-    emitOption;
-    started = false;
-    completed = false;
-    nextOutputIndex = 0;
-    messageOutputIndex = null;
-    sawText = false;
-    sawToolCall = false;
-    constructor(step, ctx) {
-        this.broadcaster = getBroadcaster(ctx);
-        this.agentName = ctx.harness.config.name;
-        this.stepId = step.id;
-        this.stepKind = step.kind;
-        this.emitOption = step.emit;
-    }
-    /**
-     * Open the turn on the event surface. Emits `response.created` so every turn
-     * always brackets with a lifecycle marker — even a custom adapter that
-     * streams nothing still emits output.
-     */
-    begin() {
-        this.start();
-    }
-    /** Forward one stream part: a structured framework event + the mapped sdk events. */
-    forward(part) {
-        if (!this.broadcaster) {
-            return;
-        }
-        const data = {
-            stepId: this.stepId,
-            kind: this.stepKind,
-            part,
-        };
-        if (shouldEmit(this.emitOption, 'sub_harness_event', data)) {
-            emitFrameworkEvent({
-                broadcaster: this.broadcaster,
-                agentName: this.agentName,
-                eventType: 'sub_harness_event',
-                data,
-            });
-        }
-        this.translate(part);
-    }
-    /**
-     * Ensure the turn's output reached the event surface. For adapters that
-     * return a result without streaming, synthesize events from the result.
-     */
-    finalize(result) {
-        if (!this.broadcaster) {
-            return;
-        }
-        if (!this.sawText && result.text.length > 0) {
-            this.openMessage();
-            this.sdk('response.output_text.delta', {
-                delta: result.text,
-            }, this.messageOutputIndex ?? 0);
-            this.sawText = true;
-        }
-        if (!this.sawToolCall) {
-            for (const item of result.items) {
-                if (isFunctionCall(item)) {
-                    this.emitToolCall(item.callId, item.name, item.arguments);
-                }
-            }
-        }
-        this.closeMessage();
-        // Always close the turn so every turn emits a completion marker.
-        if (!this.completed) {
-            this.start();
-            this.sdk('response.completed', {});
-            this.completed = true;
-        }
-    }
-    //#region internals
-    sdk(type, data, outputIndex) {
-        if (!this.broadcaster) {
-            return;
-        }
-        if (!shouldEmit(this.emitOption, type, data)) {
-            return;
-        }
-        this.broadcaster.emit({
-            source: 'sdk',
-            type,
-            data,
-            outputIndex,
-        });
-    }
-    start() {
-        if (this.started) {
-            return;
-        }
-        this.started = true;
-        this.sdk('response.created', {});
-    }
-    openMessage() {
-        if (this.messageOutputIndex !== null) {
-            return;
-        }
-        this.start();
-        const id = `sub-harness-msg-${crypto.randomUUID()}`;
-        this.messageOutputIndex = this.nextOutputIndex++;
-        this.sdk('response.output_item.added', {
-            item: {
-                id,
-                type: 'message',
-                role: 'assistant',
-                status: 'in_progress',
-                content: [
-                    {
-                        type: 'output_text',
-                        text: '',
-                    },
-                ],
-            },
-        }, this.messageOutputIndex);
-    }
-    closeMessage() {
-        if (this.messageOutputIndex === null) {
-            return;
-        }
-        const index = this.messageOutputIndex;
-        this.sdk('response.output_text.done', {}, index);
-        this.sdk('response.output_item.done', {}, index);
-        this.messageOutputIndex = null;
-    }
-    emitToolCall(toolCallId, name, input) {
-        this.start();
-        const index = this.nextOutputIndex++;
-        const args = typeof input === 'string' ? input : JSON.stringify(input ?? {});
-        this.sdk('response.output_item.added', {
-            item: {
-                id: toolCallId,
-                type: 'function_call',
-                status: 'in_progress',
-                callId: toolCallId,
-                name,
-                arguments: '',
-            },
-        }, index);
-        this.sdk('response.function_call_arguments.delta', {
-            delta: args,
-        }, index);
-        this.sdk('response.function_call_arguments.done', {
-            arguments: args,
-        }, index);
-        this.sdk('response.output_item.done', {}, index);
-        this.sawToolCall = true;
-    }
-    translate(part) {
-        if (part.type === 'stream-start') {
-            this.start();
-            return;
-        }
-        if (part.type === 'text-delta') {
-            this.openMessage();
-            this.sdk('response.output_text.delta', {
-                delta: part.delta,
-            }, this.messageOutputIndex ?? 0);
-            this.sawText = true;
-            return;
-        }
-        if (part.type === 'reasoning-delta') {
-            this.start();
-            this.sdk('response.reasoning.delta', {
-                delta: part.delta,
-            });
-            return;
-        }
-        if (part.type === 'tool-call') {
-            this.closeMessage();
-            this.emitToolCall(part.toolCallId, part.toolName, part.input);
-            return;
-        }
-        if (part.type === 'finish') {
-            this.closeMessage();
-            this.sdk('response.completed', {
-                finishReason: part.finishReason,
-            });
-            this.completed = true;
-            return;
-        }
-        // file-change | tool-result | error | raw — surfaced on the full stream only.
-        this.sdk(`sub_harness.${part.type}`, {
-            part,
-        });
-    }
-}

package/dist/patterns/interview.d.ts

@@ -1,53 +0,0 @@
-import type { ContextData } from '@noetic-tools/context';
-import type { Step } from '@noetic-tools/types';
-import type { ZodType } from 'zod';
-/** @public Answer captured by the host for a single interview question. */
-export interface InterviewQuestionAnswer {
-    questionId: string;
-    question: string;
-    answer: string | string[];
-    notes?: string;
-}
-/** @public Result of running an `interview()` step. */
-export type InterviewResult<Q, C> = {
-    status: 'complete';
-    envelope: C;
-} | {
-    status: 'maxQuestions';
-    lastQuestion?: Q;
-};
-/** @public Configuration for the `interview()` pattern. */
-export interface InterviewOpts<Q, C> {
-    /** System prompt instructing the model on how to interview the user. */
-    systemPrompt: string;
-    /** Model identifier passed to `step.llm`. */
-    model: string;
-    /** Zod schema for the `data` payload of a `question` envelope. */
-    questionSchema: ZodType<Q>;
-    /** Zod schema for the `data` payload of a `complete` envelope. */
-    completeSchema: ZodType<C>;
-    /** Host renders the question (e.g. via AskUserService) and returns the answer. */
-    askQuestion: (envelope: Q) => Promise<InterviewQuestionAnswer>;
-    /** Called once when the model emits the complete envelope. */
-    onComplete: (envelope: C) => Promise<void>;
-    /** Hard cap on question/complete turns before the loop exits with `maxQuestions`. Default 8. */
-    maxQuestions?: number;
-    /**
-     * Override how a captured answer becomes the next user message. Default emits a
-     * compact, machine-readable JSON line that the model can parse to build context.
-     */
-    formatAnswer?: (answer: InterviewQuestionAnswer) => string;
-}
-/**
- * Creates a host-callback-driven structured interview pattern. Internally a loop over a single
- * body step that delegates to `step.llm` (with `output: discriminatedUnion('type', [...])`) and
- * then hands the envelope to the host. `askQuestion` renders questions and returns answers fed
- * back as the next user message; `onComplete` fires once when the model emits `complete`.
- * Termination via `until.verified(complete) || until.maxSteps(maxQuestions)`.
- *
- * @public
- * @param opts - System prompt, model, question/complete schemas, host callbacks, optional caps.
- * @returns A `Step` whose output is `InterviewResult<Q, C>` — either the completion envelope or
- *          `maxQuestions` when the budget is exhausted before the model emits `complete`.
- */
-export declare function interview<Q, C>(opts: InterviewOpts<Q, C>): Step<ContextData, string, InterviewResult<Q, C>>;