@wrongstack/cli 1.1.4 → 1.1.6

package/dist/subcommands/handlers/hq.d.ts

@@ -1,24 +1,3 @@
-/**
- * `wstack hq` subcommand group — HQ command center lifecycle + browser
- * token management.
- *
- * Subcommand tree:
- *   wstack hq                      → start HQ server (alias for `wstack --hq`)
- *   wstack hq serve                → start HQ server (explicit form)
- *   wstack hq token create [label] [--ttl <duration>] → mint a browser token, write auth.json
- *   wstack hq token create --client [label] [--ttl <duration>] → mint a client token (/ws/client)
- *   wstack hq token list           → list issued browser tokens
- *   wstack hq token list --client   → list issued client tokens
- *   wstack hq token revoke <id>    → revoke a browser token (prefix match)
- *   wstack hq token revoke --client <id> → revoke a client token
- *   wstack hq service install|status|update|uninstall → Ubuntu systemd lifecycle
- *
- * All subcommands accept `--data-dir <path>` to override the HQ data
- * directory (default `~/.wrongstack/hq`, honors `WRONGSTACK_HOME` /
- * `WRONGSTACK_HQ_DATA_DIR`).
- *
- * @module subcommands/handlers/hq
- */
 import type { SubcommandHandler } from '../contracts.js';
 export declare const hqCmd: SubcommandHandler;
 //# sourceMappingURL=hq.d.ts.map

package/dist/subcommands/handlers/per-subcommand-help-operations.d.ts

@@ -0,0 +1,8 @@
+import type { PerSubcommandHelp } from './per-subcommand-help-types.js';
+/**
+ * Focused help for the lifecycle, integration and operations subcommands
+ * (update, remote, acp, bench, hq, mailbox, permissions, project, sage,
+ * chronicle, …) — spread into `helpTable` after the core commands.
+ */
+export declare const OPERATIONS_HELP_ENTRIES: Record<string, PerSubcommandHelp>;
+//# sourceMappingURL=per-subcommand-help-operations.d.ts.map

package/dist/subcommands/handlers/tools-cli-args.d.ts

@@ -0,0 +1,57 @@
+import type { JSONSchema } from '@wrongstack/core/types';
+export declare class ToolsCliUsageError extends Error {
+}
+/** Where `wstack tools` writes and reads — injectable for tests. */
+export interface ToolsCliIo {
+    stdout(text: string): void;
+    stderr(text: string): void;
+    readStdin(): Promise<string>;
+}
+/** Upper bound for `--input` from stdin or `@file` — tool calls, not a payload upload. */
+export declare const TOOLS_CLI_MAX_INPUT_BYTES: number;
+/**
+ * Raw text behind `--input`: absent → undefined; a bare `--input` or
+ * `--input=-` → stdin (`--input -` parses as bare: the top-level parser never
+ * takes a dash-led token as a value); `@path` → file relative to cwd; anything
+ * else → the value itself. A leading BOM (editors, `Out-File`) is dropped.
+ */
+export declare function readInputText(raw: string | boolean | undefined, cwd: string, readStdin: () => Promise<string>): Promise<{
+    text: string;
+    source: string;
+} | undefined>;
+/** A tool input must be a JSON object; blank text is `{}`. */
+export declare function parseInputObject(text: string, source: string): Record<string, unknown>;
+/**
+ * `wstack tools run grep -- --pattern foo --path src --context 2`: map the
+ * tokens after `--` onto the tool's input schema.
+ *
+ * Only after `--`: before it, the top-level parser owns every `--flag`, and a
+ * field that shares a name with a global switch (`--json`, `--yolo`, `--all`)
+ * would be read as that switch. Values are coerced by the property's declared
+ * type — string, integer/number, boolean (`--flag`, `--no-flag`,
+ * `--flag=false`), array (repeat the flag, or pass a JSON array), object (JSON).
+ * Enums, ranges and required fields are left to the executor's schema
+ * validation, which reports them as invalid input.
+ */
+export declare function parseSchemaArgs(tokens: readonly string[], schema: JSONSchema | undefined): Record<string, unknown>;
+export interface BatchCall {
+    /** 1-based line number in the batch input. */
+    line: number;
+    id?: unknown;
+    tool: string;
+    input: Record<string, unknown>;
+}
+export type BatchLine = BatchCall | {
+    line: number;
+    id?: unknown;
+    error: string;
+};
+/**
+ * JSONL batch: one `{"tool": "...", "input": {...}, "id"?: any}` per line.
+ * Blank lines are skipped. A malformed line becomes an error entry rather than
+ * aborting the batch, so every other call still reports; only exceeding
+ * {@link TOOLS_CLI_MAX_BATCH_CALLS} rejects the batch as a whole.
+ */
+export declare function parseBatchLines(text: string): BatchLine[];
+export declare function readStream(stream: NodeJS.ReadableStream, maxBytes: number): Promise<string>;
+//# sourceMappingURL=tools-cli-args.d.ts.map

