@vincemakes/kiso-tools-node 0.45.2 → 0.46.0

package/README.md

@@ -5,4 +5,11 @@ read_file, list_dir, search_text (idempotent reads), write_file,
 edit_file (safe replacement — external hard links are never
 overwritten), and shell (process-tree kill on timeout/abort).
 
+Background tasks (ADR-0058): pass `tasks: (sessionId) => …` — the
+runtime's per-session `TaskManager`, with `processTaskBackend()` — and the
+shell promotes a command that outlives `foregroundMs` to a task instead of
+killing it, starts one at once with `background: true`, ends its wait on
+`readyWhen`; `task_stop` joins the tools and `read_file` serves the
+session's task outputs. Without `tasks`, the shell is unchanged.
+
 See the repository README for the framework overview.

package/dist/index.d.ts

@@ -17,7 +17,7 @@
  * states what was dropped (deterministic per file state), so the model
  * always has a path to the full content.
  */
-import { type Tool, type ToolResult } from "@vincemakes/kiso-core";
+import { type AbortSignalLike, type Tool, type ToolResult } from "@vincemakes/kiso-core";
 /**
  * TUI2-R1 (C) — THE SHELL PROGRESS SIDECAR.
  *
@@ -106,6 +106,17 @@ export interface WorkspaceToolsOptions {
      *  secrets — so it says so. Ignored when `shellEnv` is "inherit", which is
      *  an explicit opt-in to the whole environment. */
     readonly secretEnvNames?: readonly string[];
+    /** ADR-0058 §4: read-only roots `read_file` may also serve, by ABSOLUTE
+     *  path and only inside them — a session's task outputs. Nothing else
+     *  widens: every other tool, and every relative path, stays inside the
+     *  workspace. */
+    readonly extraReadRoots?: readonly string[];
+    /** ADR-0058 (3b): the session's tasks. With them the shell promotes a
+     *  command that outlives its wait instead of killing it, can start one
+     *  in the background, `task_stop` joins the tools, and `read_file`
+     *  serves the session's task outputs. Absent: today's shell, its schema
+     *  byte for byte. */
+    readonly tasks?: (sessionId: string | undefined) => ShellTasks | undefined;
     /**
      * DC-54 — the bounds that keep a tool call finite. Every field is
      * optional and defaults to the constant beside it; a host embedding
@@ -188,9 +199,95 @@ export { PROTECTED_REFUSAL, diskPath, isProtectedPath, protectedIdentity, protec
  *  read-only shell allow holds a shell read to the same definition rather
  *  than a copy of it. */
 export { isCredentialName, isCredentialPath } from "./corpus.js";
-export declare function shellTool(opts: WorkspaceToolsOptions): Tool<{
+export { processTaskBackend, type ProcessTaskBackend, type ProcessTaskBackendOptions } from "./process-backend.js";
+/**
+ * ADR-0058 (3b): a session's tasks, as the shell and `task_stop` reach them.
+ * The runtime's TaskManager satisfies it structurally; the host hands one
+ * per session (tools-node takes no dependency on the runtime).
+ */
+export interface ShellTasks {
+    /** `<store root>/<session>.tasks` — read_file serves it. */
+    readonly root: string;
+    /** `background: true` — a runner owns the command (it survives kiso). */
+    start(spec: {
+        readonly command: string;
+        readonly cwd: string;
+        readonly env?: Readonly<Record<string, string | undefined>>;
+        readonly executionId?: string;
+        readonly readyWhen?: string;
+        readonly profile?: "oneshot" | "service";
+    }): Promise<{
+        readonly id: string;
+        readonly outputPath: string;
+    }>;
+    /** A promotion: the running child becomes a task this process owns. */
+    adopt(spec: {
+        readonly command: string;
+        readonly cwd: string;
+        readonly executionId?: string;
+        readonly readyWhen?: string;
+        readonly runner: {
+            readonly pid: number;
+            readonly startedAt: string;
+        };
+        readonly ready?: boolean;
+        readonly stop: () => void;
+    }): {
+        readonly id: string;
+        readonly outputPath: string;
+        ready(match: string): void;
+        ended(exitCode: number | null, signal: string | null): void;
+        unconfirmed(pids: readonly number[]): void;
+    };
+    stop(id: string, by: "model"): boolean;
+    get(id: string): {
+        readonly state: {
+            readonly kind: string;
+        };
+    } | undefined;
+    /** ADR-0058 Amendment 7: wait for a task's end (or ready line) that this
+     *  call's result will report; what it sees is claimed for `executionId`,
+     *  so it is never noticed. Without it the calls return at once (today's
+     *  results, a notice to follow). */
+    awaitSettled?(id: string, until: "end" | "ready", ms: number, opts: {
+        readonly executionId?: string;
+        readonly signal?: AbortSignalLike;
+    }): Promise<{
+        readonly info: SettledTask;
+        readonly settled: boolean;
+        readonly claimed: boolean;
+    }>;
+    /** 3e: a running foreground command that can be moved to the background
+     *  now (the person's key, a steer) — registered while it runs. */
+    registerDetachable?(executionId: string, detachable: {
+        readonly startedAt: number;
+        detach(by: "person" | "steer"): void;
+    }): () => void;
+}
+/** What a settled wait reports about its task. */
+interface SettledTask {
+    readonly state: {
+        readonly kind: string;
+        readonly ready?: boolean;
+        readonly exitCode?: number | null;
+        readonly signal?: string | null;
+        readonly error?: string;
+    };
+    readonly outputPath: string;
+    readonly startedAt: number;
+    readonly endedAt?: number;
+}
+type ShellInput = {
     command: string;
     timeoutMs?: number;
+    foregroundMs?: number;
+    background?: boolean;
+    readyWhen?: string;
+};
+export declare function shellTool(opts: WorkspaceToolsOptions): Tool<ShellInput>;
+/** ADR-0058 §4: stop a task this session started — its whole process group. */
+export declare function taskStopTool(opts: WorkspaceToolsOptions): Tool<{
+    id: string;
 }>;
 /** The full coding toolset, bound to one workspace root (Area 5). */
 export declare function createCodingTools(opts: WorkspaceToolsOptions): readonly Tool<any>[];