@xingjisoft/neutrino 0.6.0 → 0.7.0

package/dist/llm/plan.d.ts

@@ -0,0 +1,148 @@
+import { type TaskRuntime } from "./runtime.js";
+import type { ToolDefinition } from "./tools.js";
+/** `active` is the step the worker is on; the rest are its past and future. */
+export type PlanStepStatus = "pending" | "active" | "done" | "failed" | "blocked" | "cancelled" | "skipped";
+export interface PlanStep {
+    id?: string;
+    dependsOn?: string[];
+    acceptanceCriteria?: string[];
+    evidenceIds?: string[];
+    artifacts?: string[];
+    summary?: string;
+    deliverable?: string;
+    /** One imperative action, in the language of the request. */
+    title: string;
+    /** What the step needs: files, parameters, acceptance criteria. */
+    detail?: string;
+    status: PlanStepStatus;
+}
+/** The plan of one user turn, persisted with the session. */
+export interface PlanState {
+    /** The request restated in one line. */
+    goal: string;
+    steps: PlanStep[];
+    /** The turn stopped before the last step: paused, cancelled, or interrupted. */
+    stopped?: boolean;
+}
+/**
+ * One step is not a plan, it is the answer: such a turn runs as a plain turn.
+ * The ceiling keeps the card readable and the turn's cost proportionate.
+ */
+export declare const PLAN_MIN_STEPS = 2;
+export declare const PLAN_MAX_STEPS = 10;
+export declare const PLAN_MAX_TITLE = 160;
+export declare const PLAN_MAX_DETAIL = 400;
+/**
+ * A request longer than this many columns is treated as a brief and planned.
+ * In practice that is roughly eighty Chinese characters or one hundred and
+ * eighty ASCII ones — past that, "one action" is already unlikely.
+ */
+export declare const PLAN_LENGTH_LIMIT = 180;
+/**
+ * Does this request need a plan at all?
+ *
+ * Planning costs a model round-trip before any work starts, and for "rename
+ * this variable" that round-trip is pure friction. A request is planned only
+ * when it shows a reason to be split into steps: it asks for more than one
+ * thing, brings its own structure (a list), reads as a brief (long), or asks
+ * for a plan. Everything else runs in one pass, where the system prompt still
+ * has the agent state the steps it is taking in its own answer.
+ */
+export declare function needsPlan(request: string): boolean;
+/** Turn an already-parsed planner answer into a plan, or null when unusable. */
+export declare function normalizePlan(value: unknown, minSteps?: number): PlanState | null;
+/**
+ * Read a planner answer. JSON first, because that is what the prompt asks for,
+ * then a numbered list so a model that ignores the format still produces a
+ * usable plan. Anything else is "no plan": the turn then runs as before.
+ */
+export declare function parsePlan(text: string, minSteps?: number): PlanState | null;
+export interface PlannerInput {
+    /** The request being planned. */
+    request: string;
+    /** The conversation before that request, oldest first. */
+    transcript?: string;
+    /** Directory the work happens in. */
+    cwd?: string;
+}
+/**
+ * The user turn handed to the planner agent. The planner gets no tools, so
+ * everything it needs to make the steps concrete is in this text: where the
+ * work happens, what was said before, and what is being asked now.
+ */
+export declare function buildPlannerInput(input: PlannerInput): string;
+/** The plan as numbered text: what the worker and the reviewers read. */
+export declare function planSpec(plan: PlanState): string;
+/**
+ * The plan as the user reads it in the transcript. It is an ordinary assistant
+ * message on purpose: it is saved, replayed, folded and sent back to the model
+ * exactly like any other answer.
+ *
+ * A detail stays on its step's line: markdown renderers fold an indented line
+ * into the list item before it, which would run two steps together in the log.
+ */
+export declare function planMessage(plan: PlanState): string;
+/**
+ * The system text for one step. It repeats the whole plan so the worker knows
+ * where the step sits, and states the two rules the split exists for: do only
+ * this step, and stop when it is verified.
+ */
+export declare function renderStepDirective(template: string, plan: PlanState, index: number): string;
+/** How far a plan got. Used by the card header and by tests. */
+export declare function planProgress(plan: PlanState): {
+    done: number;
+    total: number;
+    active: number;
+};
+/** A plan loaded from disk was, by definition, no longer running. */
+export declare function resumePlan(loaded: PlanState | null | undefined): PlanState | null;
+/** Point the plan at one step. Returns false when there was nothing to change. */
+export declare function advancePlan(plan: PlanState | null, index: number, status: PlanStepStatus): boolean;
+/** A turn that cannot continue must not leave a step looking alive. */
+export declare function stopPlan(plan: PlanState | null): boolean;
+/** The message shape both loops share: enough to tell the planner what happened. */
+export interface TranscriptMessage {
+    role: string;
+    content?: string;
+    name?: string;
+    result?: string;
+}
+/** The user message a turn answers. */
+export declare function lastRequestText(messages: readonly TranscriptMessage[]): string;
+/**
+ * The exchanges before the current request, for the planner.
+ *
+ * Tool output is clipped hard: the planner needs to know what was done, not to
+ * re-read it, and a long log must not crowd the request out of its own plan.
+ */
+export declare function planTranscript(messages: readonly TranscriptMessage[]): string;
+/**
+ * One row of the info card. The kind carries the meaning (and therefore the
+ * colour); the text is what goes on screen.
+ */
+export type PlanRowKind = "header" | "step-active" | "step-done" | "step-pending" | "step-failed" | "step-blocked" | "step-cancelled" | "step-skipped" | "connector" | "more" | "line";
+export interface PlanRow {
+    kind: PlanRowKind;
+    text: string;
+}
+/**
+ * Lay the plan out as a vertical timeline, top to bottom in execution order.
+ *
+ * A finished step is drawn dark, a step still to come is drawn lit, and the step
+ * being worked on is the one highlighted row — so the card reads as "these are
+ * done, this is running, these are next" without a legend. When the plan is
+ * longer than the room, a window around the running step is shown with the
+ * number of steps above and below it, rather than dropping the middle.
+ */
+export declare function planCardRows(plan: PlanState, options: {
+    width: number;
+    maxRows: number;
+}): PlanRow[];
+/** The width a card row actually needs, in columns. */
+export declare function planRowsWidth(rows: PlanRow[]): number;
+/** Pro plans use explicit step acceptance instead of inferring success from prose. */
+export declare const FINISH_STEP_TOOL = "finish_step";
+export declare const FINISH_STEP_DEFINITION: ToolDefinition;
+export declare function preparePlan(plan: PlanState): PlanState;
+export declare function finishPlanStep(plan: PlanState | null, args: Record<string, unknown>, runtime: TaskRuntime): string;
+export declare function settlePlan(plan: PlanState | null, cancelled?: boolean): void;