package/dist/subcommands/handlers/tools-cli.d.ts

@@ -0,0 +1,5 @@
+import type { SubcommandDeps } from '../contracts.js';
+import { type ToolsCliIo } from './tools-cli-args.js';
+export type { ToolsCliIo } from './tools-cli-args.js';
+export declare function runToolsCli(verb: string, args: readonly string[], deps: SubcommandDeps, io?: ToolsCliIo): Promise<number>;
+//# sourceMappingURL=tools-cli.d.ts.map

package/dist/subcommands/handlers/tools-serve.d.ts

@@ -0,0 +1,4 @@
+import type { SubcommandDeps } from '../contracts.js';
+import type { ToolsCliIo } from './tools-cli-args.js';
+export declare function serveToolsCommand(args: readonly string[], deps: SubcommandDeps, io: ToolsCliIo, waitForShutdown?: () => Promise<void>): Promise<number>;
+//# sourceMappingURL=tools-serve.d.ts.map

package/dist/{subcommands-YADUV7IJ.js → subcommands-SKJPUJ7N.js}

@@ -1,10 +1,10 @@
 import {
   subcommandNames,
   subcommands
-} from "./chunk-2LTHDKZX.js";
+} from "./chunk-W7X23HI6.js";
 import "./chunk-W23PY4IJ.js";
 export {
   subcommandNames,
   subcommands
 };
-//# sourceMappingURL=subcommands-YADUV7IJ.js.map
+//# sourceMappingURL=subcommands-SKJPUJ7N.js.map

package/dist/tool-gateway-http.d.ts

@@ -0,0 +1,30 @@
+import type { ToolRegistry } from '@wrongstack/core/registry';
+import { type ToolGateway } from './tool-gateway.js';
+export interface ToolGatewayHttpOptions {
+    gateway: ToolGateway;
+    /** For `withheldReason` on tools the gateway does not expose. */
+    registry: ToolRegistry;
+    /** Required. Every route but `/health` checks `Authorization: Bearer <token>`. */
+    token: string;
+    /** TCP port; 0 picks a free one. */
+    port?: number | undefined;
+    /** Default 127.0.0.1. */
+    host?: string | undefined;
+    /** Allow `callback.url` to name a non-loopback host. Default false. */
+    allowRemoteCallbacks?: boolean | undefined;
+    maxConcurrentCalls?: number | undefined;
+    /** Do not keep the process alive for this server (an in-process side service). */
+    unref?: boolean | undefined;
+    log?: ((message: string) => void) | undefined;
+    /** Injectable for tests. */
+    fetchImpl?: typeof fetch | undefined;
+}
+export interface ToolGatewayHttpHandle {
+    url: string;
+    port: number;
+    host: string;
+    /** Resolves once every accepted async call has settled and its callback was attempted. */
+    close(): Promise<void>;
+}
+export declare function serveToolGatewayHttp(opts: ToolGatewayHttpOptions): Promise<ToolGatewayHttpHandle>;
+//# sourceMappingURL=tool-gateway-http.d.ts.map

