@dolusoft/command-console-core 1.0.1 → 1.1.0

package/dist/types/core/console/console.types.d.ts

@@ -1,7 +1,7 @@
-import type { CommandResponse, CommandSpec, ConsoleEntry, ContextFrame } from '@dolusoft/command-protocol';
+import type { Actor, CommandOutcome, CommandResponse, CommandSpec, ConsoleEntry, ContextFrame } from '@dolusoft/command-protocol';
 import type { KeyInput } from '../../shared/keys.js';
 import type { Updater } from '../../store/action.js';
-import type { BeforeRunResult, CommandDefinition, RunInfo } from '../dispatch/dispatch.types.js';
+import type { BeforeRunResult, CommandDefinition, ConsoleGate, RunInfo } from '../dispatch/dispatch.types.js';
 /** The live input line. */
 export interface InputState {
     value: string;
@@ -154,7 +154,28 @@ export interface ConsoleOptions<TFeatures extends Partial<OptionalFeatures> = {}
     recallLimit?: number;
     /** Whether a line is recorded (recall feature); default every line. */
     shouldRecord?: (line: string) => boolean;
+    /**
+     * Sends the lines of commands with `input` and `danger` as envelopes and
+     * runs them from their echo (ADR 0012); fixed for the life of the console.
+     */
+    gate?: ConsoleGate;
+    /** The view instance a typed line targets, read when the line ends. */
+    activeView?: () => string | undefined;
+    /** How long an envelope waits for its echo, in ms; default 5000. */
+    echoTimeoutMs?: number;
+    /** Makes envelope ids; default `crypto.randomUUID()`. */
+    createEnvelopeId?: () => string;
 }
+/** What `request()` runs: a command and its input, or a line. */
+export type RequestInput = {
+    command: string;
+    args: Record<string, unknown>;
+    view?: string;
+    actor: Actor;
+} | {
+    line: string;
+    actor: Actor;
+};
 /** The methods every console has. */
 export interface CoreConsoleAPI<TFeatures extends Partial<OptionalFeatures> = {}> {
     /** The committed state; the same object until the next change. */
@@ -203,6 +224,11 @@ export interface CoreConsoleAPI<TFeatures extends Partial<OptionalFeatures> = {}
     run(line: string): Promise<boolean>;
     /** Interrupts the running command, else cancels the live line. */
     cancel(): void;
+    /**
+     * Runs a command for a caller other than the user's Enter (an agent).
+     * Never rejects: every refusal or failure is an `error` outcome.
+     */
+    request(input: RequestInput): Promise<CommandOutcome>;
     /** Applies the key map; `true` when the key was handled. */
     handleKey(input: KeyInput): boolean;
 }

package/dist/types/core/dispatch/commandError.d.ts

@@ -0,0 +1,24 @@
+import type { ErrorCode } from '@dolusoft/command-protocol';
+/**
+ * The codes a command's `run` may end with through a `CommandError`. The
+ * other codes belong to the core (`busy`, `timeout`, `id-conflict`, …); a
+ * `CommandError` that carries one gives `failed`.
+ */
+export type CommandErrorCode = Extract<ErrorCode, 'target-not-found' | 'invalid-args' | 'failed'>;
+/**
+ * Thrown (or rejected) by a command's `run` to end the run with `code`: the
+ * run fails as with any error (`onError`, the error entry), and the outcome a
+ * `request()` resolves is `{ status: 'error', code }`.
+ */
+export declare class CommandError extends Error {
+    /** The code the run's outcome carries. */
+    readonly code: CommandErrorCode;
+    constructor(code: CommandErrorCode, message?: string, options?: ErrorOptions);
+}
+/**
+ * The outcome code of an error a command's `run` threw: a `CommandError`'s
+ * code when a command may give it, else `failed` (C-86). The error is known
+ * by its `name`, not by `instanceof`: a command built against a second copy
+ * of the core throws a `CommandError` of another class.
+ */
+export declare const commandErrorCode: (error: unknown) => CommandErrorCode;

package/dist/types/core/dispatch/dispatch.types.d.ts