package/dist/llm/retry.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Retry policy for the model connection.
+ *
+ * A single turn is minutes of work, and the connection carries it the whole way.
+ * Providers, and the proxies and load balancers in front of them, drop sockets
+ * for reasons a client can never observe: an idle timeout, a rolling restart, a
+ * middlebox resetting the flow. Those blips clear on their own within seconds,
+ * so a failed request that is simply re-sent saves the turn — while surfacing
+ * the error throws away everything the user typed and everything the model had
+ * already produced.
+ *
+ * The policy is exponential: seven attempts in total, waiting 5s, 10s, 20s,
+ * 40s, 80s and finally 160s between them (about five minutes end to end). The
+ * waits grow because a link that is merely flaky recovers long before the
+ * budget runs out, and a link that is genuinely down must not be hammered.
+ */
+/** Total tries, the first one included. */
+export declare const DEFAULT_NETWORK_ATTEMPTS = 7;
+/** Wait before the first retry; every further retry doubles it. */
+export declare const DEFAULT_RETRY_DELAY_MS = 5000;
+export interface RetryPolicy {
+    /** Total tries, including the first one. */
+    attempts: number;
+    /** Wait before the first retry; doubled for each retry after that. */
+    baseDelayMs: number;
+}
+/**
+ * The policy in force.
+ *
+ * Read on every use rather than cached at import time, so the environment can
+ * tune it (`NEUTRINO_NETWORK_ATTEMPTS`, `NEUTRINO_RETRY_DELAY_MS`) without a
+ * rebuild and the tests can collapse the waits to a millisecond.
+ */
+export declare function retryPolicy(): RetryPolicy;
+/** Wait before retry number `retry` (0-based): base, 2×base, 4×base, … */
+export declare function retryDelayMs(retry: number, policy?: RetryPolicy): number;
+/** What the UI is told before a retried request goes out again. */
+export interface RetryNotice {
+    /** The attempt about to go out (2 = the first retry), 1-based. */
+    attempt: number;
+    /** Total attempts allowed. */
+    attempts: number;
+    /** How long this attempt waits before it is sent. */
+    delayMs: number;
+    /** What went wrong, in the same wording the transcript uses. */
+    reason: string;
+}
+/** A wait in human terms: "5s", "40s", "2m 40s". */
+export declare function formatDelay(ms: number): string;
+export declare const DROP_HINT_RE: RegExp;
+/**
+ * Flatten an error and its `cause` chain into one readable line.
+ *
+ * `fetch` reports almost every transport problem as a bare
+ * `TypeError: fetch failed`; the actual reason (`ECONNRESET`, `EMFILE`,
+ * `ENOTFOUND`, `UND_ERR_…`) is tucked away in `error.cause`. Without walking
+ * that chain a failure is impossible to diagnose, so this always reports it.
+ */
+export declare function describeError(e: unknown): string;
+/**
+ * Whether a failed request is worth retrying: a transient connection problem
+ * (reset / refused / DNS / timeout) rather than a real response from the API.
+ */
+export declare function isRetriableNetworkError(e: unknown): boolean;
+export declare function isRetriableStatus(status: number): boolean;
+/** A response that did arrive, but carried a failure status. */
+export declare class HttpStatusError extends Error {
+    readonly status: number;
+    constructor(status: number, body: string);
+}
+/** Whether a failure is transient, including HTTP statuses that invite a retry. */
+export declare function isRetriableFailure(e: unknown): boolean;
+/**
+ * Sleep before retry number `retry`, in short slices.
+ *
+ * The wait can reach 160s, so it must not be a single `setTimeout`: a paused
+ * turn or a newer message has to be able to cut it short. Returns false when
+ * `cancelled` fired, which tells the caller to stop without an error.
+ */
+export declare function waitBeforeRetry(retry: number, policy: RetryPolicy, cancelled?: () => boolean): Promise<boolean>;