package/dist/tool-gateway.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Tool gateway — the one execution core behind every surface that lets an
+ * EXTERNAL caller drive WrongStack's built-in tools without an agent loop.
+ *
+ * Two adapters sit on top of it today:
+ * - `wstack mcp serve`  — MCP over stdio/HTTP (`mcp-serve.ts`)
+ * - `wstack tools run`  — one call per process (`subcommands/handlers/tools-cli.ts`)
+ *
+ * Both used to need the same subtle decisions — which tools are exposed, which
+ * permission policy applies, whether file tools are confined to the project
+ * root, and that every call gets a fresh Context. Keeping those in one place is
+ * the point: a second hand-written copy is how a surface quietly ends up with a
+ * wider default than the other.
+ */
+import { Context } from '@wrongstack/core/agent';
+import { ToolRegistry } from '@wrongstack/core/registry';
+import { AutoApprovePermissionPolicy } from '@wrongstack/core/security';
+import type { Config, PermissionPolicy, Tool, ToolSettlement, ToolsConfig } from '@wrongstack/core/types';
+/**
+ * The registry a gateway serves: the subcommand's pre-populated one when the
+ * dispatcher built it, else a fresh built-in tier. Also binds the Kanban ports
+ * the `kanban` tool resolves at call time.
+ */
+export declare function resolveGatewayRegistry(existing: ToolRegistry | undefined, config: Pick<Config, 'features'>): ToolRegistry;
+/**
+ * Parse `--allow fs.write,shell.exec` into capability ids. Every entry must be
+ * a known capability — a typo silently granting nothing would read as "the
+ * tool is broken", and a typo that matched something unintended would widen
+ * the grant. A bare `--allow` (no list) is an error, never "allow everything".
+ */
+export declare function parseCapabilityGrants(raw: string | boolean | undefined): string[];
+/**
+ * `--yolo` for the gateway: widen the CAPABILITY allowlist, keep every guard.
+ *
+ * This replaced an `AllowAllPermissionPolicy extends AutoApprovePermissionPolicy`
+ * whose `evaluate()` returned `{ permission: 'auto' }` unconditionally. That
+ * override skipped the whole base implementation — the sensitive-read denial,
+ * the leader deny rules, the destructive-command classifier, the agent-state
+ * write guard, and `LOCKED_DESTRUCTIVE_KINDS`. It was the only place in the
+ * codebase where `agent-state` and `credential-bind` could be un-gated, so a
+ * third-party MCP client could have written `hooks` into config.json (boot-time
+ * RCE) or `auto: true` into trust.json.
+ *
+ * It did not actually get there — but only by accident, and the accident is the
+ * reason this is a rewrite rather than a patch. The override returned
+ * `source: 'default'` where the base class returns `source: 'yolo'`, so
+ * `ToolExecutor.capabilityDowngraded` re-armed and forced `confirm`; the gateway
+ * has no confirmAwaiter, so the call hard-errored. Changing that one string
+ * literal to `'yolo'` — which reads as a trivial consistency cleanup — would
+ * have made the bypass live. Safety must not rest on a string nobody knows is
+ * load-bearing.
+ *
+ * Granting every capability is what `--yolo` actually means, and it is what
+ * lets `ToolExecutor` trust an `auto` instead of downgrading it (see the
+ * `dangerousNotAllowed` reasoning in `auto-approve-policy.ts`). The destructive
+ * classifier is deliberately NOT relaxed: `yoloConfirmKinds` is left at its
+ * default, which gates every destructive kind. Destructive calls therefore
+ * still require a confirmation this surface cannot answer, exactly as before —
+ * this change removes a latent bypass without widening anything.
+ */
+export declare function yoloServePolicy(yoloPlus?: () => boolean): AutoApprovePermissionPolicy;
+/**
+ * Whether the file tools are confined to the project root for the gateway.
+ *
+ * The gateway is the one surface where the file tools are driven by a REMOTE
+ * caller, so an unset config must inherit containment rather than invert it —
+ * an unset value here previously became `false`, which short-circuited
+ * `ensureInsideRoot` and let `tools/call read` return `~/.ssh/id_rsa`.
+ *
+ * This lives in one exported function rather than as a literal repeated at each
+ * call site so the invariant is testable and a third call site cannot quietly
+ * reintroduce the wrong default. Only a trusted user config can opt out:
+ * `tools.restrictToProjectRoot` is on the in-project denylist, so a
+ * checked-out repository cannot reach it.
+ */
+export declare function resolveServeFsRestriction(config: {
+    tools?: {
+        restrictToProjectRoot?: boolean | undefined;
+    } | undefined;
+}): boolean;
+/** Minimal run context — tools read cwd/projectRoot/signal; provider/session are stubs. */
+export declare function makeServeContext(cwd: string, projectRoot: string, signal: AbortSignal, restrictFsToRoot?: boolean): Context;
+/**
+ * Compute the set of tools a gateway exposes: a tool is included only if it
+ * passes the whitelist (when set) AND the permission policy returns `auto`.
+ * With `AutoApprovePermissionPolicy` this withholds shell/write/edit and
+ * dangerous-capability tools; with the `--yolo` policy everything passes.
+ */
+export declare function selectExposedTools(registry: ToolRegistry, ctx: Context, policy: PermissionPolicy, whitelist: Set<string> | null): Promise<Tool[]>;
+/** Whether a one-shot call to this tool first catches the index up with the disk. */
+export declare function readsCodebaseIndex(name: string): boolean;
+/**
+ * Why `name` is not callable through `gateway`, in words a caller can act on —
+ * one text for every surface (`wstack tools run`, `wstack tools serve`), since
+ * the flags it names are the same on both.
+ */
+export declare function withheldReason(gateway: ToolGateway, registry: ToolRegistry, name: string): string;
+export interface ToolGatewayOptions {
+    registry: ToolRegistry;
+    /** Only the `tools.*` knobs the gateway reads. */
+    config: {
+        tools?: Partial<Pick<ToolsConfig, 'restrictToProjectRoot' | 'maxToolTimeoutMs' | 'kanbanGovernance'>> | undefined;
+    };
+    cwd: string;
+    projectRoot: string;
+    /** Grant every capability; the subagent locks still refuse. */
+    yolo: boolean;
+    /**
+     * Under `yolo`: whether the user's YOLO+ is on right now (destructive kinds
+     * then pass; the locked ones never do). An in-process worker gateway reads
+     * the live config; the CLI surfaces leave it unset.
+     */
+    yoloPlus?: (() => boolean) | undefined;
+    /**
+     * Capabilities granted on top of the read-only default (`--allow`), each
+     * validated by {@link parseCapabilityGrants}. Ignored under `yolo`.
+     */
+    allow?: readonly string[] | undefined;
+    /** Restrict to these names; null exposes everything the policy allows. */
+    whitelist: Set<string> | null;
+    /**
+     * Each call is its own process (`wstack tools run`): also withhold tools
+     * whose state lives in a session or in the serving process
+     * ({@link oneShotWithholdReason}).
+     */
+    oneShot?: boolean | undefined;
+    /**
+     * A long-lived server whose caller edits the tree with its own tools
+     * (`wstack tools serve`, called by an external agent): withhold the
+     * session-bound tools (process-bound ones work in a long-lived process), and
+     * catch the index up before EVERY index-reading call — the caller's edits
+     * are invisible to WrongStack, so "once per process" would go stale.
+     * Concurrent calls share one catch-up; at most one starts per second.
+     */
+    remoteAgent?: boolean | undefined;
+    /**
+     * One-shot / remote-agent: bring the index up to date with the disk before an
+     * index-reading call ({@link readsCodebaseIndex}) — once per process, and
+     * again after any mutating call. Incremental by mtime (~0.3s on an
+     * unchanged 11k-file repo). Defaults to the real catch-up; injectable for tests.
+     */
+    catchUpIndex?: ((projectRoot: string, signal: AbortSignal) => Promise<void>) | undefined;
+    /** Non-fatal problems (a failed index catch-up) for the caller to surface. */
+    onWarning?: ((message: string) => void) | undefined;
+}
+export type ToolGatewayCallResult = {
+    kind: 'result';
+    content: string;
+    isError: boolean;
+    settlement: ToolSettlement;
+    durationMs: number;
+}
+/** Not in the exposed set — withheld by policy/whitelist, or unknown. */
+ | {
+    kind: 'not_exposed';
+}
+/** The call needs an interactive confirmation the gateway cannot give. */
+ | {
+    kind: 'confirm_required';
+};
+export interface ToolGateway {
+    /** `safe` = read-only default, `granted` = default plus `--allow`, `yolo` = everything. */
+    readonly mode: 'safe' | 'granted' | 'yolo';
+    /** The capability allowlist the policy evaluates against. */
+    readonly capabilities: readonly string[];
+    /** The root the file tools are confined to; per-call `cwd` must lie inside it. */
+    readonly projectRoot: string;
+    /** Exposed tools, in registry order. `list` and `call` always agree. */
+    readonly tools: readonly Tool[];
+    get(name: string): Tool | undefined;
+    /** Whether this surface withholds `name` for living in a session / the serving process. */
+    withheldBy(name: string): 'session' | 'process' | undefined;
+    /**
+     * `options.cwd`: this call's working directory (relative paths, shell
+     * commands). The caller validates it against {@link projectRoot}; the
+     * file tools stay confined to the root either way.
+     */
+    call(name: string, input: Record<string, unknown>, options?: {
+        cwd?: string | undefined;
+    }): Promise<ToolGatewayCallResult>;
+    /** Abort in-flight calls and disconnect from the project daemons. */
+    close(): Promise<void>;
+}
+export declare function createToolGateway(options: ToolGatewayOptions): Promise<ToolGateway>;
+//# sourceMappingURL=tool-gateway.d.ts.map