@ordewell/core 0.8.0 → 0.9.0

package/README.md

@@ -5,7 +5,7 @@ dependencies, shared by the CLI, the terminal UI, the VS Code extension and the
 local API server.
 
 This package is published so those surfaces can depend on it. It has no CLI of
-its own — if you want to *use* Ordewell, install
+its own. If you want to *use* Ordewell, install
 **[@ordewell/cli](https://www.npmjs.com/package/@ordewell/cli)** instead.
 
 ```bash
@@ -16,11 +16,11 @@ npm install @ordewell/core
 
 | Module | Responsibility |
 | --- | --- |
-| `Session` | One plan's full lifecycle — generation, execution, mutation, persistence |
+| `Session` | One plan's full lifecycle: generation, execution, mutation, persistence |
 | `PlanStore` | All plan-shaped state: the task tree, status sets, runner set |
 | `Planner` | The read-only model that researches a repo and emits the plan |
-| `TaskOrchestrator` | Pure scheduler — dependency order and parallelism |
-| `VerdictEngine` | Completion verification — the runner's attempt-bound `task_complete` call; the model is never the tie-breaker |
+| `TaskOrchestrator` | Pure scheduler: dependency order and parallelism |
+| `VerdictEngine` | Completion verification from the runner's attempt-bound `task_complete` call; the model is never the tie-breaker |
 | `ModelResolver` / `ModeResolver` | Per-task model routing and mode resolution |
 | `RunnerRegistry` | Built-in runner manifests |
 
@@ -32,7 +32,7 @@ Subpath exports: `@ordewell/core/parsing`, `/plan-utils`, `/testing`.
 ## Stability
 
 Pre-1.0. The surfaces in this monorepo are the intended consumers, and the API
-changes with them — pin an exact version if you depend on it directly.
+changes with them. Pin an exact version if you depend on it directly.
 
 The domain vocabulary these names come from is defined in
 [CONTEXT.md](https://github.com/ordewell/ordewell/blob/main/CONTEXT.md).

package/dist/{IFileSystem-D96mT-bm.d.ts → IFileSystem-DpaaFdit.d.ts}

@@ -1,4 +1,4 @@
-import { I as IApproval } from './IRunner-CGCihlGQ.js';
+import { I as IApproval } from './IRunner-BiQio8gJ.js';
 
 interface ToolOutcome {
     success: boolean;

package/dist/{IFileSystem-DXJCRw5x.d.mts → IFileSystem-_m7HdoxJ.d.mts}

@@ -1,4 +1,4 @@
-import { I as IApproval } from './IRunner-XVUddYVX.mjs';
+import { I as IApproval } from './IRunner-CxiymkP_.mjs';
 
 interface ToolOutcome {
     success: boolean;

package/dist/{IRunner-CGCihlGQ.d.ts → IRunner-BiQio8gJ.d.ts}

@@ -2,6 +2,78 @@ import { ChildProcess } from 'child_process';
 import { ao as UsageRecord, a8 as SubagentOutcome, W as RunnerId, ag as TaskSkillSnapshot } from './Task-1Q19y7sZ.js';
 import { z } from 'zod/v4';
 
+/**
+ * The planner's standing approvals (ADR-0026): what runs without asking
+ * anyone, under every approval mode.
+ *
+ * One entry is one of:
+ *
+ *   - a **command rule**, `gh issue list` or `gcloud * * list`: the binary,
+ *     then words matched against the command's leading arguments, the ones
+ *     before its first flag. A command whose leading words match the rule's
+ *     runs, whatever arguments follow — but the rule must spell out at least
+ *     the words the command's approval scope holds (ADR-0008, T1), so
+ *     `az group` never covers `az group delete`, and a one-word read takes a
+ *     `*` for its argument (`kubectl get *`). `*` stands for one word, and
+ *     inside a word for any run of characters (`describe-*`). An entry equal
+ *     to a scope also matches that scope, as pre-approved scopes always did.
+ *   - an **MCP tool rule**, `mcp:find-*`: a glob over the tool's own name,
+ *     without the server, case-insensitive.
+ *   - a **scope pattern**, anything starting with `/`, `~`, `http://`,
+ *     `https://`, `mcp__` or a drive letter: matched against an approval's
+ *     scope as ADR-0008 always matched pre-approved entries, `*` matching any
+ *     run of characters.
+ *
+ * A leading `!` excludes instead, and an exclusion wins over every rule. A
+ * command exclusion's words are looked for anywhere among the arguments, in
+ * order, flags included and case ignored, so `!kubectl *secret*` and
+ * `!* --endpoint*` hold wherever the word appears; a lone short flag (`-s`)
+ * also holds inside a bundle (`-As`, `-shost`). `*` as its binary covers
+ * every command.
+ */
+/** The words a command rule is matched against: a lexed segment's binary and arguments. */
+interface CommandWords {
+    binary: string;
+    args: readonly string[];
+    /** How many leading arguments the command's approval scope holds; a rule must cover at least that many. */
+    scopeWords?: number;
+}
+interface RuleWord {
+    matches: (word: string) => boolean;
+    wildcard: boolean;
+}
+interface CommandRule {
+    text: string;
+    binary: string;
+    words: RuleWord[];
+}
+interface PlannerAllowlist {
+    commands: CommandRule[];
+    commandExclusions: CommandRule[];
+    tools: RegExp[];
+    toolExclusions: RegExp[];
+    scopes: RegExp[];
+    scopeExclusions: RegExp[];
+}
+declare function parseAllowlist(entries: readonly string[]): PlannerAllowlist;
+/** The rule that lets this command run unasked, or undefined when none does or an exclusion holds. */
+declare function commandAllowedBy(list: PlannerAllowlist, command: CommandWords): string | undefined;
+/** Whether an MCP tool, by its own name without the server, runs unasked. */
+declare function toolAllowed(list: PlannerAllowlist, tool: string): boolean;
+/** Whether an approval scope — a directory, an origin, a tool's full name — is pre-approved. */
+declare function scopeAllowed(list: PlannerAllowlist, scope: string): boolean;
+/**
+ * Read-only command families that are safe to run unasked: they read, never
+ * write a file or change a resource, and need no argument that runs code.
+ * Absent on purpose: commands that run the repository's own code (test
+ * runners, builds, package scripts, a package manager the repository pins or
+ * extends — on an untrusted repository someone else wrote that code), commands
+ * a repository's own config can point at another endpoint with the user's
+ * credentials (`.npmrc`, `.sentryclirc`, a Terraform or Pulumi backend), and
+ * commands whose usual output is a secret.
+ */
+declare const DEFAULT_PLANNER_ALLOWLIST: readonly string[];
+
 /**
  * The planner's single approval seam. Every capability that reaches beyond the
  * default read-only, in-workspace envelope — a path outside the workspace root,
@@ -17,9 +89,11 @@ import { z } from 'zod/v4';
 /**
  * `runner_tool` is a task runner's own tool request (ADR-0018, A1): it waits
  * for an answer as long as it takes, and never passes through the planner's
- * policy — the runner's mode already decided it needed asking.
+ * policy — the runner's mode already decided it needed asking. `mcp_tool` is
+ * a harness planner reaching for an MCP tool the user configured (ADR-0026),
+ * scoped to that one tool.
  */
-type ApprovalKind = 'external_path' | 'shell_command' | 'url_fetch' | 'runner_tool';
+type ApprovalKind = 'external_path' | 'shell_command' | 'url_fetch' | 'mcp_tool' | 'runner_tool';
 interface ApprovalRequest {
     kind: ApprovalKind;
     /** The concrete thing being asked about: an absolute path, a command line, a URL. */
@@ -41,6 +115,14 @@ interface ApprovalRequest {
     taskId?: string;
     /** "Allow for this task" can be offered: the runner proposed its own session-scoped grant. */
     allowForTask?: boolean;
+    /**
+     * The allowlist rule the command classifier found covering every part of a
+     * `shell_command` that asks (ADR-0026). It settles `scope`, never the
+     * outside directories in `scopes`.
+     */
+    allowedBy?: string;
+    /** For `mcp_tool`: the tool's own name, without its server, which allowlist tool rules match. */
+    tool?: string;
 }
 /**
  * An answer, from whoever gives it — a person on any surface, or later the
@@ -63,6 +145,8 @@ declare function approvalScopes(request: ApprovalRequest): string[];
 declare function isRunnerApproval(request: ApprovalRequest): boolean;
 interface IApproval {
     request(req: ApprovalRequest): Promise<boolean>;
+    /** The standing approvals a command is classified against, when this approval has any (ADR-0026). */
+    allowlist?(): PlannerAllowlist;
 }
 /** Denies everything. The safe default when a surface wires no approval channel. */
 declare const DENY_ALL: IApproval;
@@ -92,6 +176,9 @@ declare const listRunnersInput: z.ZodObject<{}, z.core.$strip>;
 declare const listModelsInput: z.ZodObject<{
     runner: z.ZodString;
 }, z.core.$strip>;
+declare const runCommandInput: z.ZodObject<{
+    command: z.ZodString;
+}, z.core.$strip>;
 declare const loadSkillInput: z.ZodObject<{
     name: z.ZodString;
 }, z.core.$strip>;
@@ -186,6 +273,7 @@ type CheckpointArgs = z.infer<typeof checkpointInput>;
 type ListRunnersArgs = z.infer<typeof listRunnersInput>;
 type ListModelsArgs = z.infer<typeof listModelsInput>;
 type LoadSkillArgs = z.infer<typeof loadSkillInput>;
+type RunCommandArgs = z.infer<typeof runCommandInput>;
 type SubmitPlanArgs = z.infer<typeof submitPlanInput>;
 type EditPlanArgs = z.infer<typeof editPlanInput>;
 type TaskQueryArgs = z.infer<typeof taskQueryInput>;
@@ -220,6 +308,7 @@ interface TaskToolHandler {
 }
 interface PlannerToolHandler {
     loadSkill?: Run<LoadSkillArgs>;
+    runCommand?: Run<RunCommandArgs>;
     listRunners?: Run<ListRunnersArgs>;
     listModels?: Run<ListModelsArgs>;
     submitPlan?: Run<SubmitPlanArgs>;
@@ -400,15 +489,17 @@ type AgentEvent =
     digest: string;
 }
 /**
- * The agent asked to do something its mode does not cover. A planner always
- * auto-denies it (T1) — a planner that can mutate is not a planner — and the
- * adapter answers so the turn does not hang. A task's request stays open
- * until {@link TaskModeAgentAdapter.answerPermission} (ADR-0018, A1).
+ * The agent asked to do something its mode does not cover. Without
+ * `decided` the request stays open until {@link AgentAdapter.answerPermission}:
+ * a task's for a person (ADR-0018, A1), a planner's for the planner's
+ * envelope (ADR-0026). An adapter that cannot hold a planner's request open
+ * denies it itself and says so in `decided`, so the turn does not hang.
  *
  * `input` and `suggestions` are the raw request; `suggestions` are the
  * agent's own session-scoped grants, what "Allow for this task" answers with.
- * `decided` marks a request the task's mode already answered — the adapter
- * replied as the manifest says that mode does — so it is shown, never asked.
+ * `decided` marks a request already answered — by the adapter, as the
+ * manifest says the task's mode does, or as a denial — so it is shown, never asked.
+ * `ask` is what a planner's open request is for, in the envelope's terms.
  */
  | {
     type: 'permission_request';
@@ -419,6 +510,7 @@ type AgentEvent =
     suggestions?: unknown[];
     toolUseId?: string;
     decided?: ApprovalDecision;
+    ask?: PlannerAsk;
 }
 /** The agent withdrew an open request — an interrupt cancels the call it was for. It takes no answer now. */
  | {
@@ -468,6 +560,28 @@ type AgentEvent =
     type: 'error';
     message: string;
 };
+/**
+ * What a planner's permission request is for, read from the runner's own
+ * request by its adapter, so one envelope decides it whichever runner asked
+ * (ADR-0026). `other` is anything the envelope never grants a planner.
+ */
+type PlannerAsk = 
+/** `scope` is the tool's full name as the runner reports it; `tool` its own name, without the server. */
+{
+    kind: 'mcp';
+    scope: string;
+    tool: string;
+    server?: string;
+} | {
+    kind: 'fetch';
+    url: string;
+} | {
+    kind: 'path';
+    path: string;
+    directory: boolean;
+} | {
+    kind: 'other';
+};
 interface AgentStartCommon {
     /** Workspace root. The agent works from here and, in read-only mode, cannot leave it. */
     cwd: string;
@@ -556,6 +670,12 @@ interface AgentAdapter {
      * adapter that cannot inject the server at all, which cannot run tasks.
      */
     mcpAttached?(): Promise<boolean>;
+    /**
+     * Answer an open `permission_request`. False when the id is not open — it
+     * was answered, cancelled, or never asked. Absent on an adapter that leaves
+     * no planner request open.
+     */
+    answerPermission?(id: string, decision: ApprovalDecision): boolean;
 }
 /** What an adapter adds to run a task rather than a planner (ADR-0018). */
 interface TaskModeAgentAdapter extends AgentAdapter {
@@ -586,10 +706,6 @@ interface TaskModeAgentAdapter extends AgentAdapter {
      * mid-turn.
      */
     steer?(id: string, text: string): Promise<boolean>;
-    /**
-     * Answer an open `permission_request`. False when the id is not open — it
-     * was answered, cancelled, or never asked.
-     */
     answerPermission(id: string, decision: ApprovalDecision): boolean;
 }
 type SpawnFn = (command: string, args: string[], options: {
@@ -755,23 +871,35 @@ interface RunnerEntry {
  *
  * Grants are keyed on {@link ApprovalRequest.scope}, never on the concrete
  * subject: approving a read of `/tmp/foo/a.log` grants `/tmp/foo/*`, and
- * approving `az group list` grants `az group`. Without that, a planner doing
- * real research would prompt on every single call and the feature would be
- * unusable.
+ * approving `az group list` grants `az group list`. Without that, a planner
+ * doing real research would prompt on every single call and the feature would
+ * be unusable.
  *
  * `mode` is the policy floor:
  *   ask     consult the human channel; no channel means deny (headless, web)
  *   allow   grant everything the tier system did not already refuse
- *   deny    grant nothing beyond `preApproved`
+ *   deny    grant nothing beyond `preApproved` — the allowlist-only mode
  *
  * Note the ordering: `preApproved` is honored under every mode including
  * `deny`, because it is an explicit operator decision rather than a default.
+ * Its entries are allowlist rules (see `plannerAllowlist.ts`), and both it and
+ * `mode` may be read afresh on every request, so a settings change applies to
+ * the next call.
  */
 type ApprovalMode = 'ask' | 'allow' | 'deny';
+/**
+ * The configured mode. `auto` follows the autonomy level (ADR-0026): Guarded
+ * asks, Full runs the allowlist alone and asks nobody, so a planner in Full
+ * never waits on a person and never acts outside its standing approvals.
+ */
+type ApprovalModeSetting = ApprovalMode | 'auto';
+declare function effectiveApprovalMode(setting: ApprovalModeSetting, autonomous: boolean): ApprovalMode;
+/** A configured mode as written: `allowlist` is the user-facing name of `deny`, and anything unknown is `auto`. */
+declare function parseApprovalModeSetting(raw: string | undefined): ApprovalModeSetting;
 interface ApprovalPolicyOptions {
-    mode?: ApprovalMode;
-    /** Scopes granted up front from config. A trailing `*` matches by prefix. */
-    preApproved?: string[];
+    mode?: ApprovalMode | (() => ApprovalMode);
+    /** Allowlist entries granted up front from config (ADR-0026). */
+    preApproved?: readonly string[] | (() => readonly string[]);
     /** The human channel. Absent means there is nobody to ask. */
     ask?: (req: ApprovalRequest) => Promise<boolean>;
     /** Called whenever a decision is reached, for surfacing in a UI or a log. */
@@ -779,8 +907,9 @@ interface ApprovalPolicyOptions {
 }
 type ApprovalSource = 'pre-approved' | 'remembered' | 'mode' | 'asked' | 'no-channel';
 declare class ApprovalPolicy implements IApproval {
-    private readonly mode;
-    private readonly preApproved;
+    private readonly modeOf;
+    private readonly entriesOf;
+    private parsed;
     private readonly asker?;
     private readonly onDecision?;
     private readonly granted;
@@ -790,6 +919,8 @@ declare class ApprovalPolicy implements IApproval {
     private generation;
     constructor(opts?: ApprovalPolicyOptions);
     request(req: ApprovalRequest): Promise<boolean>;
+    /** The standing approvals, parsed from the entries in force now. */
+    allowlist(): PlannerAllowlist;
     /** Scopes the user has granted this session — for display and for persistence. */
     grantedScopes(): string[];
     /** Drop every session-scoped decision. Called on session reset. */
@@ -961,13 +1092,16 @@ interface IConfig {
     conflictRepairAttempts: number;
     /**
      * What to do when planner research reaches outside its default envelope — an
-     * out-of-workspace path, or a shell command beyond the auto-allowed read-only
-     * set. `ask` prompts the user (and denies where no surface can prompt, such as
-     * headless runs); `allow` and `deny` skip the prompt entirely.
+     * out-of-workspace path, a shell command beyond the auto-allowed read-only
+     * set, an MCP tool. `ask` prompts the user (and denies where no surface can
+     * prompt, such as headless runs); `allow` and `deny` skip the prompt
+     * entirely; `auto` follows {@link autonomousMode} (ADR-0026).
      */
-    approvalMode: ApprovalMode;
-    /** Scopes granted up front, so CI and power users never see a prompt. Trailing `*` matches by prefix. */
+    approvalMode: ApprovalModeSetting;
+    /** Allowlist entries granted up front, beside the defaults (ADR-0026, `plannerAllowlist.ts`). */
     approvalPreApproved: string[];
+    /** Whether the built-in allowlist of read-only command families and MCP tools applies. */
+    approvalDefaults: boolean;
     /** Get the base URL for an OpenAI-compatible provider. */
     getProviderBaseUrl(provider: AiProvider): string;
     /** Get the API key for a provider. */
@@ -1162,4 +1296,4 @@ interface IRunner {
     activeCount: number;
 }
 
-export { type RunnerManifest as $, type AgentAdapter as A, type McpToolReply as B, type CatalogModel as C, DENY_ALL as D, type EditPlanArgs as E, type FetchAllProviderModelsOptions as F, ModelCatalog as G, type ModelShortcut as H, type IApproval as I, ORDEWELL_MCP_PATH as J, ORDEWELL_MCP_SERVER_NAME as K, LineBuffer as L, type McpClientConfig as M, type OrchestratorOption as N, ORCHESTRATOR_SHORTCUTS as O, OrdewellMcpServer as P, type OwnerOnlyFile as Q, PLANNER_TOOLS as R, type PlannerStartOptions as S, type PlannerTokenScope as T, type PlannerToolHandler as U, type ProviderCredentialSource as V, type ProviderModelLists as W, type ProviderModelsResult as X, type QueuedTaskMessage as Y, type RunnerEntry as Z, type RunnerFeatures as _, type AgentAdapterFactory as a, type RunnerMode as a0, type RunnerModelDiscovery as a1, RunnerRegistry as a2, type SpawnFn as a3, type StructuredEvent as a4, type StructuredTurnEnd as a5, type SubmitPlanArgs as a6, TASK_COMPLETE_TOOL as a7, TASK_TOOLS as a8, type TaskCompleteArgs as a9, type TaskModeAgentAdapter as aa, TaskModeUnsupportedError as ab, type TaskOutputArgs as ac, type TaskQueryArgs as ad, type TaskRunnerFlags as ae, type TaskStartOptions as af, type TaskTokenScope as ag, type TaskToolHandler as ah, approvalScopes as ai, collectProviderCredentials as aj, enabledRunners as ak, fetchAllProviderModels as al, isGranted as am, isRunnerApproval as an, knownModelId as ao, mcpClientConfig as ap, ownerOnlyConfigFile as aq, resolveModelShortcut as ar, resolveProvider as as, sharedMcpServer as at, toApprovalDecision as au, toOrchestratorOptions as av, type AgentEvent as b, type AgentProcessDeps as c, type AgentStartOptions as d, type AiProvider as e, type AllProviderModels as f, type ApprovalAnswer as g, type ApprovalDecision as h, type ApprovalKind as i, type ApprovalMode as j, ApprovalPolicy as k, type ApprovalPolicyOptions as l, type ApprovalRequest as m, type ApprovalSource as n, type CheckpointAnswer as o, type CheckpointArgs as p, type DiscoveryCommand as q, type IConfig as r, type IRunner as s, type IRunnerSession as t, type ListModelsArgs as u, type ListRunnersArgs as v, type LoadSkillArgs as w, type McpCredential as x, type McpTool as y, type McpToolContext as z };
+export { type ProviderModelsResult as $, type AgentAdapter as A, type McpCredential as B, type CatalogModel as C, DEFAULT_PLANNER_ALLOWLIST as D, type EditPlanArgs as E, type FetchAllProviderModelsOptions as F, type McpTool as G, type McpToolContext as H, type IApproval as I, type McpToolReply as J, ModelCatalog as K, LineBuffer as L, type McpClientConfig as M, type ModelShortcut as N, ORCHESTRATOR_SHORTCUTS as O, ORDEWELL_MCP_PATH as P, ORDEWELL_MCP_SERVER_NAME as Q, type OrchestratorOption as R, OrdewellMcpServer as S, type OwnerOnlyFile as T, PLANNER_TOOLS as U, type PlannerAllowlist as V, type PlannerStartOptions as W, type PlannerTokenScope as X, type PlannerToolHandler as Y, type ProviderCredentialSource as Z, type ProviderModelLists as _, type AgentAdapterFactory as a, type QueuedTaskMessage as a0, type RunCommandArgs as a1, type RunnerEntry as a2, type RunnerFeatures as a3, type RunnerManifest as a4, type RunnerMode as a5, type RunnerModelDiscovery as a6, RunnerRegistry as a7, type SpawnFn as a8, type StructuredEvent as a9, resolveModelShortcut as aA, resolveProvider as aB, scopeAllowed as aC, sharedMcpServer as aD, toApprovalDecision as aE, toOrchestratorOptions as aF, toolAllowed as aG, type StructuredTurnEnd as aa, type SubmitPlanArgs as ab, TASK_COMPLETE_TOOL as ac, TASK_TOOLS as ad, type TaskCompleteArgs as ae, type TaskModeAgentAdapter as af, TaskModeUnsupportedError as ag, type TaskOutputArgs as ah, type TaskQueryArgs as ai, type TaskRunnerFlags as aj, type TaskStartOptions as ak, type TaskTokenScope as al, type TaskToolHandler as am, approvalScopes as an, collectProviderCredentials as ao, commandAllowedBy as ap, effectiveApprovalMode as aq, enabledRunners as ar, fetchAllProviderModels as as, isGranted as at, isRunnerApproval as au, knownModelId as av, mcpClientConfig as aw, ownerOnlyConfigFile as ax, parseAllowlist as ay, parseApprovalModeSetting as az, type AgentEvent as b, type AgentProcessDeps as c, type AgentStartOptions as d, type AiProvider as e, type AllProviderModels as f, type ApprovalAnswer as g, type ApprovalDecision as h, type ApprovalKind as i, type ApprovalMode as j, type ApprovalModeSetting as k, ApprovalPolicy as l, type ApprovalPolicyOptions as m, type ApprovalRequest as n, type ApprovalSource as o, type CheckpointAnswer as p, type CheckpointArgs as q, type CommandWords as r, DENY_ALL as s, type DiscoveryCommand as t, type IConfig as u, type IRunner as v, type IRunnerSession as w, type ListModelsArgs as x, type ListRunnersArgs as y, type LoadSkillArgs as z };