package/dist/llm/risk.d.ts

@@ -0,0 +1,21 @@
+export type RiskLevel = "high" | "extreme";
+export interface RiskAssessment {
+    level: RiskLevel;
+    /** Tool that was called. */
+    tool: string;
+    /** One-line description of what is about to happen. */
+    summary: string;
+    /** Why this was flagged. Shown to the user (and to the AI reviewer). */
+    reasons: string[];
+}
+/** Score a shell command. */
+export declare function assessCommand(command: string, cwd: string): {
+    level: RiskLevel;
+    reasons: string[];
+};
+/**
+ * Classify a single tool call.
+ *
+ * Returns `null` when the call is routine and may run without approval.
+ */
+export declare function assessToolCall(name: string, args: Record<string, unknown>, cwd: string): RiskAssessment | null;

package/dist/llm/risk.js

@@ -14,6 +14,7 @@
  */
 import os from "node:os";
 import path from "node:path";
+import { currentTask } from "./runtime.js";
 /** Wrappers that merely delegate to the command that follows them. */
 const WRAPPERS = new Set([
     "sudo",
@@ -355,6 +356,12 @@ function summarizeArgs(name, args) {
 export function assessToolCall(name, args, cwd) {
     const workingDir = path.resolve(cwd || process.cwd());
     const summary = summarizeArgs(name, args);
+    const plugin = currentTask()?.runtime.plugins?.toolPolicy(name);
+    if (plugin && (plugin.native || plugin.effects.some(e => e !== "filesystem.read"))) {
+        return { level: "high", tool: name, summary, reasons: [plugin.native ? "runs a fully trusted native plugin" : `plugin declares: ${plugin.effects.join(", ")}`] };
+    }
+    if (name === "plugin_fetch")
+        return { level: "high", tool: name, summary: String(args.url ?? name), reasons: ["sends an HTTP request from a plugin"] };
     if (name === "web_search") {
         return {
             level: "high", tool: name, summary,

package/dist/llm/runtime.d.ts

@@ -0,0 +1,189 @@
+import { DiagnosticRecorder } from "./diagnostics.js";
+import type { PlanState } from "./plan.js";
+import type { AgentMode } from "../config.js";
+import type { PluginHost } from "../plugins/host.js";
+import type { PluginPin } from "../plugins/types.js";
+import type { OwnedUI } from "../plugins/host.js";
+export type AgentStatus = "completed" | "partial" | "blocked" | "failed" | "cancelled";
+export interface AgentError {
+    code: string;
+    message: string;
+}
+export interface AgentResult {
+    runId: string;
+    status: AgentStatus;
+    report: string;
+    evidenceIds: string[];
+    artifacts: string[];
+    blockers: string[];
+    error?: AgentError;
+}
+export interface TaskLimits {
+    agentRuns: number;
+    modelRequests: number;
+    toolCalls: number;
+    tokens: number;
+    durationMs: number;
+}
+export type TaskBudgetScope = "task" | "delegation";
+export declare function taskBudgetScope(config: Record<string, unknown>): TaskBudgetScope;
+export interface TaskBudgetStop {
+    code: string;
+    scope: TaskBudgetScope;
+    limit: number;
+    used: number;
+    requested: number;
+    reserved?: number;
+    runId: string;
+}
+export declare const DEFAULT_TASK_LIMITS: Readonly<TaskLimits>;
+export declare function taskLimits(config: Record<string, unknown>): TaskLimits;
+export interface TaskPolicy {
+    readonly readOnly: boolean;
+    /** Each group is an additional restriction; a write must match every group. */
+    readonly writePathGroups: readonly (readonly string[])[];
+}
+export interface TaskScope {
+    readonly signal: AbortSignal;
+    readonly runtime: TaskRuntime;
+    readonly runId: string;
+    readonly parentRunId?: string;
+    readonly role: string;
+    readonly depth: number;
+    readonly policy: TaskPolicy;
+    readonly ancestors: readonly string[];
+}
+export interface ToolEvidence {
+    id: string;
+    runId: string;
+    name: string;
+    arguments: Record<string, unknown>;
+    result: string;
+    status: "completed" | "failed" | "denied" | "cancelled";
+}
+export interface TaskSnapshot {
+    execution_mode?: AgentMode | "pro";
+    plugins?: PluginPin[];
+    pluginErrors?: string[];
+    pluginUI?: OwnedUI[];
+    pluginPrompt?: {
+        role: string;
+        sections: unknown;
+    };
+    rootRunId: string;
+    state: "running" | "cancelling" | AgentStatus;
+    counts: {
+        agentRuns: number;
+        modelRequests: number;
+        toolCalls: number;
+        tokens: number;
+    };
+    limits: TaskLimits;
+    budgetScope?: TaskBudgetScope;
+    delegatedCounts?: {
+        modelRequests: number;
+        toolCalls: number;
+        tokens: number;
+    };
+    budgetStop?: TaskBudgetStop;
+    journal?: string;
+    persistenceError?: string;
+}
+/** A saved task has no live worker after restart. Never replay its tool ledger. */
+export declare function resumeTaskSnapshot(snapshot: TaskSnapshot | undefined): TaskSnapshot | undefined;
+export declare class TaskControlError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare function currentTask(): TaskScope | undefined;
+/** Node 18-compatible signal composition with deterministic listener cleanup. */
+export declare function linkSignals(...values: Array<AbortSignal | undefined>): {
+    signal: AbortSignal;
+    dispose(): void;
+};
+/** One user turn owns one ledger and cancellation tree, with optional root limits. */
+export declare class TaskRuntime {
+    private readonly executionMode?;
+    plugins?: PluginHost;
+    private pluginPrompt?;
+    readonly rootRunId: `${string}-${string}-${string}-${string}-${string}`;
+    readonly diagnostics?: DiagnosticRecorder;
+    readonly signal: AbortSignal;
+    readonly originalRequest: string;
+    readonly priorUserRequests: readonly string[];
+    readonly cwd: string;
+    readonly workspaceOnly: boolean;
+    readonly limits: Readonly<TaskLimits>;
+    readonly budgetScope: TaskBudgetScope;
+    readonly root: TaskScope;
+    readonly evidence: ToolEvidence[];
+    readonly results: AgentResult[];
+    plan?: PlanState;
+    private readonly controller;
+    private readonly deadline?;
+    private readonly delegationController;
+    private delegationDeadline?;
+    private delegationStarted?;
+    private readonly started;
+    private readonly pending;
+    private readonly usage;
+    private readonly delegatedUsage;
+    private reservedTokens;
+    private delegatedReservedTokens;
+    private budgetStop?;
+    private state;
+    private persistenceError?;
+    private readonly journal?;
+    private journalStarted;
+    private journalDiscarded;
+    private readonly detachSignal?;
+    constructor(options: {
+        request: string;
+        cwd?: string;
+        priorUserRequests?: readonly string[];
+        limits?: Partial<TaskLimits>;
+        budgetScope?: TaskBudgetScope;
+        executionMode?: AgentMode | "pro";
+        signal?: AbortSignal;
+        readOnly?: boolean;
+        writePaths?: readonly string[];
+        workspaceOnly?: boolean;
+        journalDir?: string;
+        diagnostics?: DiagnosticRecorder;
+    });
+    run<T>(callback: () => T): T;
+    withSignal<T>(signal: AbortSignal, callback: () => Promise<T>): Promise<T>;
+    child<T>(role: string, task: string, callback: (scope: TaskScope) => Promise<T>, options?: {
+        readOnly?: boolean;
+        writePaths?: readonly string[];
+    }): Promise<T>;
+    check(): void;
+    cancel(reason?: string): void;
+    track<T>(operation: Promise<T>): Promise<T>;
+    activity(): () => void;
+    get settling(): boolean;
+    drain(): Promise<void>;
+    finish(status: AgentStatus): void;
+    snapshot(): TaskSnapshot;
+    instructions(scope?: TaskScope): string;
+    assertTool(name: string, args: Record<string, unknown>, scope?: TaskScope): void;
+    availableTools<T extends {
+        function: {
+            name: string;
+        };
+    }>(tools: T[], scope?: TaskScope): T[];
+    tool(name: string, args: Record<string, unknown>, execute: () => Promise<string>): Promise<string>;
+    recordTool(name: string, args: Record<string, unknown>, result: string, status: ToolEvidence["status"], id?: `${string}-${string}-${string}-${string}-${string}`, runId?: string): ToolEvidence;
+    recordResult(result: AgentResult): void;
+    evidenceFor(runId: string): ToolEvidence[];
+    partialReport(): string;
+    /** Reserve before every actual HTTP attempt, including retries, reviews and summaries. */
+    request(inputTokens: number, outputTokens: number, final?: boolean): {
+        settle(used: number): void;
+    };
+    private isDelegated;
+    private expireTask;
+    private stopBudget;
+    note(type: string, data: unknown): void;
+    private event;
+}