@@ -1,4 +1,4 @@
-import type { CommandResponse, CommandSpec, ContextFrame, OutputBlock, OutputEntry } from '@dolusoft/command-protocol';
+import type { CommandResponse, CommandSpec, ContextFrame, Envelope, JsonValue, OutputBlock, OutputEntry } from '@dolusoft/command-protocol';
 /**
  * What `beforeRun` returns: `undefined` goes on to the command's `run`;
  * `false` ends the run silently; a response ends the run as if the command
@@ -36,6 +36,12 @@ export interface CommandDefinition extends CommandSpec {
      * Called only for safe positions (README: Completion).
      */
     complete?(request: CompletionRequest): CompletionResult;
+    /**
+     * Maps the validated input of a command with `input` before it is sent or
+     * run (a relative time made absolute). Pure; its result is checked again
+     * against the schema.
+     */
+    normalize?(input: Record<string, JsonValue>): Record<string, JsonValue>;
 }
 /** The parsed line a command runs with. */
 export interface CommandRequest {
@@ -51,6 +57,27 @@ export interface CommandRequest {
     line: string;
     /** The context frames when the run started, bottom → top, root excluded. */
     context: ContextFrame[];
+    /**
+     * The validated, normalized input of a command with `input`; `args`, `rest`
+     * and `line` then come from its canonical line.
+     */
+    input?: Record<string, JsonValue>;
+    /** The view instance the line targets (`activeView()` or the request's). */
+    view?: string;
+}
+/**
+ * What the console sends envelopes through (ADR 0012). The consumer's
+ * transport implements it; the core never touches the network.
+ */
+export interface ConsoleGate {
+    /** The id of this tab, the same for the life of the page. */
+    tab: string;
+    /** Sends an envelope; a rejection ends the operation as `connection-lost`. */
+    send(envelope: Envelope): Promise<void>;
+    /** Calls `listener` with every value the transport receives. */
+    subscribe(listener: (raw: unknown) => void): () => void;
+    /** Calls `fn` once after `ms`; returns the function that cancels it. */
+    schedule(ms: number, fn: () => void): () => void;
 }
 /** The handle a running command gets. */
 export interface RunContext {

package/dist/types/core/dispatch/dispatch.utils.d.ts

@@ -1,10 +1,11 @@
-import type { CommandResponse, CommandSpec, OutputBlock } from '@dolusoft/command-protocol';
+import { type CommandResponse, type CommandSpec, type OutputBlock } from '@dolusoft/command-protocol';
 import type { CommandDefinition, CommandReturn } from './dispatch.types.js';
 /**
  * Validates the commands (core README: Options, C-56): names and aliases are
  * non-empty, without whitespace or quotes, unique across every name and alias;
- * `fromArg` is a non-negative integer; `run` is a function. Throws on the
- * first violation.
+ * `fromArg` is a non-negative integer; `run` is a function; `input` is an
+ * input schema, `danger` a known value and `normalize` a function (C-76).
+ * Throws on the first violation.
  */
 export declare const validateCommands: (commands: unknown) => void;
 /** The JSON spec of a command, without its functions (`getCommands`). */

package/dist/types/core/dispatch/operation.d.ts

@@ -0,0 +1,23 @@
+import type { CommandDefinition } from './dispatch.types.js';
+import type { AnyConsoleOptions } from '../console/console.types.js';
+/** Whether two JSON values are equal, objects compared by their keys. */
+export declare const sameJson: (a: unknown, b: unknown) => boolean;
+/** Remembers `id` among the newest `closedLimit` closed ids. */
+export declare const rememberClosed: (closed: Set<string>, id: string) => void;
+/** `summary` cut to `summaryLimit` code points; `undefined` unless a string. */
+export declare const cutSummary: (summary: unknown) => string | undefined;
+/**
+ * What makes envelope ids: `createEnvelopeId`, else the page's UUID function.
+ * Throws when a gate is given and neither exists (C-78).
+ */
+export declare const envelopeIds: (options: Pick<AnyConsoleOptions, "gate" | "createEnvelopeId">) => (() => string) | undefined;
+/**
+ * Checks the gate options at creation and on every `setOptions` (C-78):
+ * envelope ids can be made, and `echoTimeoutMs` is a finite number above 0.
+ */
+export declare const checkGateOptions: (options: Pick<AnyConsoleOptions, "gate" | "createEnvelopeId" | "echoTimeoutMs">) => void;
+/**
+ * Whether a command can travel in an envelope: it has `input` and `danger`
+ * and no `sensitive` (C-79).
+ */
+export declare const describedCommand: (command: CommandDefinition) => boolean;

package/dist/types/helpers/agentTools.d.ts

@@ -0,0 +1,34 @@
+import type { JsonValue } from '@dolusoft/command-protocol';
+import type { CoreConsoleAPI } from '../core/console/console.types.js';
+/** The hints a tool carries (WebMCP `ToolAnnotations`). */
+export interface AgentToolAnnotations {
+    /** The tool does not change the application. */
+    readOnlyHint?: boolean;
+    /** The result may hold text the agent should not take as instructions. */
+    untrustedContentHint?: boolean;
+}
+/** One tool, as a WebMCP `ModelContextTool` takes it. */
+export interface AgentTool {
+    /** `context`, `help` or `run`. */
+    name: string;
+    /** What the tool does, for the agent. */
+    description: string;
+    /** A JSON Schema of the tool's input. */
+    inputSchema: {
+        [key: string]: JsonValue;
+    };
+    /** The tool's hints. */
+    annotations: AgentToolAnnotations;
+    /** Never rejects: a failure is an `error` outcome. */
+    execute(input: unknown): Promise<JsonValue>;
+}
+/** What `agentTools` needs besides the console. */
+export interface AgentToolsOptions {
+    /** What the `context` tool returns: the tab, its views, the active view. */
+    context: () => JsonValue | Promise<JsonValue>;
+}
+/**
+ * The `context`, `help` and `run` tools of `console` (C-83). `run` calls
+ * `console.request` as `external-agent`, so only `read` commands run.
+ */
+export declare function agentTools(console: Pick<CoreConsoleAPI, 'getCommands' | 'request'>, options: AgentToolsOptions): [AgentTool, AgentTool, AgentTool];

package/dist/types/index.d.ts

@@ -1,8 +1,12 @@
 export { consoleFeatures, createConsole } from './helpers/consoleFeatures.js';
+export { agentTools } from './helpers/agentTools.js';
+export { CommandError } from './core/dispatch/commandError.js';
+export type { CommandErrorCode } from './core/dispatch/commandError.js';
+export type { AgentTool, AgentToolAnnotations, AgentToolsOptions } from './helpers/agentTools.js';
 export { contextFeature } from './features/context/contextFeature.js';
 export { recallFeature } from './features/recall/recallFeature.js';
 export { completionFeature } from './features/completion/completionFeature.js';
-export type { CompletionAPI, CompletionFeature, CompletionSession, Console, ConsoleOptions, ConsoleState, ContextAPI, ContextFeature, ControllableState, CoreConsoleAPI, FeatureAPIsOf, InputState, OptionalFeatures, RecallAPI, RecallFeature, RunningCommand } from './core/console/console.types.js';
-export type { BeforeRunResult, CommandDefinition, CommandRequest, CommandReturn, CompletionRequest, CompletionResult, RunContext, RunInfo } from './core/dispatch/dispatch.types.js';
+export type { CompletionAPI, CompletionFeature, CompletionSession, Console, ConsoleOptions, ConsoleState, ContextAPI, ContextFeature, ControllableState, CoreConsoleAPI, FeatureAPIsOf, InputState, OptionalFeatures, RecallAPI, RecallFeature, RequestInput, RunningCommand } from './core/console/console.types.js';
+export type { BeforeRunResult, CommandDefinition, CommandRequest, CommandReturn, CompletionRequest, CompletionResult, ConsoleGate, RunContext, RunInfo } from './core/dispatch/dispatch.types.js';
 export type { KeyInput } from './shared/keys.js';
 export type { Updater } from './store/action.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dolusoft/command-console-core",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "The engine of a headless command console: createConsole, its features (recall, completion, context) and redaction of sensitive lines. No framework.",
   "private": false,
   "type": "module",
@@ -32,7 +32,7 @@
   "homepage": "https://github.com/dolusoft/command-console#readme",
   "license": "MIT",
   "dependencies": {
-    "@dolusoft/command-protocol": "1.0.1"
+    "@dolusoft/command-protocol": "1.1.0"
   },
   "scripts": {
     "build": "vite build && tsc -p tsconfig.build.json && node ../../scripts/emit-type-extensions.mjs dist/types"