@idapt/cli 1.9.0 → 1.11.0

package/dist/index.d.cts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { HttpContext } from '@idapt/sdk';
 
 /**
  * v1 contract framework — the SINGLE SOURCE of truth for the public API surface.
@@ -36,7 +37,7 @@ type ResponseKind = "single" | "list" | "created" | "deleted" | "binary";
 /** Wire auth mode — drives the OpenAPI `security` requirement + whether 401 is documented. */
 type V1AuthMode = "standard" | "optional" | "public" | "bearer-only";
 /** HTTP error statuses the v1 surface documents. */
-type V1ErrorStatus = 401 | 402 | 403 | 404 | 409 | 422 | 429 | 500 | 503;
+type V1ErrorStatus = 401 | 402 | 403 | 404 | 409 | 413 | 422 | 429 | 500 | 503;
 /**
  * A bespoke error response. Use instead of a bare {@link V1ErrorStatus} when an
  * op documents an error with op-specific prose / example / headers that the
@@ -91,6 +92,17 @@ interface V1CommandDocFields {
     readonly requestExample?: unknown;
     /** Inline example for the success-response body. */
     readonly responseExample?: unknown;
+    /**
+     * Agent-invocation examples — concrete `{action, args}` calls surfaced in the
+     * command catalog + `help`. Distinct from `requestExample`/`responseExample`
+     * (which document the HTTP bodies for OpenAPI). Helps the model produce
+     * well-formed calls (the Anthropic `input_examples` affordance).
+     */
+    readonly examples?: readonly {
+        readonly title?: string;
+        readonly action: string;
+        readonly args?: Record<string, unknown>;
+    }[];
     /** For `binary` responses — the media types served (+ optional example/description). */
     readonly binary?: {
         readonly contentTypes: readonly string[];
@@ -102,6 +114,31 @@ interface V1CommandDocFields {
     /** Marks the operation `deprecated` in the spec. */
     readonly deprecated?: boolean;
 }
+/**
+ * Resource type a request field resolves against. The v1 route turns a human
+ * reference (resourceId | slug | name | workspace-relative path) into the
+ * canonical internal id before the handler runs. This is the contract-level
+ * encoding of what the dispatcher's old `TOOL_PATH_PARAMETERS` map did — moved
+ * here so resolution is one server-side step shared by chat / CLI / MCP / SDK.
+ */
+type V1ResolveType = "file" | "folder" | "parent-folder" | "computer" | "agent" | "script" | "workspace";
+/** How a single request field is resolved + (optionally) context-defaulted. */
+interface V1FieldResolution {
+    /** Resource type to resolve this field's value(s) against. */
+    readonly type: V1ResolveType;
+    /** The field carries an ARRAY of references (e.g. `reference_image_ids`). */
+    readonly array?: boolean;
+    /**
+     * When the field is omitted, default it from request context instead of
+     * erroring. `"scopedWorkspace"` fills `workspace_id` from
+     * `credential.scopedWorkspaceId` (falling back to the actor's personal
+     * workspace) — the single defaulting rule that makes `workspace_id` optional
+     * on scope verbs for every caller.
+     */
+    readonly autoDefault?: "scopedWorkspace";
+}
+/** Steering-policy: how this resource's playbook reaches the in-chat agent. */
+type V1SteeringPolicy = "eager" | "reactive" | "none";
 interface V1CommandSpec extends V1CommandDocFields {
     /** Resource group, e.g. "drive". */
     readonly resource: string;
@@ -127,10 +164,37 @@ interface V1CommandSpec extends V1CommandDocFields {
     readonly public: boolean;
     /** Exposed as an agent tool (dispatcher / MCP / `idapt`). */
     readonly agentExposed: boolean;
+    /**
+     * Workspace-scope behavior for the IN-APP agent dispatcher only (CLI / MCP
+     * always pass `workspace_id` explicitly and are unaffected):
+     *   - "scope"  → `workspace_id` is an operating SCOPE; the dispatcher auto-pins
+     *                it to the chat's current workspace when the model omits it.
+     *   - "target" → `workspace_id` is a DESTINATION (move / copy / link); never
+     *                auto-filled — the model must name it explicitly.
+     * Omitted → the dispatcher still auto-pins read (GET) verbs whose request
+     * declares `workspace_id`; everything else stays explicit. Cross-workspace
+     * targeting is additionally gated by the `cross_workspace_agent` flag.
+     */
+    readonly workspaceScope?: "scope" | "target";
     /** Long-running → goes through the async-operation layer. */
     readonly async: boolean;
     /** Tier-1 one-line decision hint (≤200 chars). */
     readonly summary: string;
+    /**
+     * Per-field reference resolution + workspace defaulting, keyed by the request
+     * field name (snake_case wire name). The v1 route resolves each listed field
+     * (id | slug | name | path → internal id) using the caller's credential
+     * scope, in ONE place shared by every channel. Replaces the dispatcher's
+     * `TOOL_PATH_PARAMETERS`. Omit for verbs that take no references.
+     */
+    readonly fieldResolution?: Readonly<Record<string, V1FieldResolution>>;
+    /**
+     * How this resource's playbook reaches the in-chat agent (default `reactive`).
+     * Set on EVERY command of a resource to the same value (resource-level policy);
+     * `eager` for destructive / orchestration resources. Drives the builtin
+     * `tool-steering` hook — there is no forced-round-trip gate.
+     */
+    readonly steeringPolicy?: V1SteeringPolicy;
 }
 /**
  * Resource-level playbook (tier-2b instructions) — the cross-cutting "when /
@@ -193,16 +257,26 @@ declare function autoMode(isTty: boolean, requested?: RenderMode): RenderMode;
 /**
  * Transport seam. `execute()` builds a neutral {@link AgentToolsRequest} from a
  * command spec and hands it to a transport. The default {@link createFetchTransport}
- * is a thin bearer-auth fetch wrapper; in the in-chat worker / MCP it is given a
+ * sends HTTP **through `@idapt/sdk`'s low-level `requestRaw()`** (bearer auth, URL
+ * + body building, fetch-error mapping); in the in-chat worker / MCP it is given a
  * transport that injects the minted agent-principal token, and tests inject a
  * mock.
  *
- * This is the single seam where the `@idapt/sdk` low-level `request()` will be
- * plugged in once the SDK exports it — so cli reuses the SDK's HTTP
- * behaviour instead of duplicating it long-term.
+ * This is the single seam where the cli, MCP, and in-app dispatcher (which all
+ * consume this transport) share ONE HTTP layer with the SDK instead of
+ * duplicating fetch — the JS twin of the Go daemon routing through one client.
+ *
+ * The {@link AgentToolsRequest}/{@link AgentToolsResponse} interface is kept
+ * byte-stable so `execute.ts` / MCP / the dispatcher are unaffected: the
+ * transport still NEVER throws on an HTTP status — every status (incl. 4xx/5xx)
+ * comes back as `{ status, json | text | blob }`. The SDK's `requestRaw()` throws
+ * a typed `IdaptError` on non-2xx, so we catch it and rebuild that flat shape
+ * from the error's preserved `.status` + `.body`. Only a transport-level failure
+ * (network error / abort) propagates as a thrown error, exactly as before.
  */
+
 interface AgentToolsRequest {
-    readonly method: "GET" | "POST" | "PATCH" | "DELETE";
+    readonly method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
     /** Absolute-from-origin path, e.g. "/api/v1/drive/files/file_abc". */
     readonly path: string;
     readonly query?: Record<string, string | number | boolean | undefined>;
@@ -225,6 +299,15 @@ interface AgentToolsResponse {
 }
 interface AgentToolsTransport {
     request(req: AgentToolsRequest): Promise<AgentToolsResponse>;
+    /**
+     * The underlying SDK {@link HttpContext} this transport sends through, when it
+     * is the default fetch transport. The spec executor delegates request
+     * assembly, the HTTP call, envelope unwrap, and operation polling to the SDK's
+     * `executeCommand` over THIS context — so the CLI and SDK share ONE executor
+     * with zero duplicated logic. Absent only on bespoke (non-fetch) transports,
+     * in which case the executor reports the command is not runnable.
+     */
+    readonly ctx?: HttpContext;
 }
 interface FetchTransportOptions {
     /** Origin, e.g. "https://idapt.app" or "http://localhost:3000". */
@@ -241,17 +324,21 @@ interface FetchTransportOptions {
      */
     readonly userAgent?: string;
 }
-/** Default bearer-auth fetch transport. */
+/** Default bearer-auth transport — sends through the SDK's `requestRaw()`. */
 declare function createFetchTransport(opts: FetchTransportOptions): AgentToolsTransport;
 
 /**
  * Execute an `idapt <resource> <verb> …` command against the v1 API.
  *
- * Pure translation: resolve the command spec, bind path params, validate the
- * remaining args against the contract's request schema, build the REST request
- * per the spec's `argLocation`, call the transport, unwrap the envelope by
- * `responseKind`, and render per the chosen mode. No per-verb code — the spec
- * (from `shared/api/v1/contracts`) drives everything.
+ * The CLI is the **spec/positional/validation/render adapter** around the SINGLE
+ * spec executor that lives in `@idapt/sdk` (`executeCommand`): it resolves the
+ * command spec, binds path params from positionals + named args, validates the
+ * remaining args against the contract's request schema, then DELEGATES request
+ * assembly, the HTTP call, envelope unwrap, and async-operation polling to the
+ * SDK over the transport's shared {@link HttpContext}. The CLI layers on what is
+ * its own — positional binding, pre-flight validation with repair hints, binary
+ * text-detection, render mode, and the soft `ExecuteResult` (it never throws on
+ * an HTTP status). One executor, zero duplicated transport logic.
  */
 
 interface ExecuteOptions {

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { HttpContext } from '@idapt/sdk';
 
 /**
  * v1 contract framework — the SINGLE SOURCE of truth for the public API surface.
@@ -36,7 +37,7 @@ type ResponseKind = "single" | "list" | "created" | "deleted" | "binary";
 /** Wire auth mode — drives the OpenAPI `security` requirement + whether 401 is documented. */
 type V1AuthMode = "standard" | "optional" | "public" | "bearer-only";
 /** HTTP error statuses the v1 surface documents. */
-type V1ErrorStatus = 401 | 402 | 403 | 404 | 409 | 422 | 429 | 500 | 503;
+type V1ErrorStatus = 401 | 402 | 403 | 404 | 409 | 413 | 422 | 429 | 500 | 503;
 /**
  * A bespoke error response. Use instead of a bare {@link V1ErrorStatus} when an
  * op documents an error with op-specific prose / example / headers that the
@@ -91,6 +92,17 @@ interface V1CommandDocFields {
     readonly requestExample?: unknown;
     /** Inline example for the success-response body. */
     readonly responseExample?: unknown;
+    /**
+     * Agent-invocation examples — concrete `{action, args}` calls surfaced in the
+     * command catalog + `help`. Distinct from `requestExample`/`responseExample`
+     * (which document the HTTP bodies for OpenAPI). Helps the model produce
+     * well-formed calls (the Anthropic `input_examples` affordance).
+     */
+    readonly examples?: readonly {
+        readonly title?: string;
+        readonly action: string;
+        readonly args?: Record<string, unknown>;
+    }[];
     /** For `binary` responses — the media types served (+ optional example/description). */
     readonly binary?: {
         readonly contentTypes: readonly string[];
@@ -102,6 +114,31 @@ interface V1CommandDocFields {
     /** Marks the operation `deprecated` in the spec. */
     readonly deprecated?: boolean;
 }
+/**
+ * Resource type a request field resolves against. The v1 route turns a human
+ * reference (resourceId | slug | name | workspace-relative path) into the
+ * canonical internal id before the handler runs. This is the contract-level
+ * encoding of what the dispatcher's old `TOOL_PATH_PARAMETERS` map did — moved
+ * here so resolution is one server-side step shared by chat / CLI / MCP / SDK.
+ */
+type V1ResolveType = "file" | "folder" | "parent-folder" | "computer" | "agent" | "script" | "workspace";
+/** How a single request field is resolved + (optionally) context-defaulted. */
+interface V1FieldResolution {
+    /** Resource type to resolve this field's value(s) against. */
+    readonly type: V1ResolveType;
+    /** The field carries an ARRAY of references (e.g. `reference_image_ids`). */
+    readonly array?: boolean;
+    /**
+     * When the field is omitted, default it from request context instead of
+     * erroring. `"scopedWorkspace"` fills `workspace_id` from
+     * `credential.scopedWorkspaceId` (falling back to the actor's personal
+     * workspace) — the single defaulting rule that makes `workspace_id` optional
+     * on scope verbs for every caller.
+     */
+    readonly autoDefault?: "scopedWorkspace";
+}
+/** Steering-policy: how this resource's playbook reaches the in-chat agent. */
+type V1SteeringPolicy = "eager" | "reactive" | "none";
 interface V1CommandSpec extends V1CommandDocFields {
     /** Resource group, e.g. "drive". */
     readonly resource: string;
@@ -127,10 +164,37 @@ interface V1CommandSpec extends V1CommandDocFields {
     readonly public: boolean;
     /** Exposed as an agent tool (dispatcher / MCP / `idapt`). */
     readonly agentExposed: boolean;
+    /**
+     * Workspace-scope behavior for the IN-APP agent dispatcher only (CLI / MCP
+     * always pass `workspace_id` explicitly and are unaffected):
+     *   - "scope"  → `workspace_id` is an operating SCOPE; the dispatcher auto-pins
+     *                it to the chat's current workspace when the model omits it.
+     *   - "target" → `workspace_id` is a DESTINATION (move / copy / link); never
+     *                auto-filled — the model must name it explicitly.
+     * Omitted → the dispatcher still auto-pins read (GET) verbs whose request
+     * declares `workspace_id`; everything else stays explicit. Cross-workspace
+     * targeting is additionally gated by the `cross_workspace_agent` flag.
+     */
+    readonly workspaceScope?: "scope" | "target";
     /** Long-running → goes through the async-operation layer. */
     readonly async: boolean;
     /** Tier-1 one-line decision hint (≤200 chars). */
     readonly summary: string;
+    /**
+     * Per-field reference resolution + workspace defaulting, keyed by the request
+     * field name (snake_case wire name). The v1 route resolves each listed field
+     * (id | slug | name | path → internal id) using the caller's credential
+     * scope, in ONE place shared by every channel. Replaces the dispatcher's
+     * `TOOL_PATH_PARAMETERS`. Omit for verbs that take no references.
+     */
+    readonly fieldResolution?: Readonly<Record<string, V1FieldResolution>>;
+    /**
+     * How this resource's playbook reaches the in-chat agent (default `reactive`).
+     * Set on EVERY command of a resource to the same value (resource-level policy);
+     * `eager` for destructive / orchestration resources. Drives the builtin
+     * `tool-steering` hook — there is no forced-round-trip gate.
+     */
+    readonly steeringPolicy?: V1SteeringPolicy;
 }
 /**
  * Resource-level playbook (tier-2b instructions) — the cross-cutting "when /
@@ -193,16 +257,26 @@ declare function autoMode(isTty: boolean, requested?: RenderMode): RenderMode;
 /**
  * Transport seam. `execute()` builds a neutral {@link AgentToolsRequest} from a
  * command spec and hands it to a transport. The default {@link createFetchTransport}
- * is a thin bearer-auth fetch wrapper; in the in-chat worker / MCP it is given a
+ * sends HTTP **through `@idapt/sdk`'s low-level `requestRaw()`** (bearer auth, URL
+ * + body building, fetch-error mapping); in the in-chat worker / MCP it is given a
  * transport that injects the minted agent-principal token, and tests inject a
  * mock.
  *
- * This is the single seam where the `@idapt/sdk` low-level `request()` will be
- * plugged in once the SDK exports it — so cli reuses the SDK's HTTP
- * behaviour instead of duplicating it long-term.
+ * This is the single seam where the cli, MCP, and in-app dispatcher (which all
+ * consume this transport) share ONE HTTP layer with the SDK instead of
+ * duplicating fetch — the JS twin of the Go daemon routing through one client.
+ *
+ * The {@link AgentToolsRequest}/{@link AgentToolsResponse} interface is kept
+ * byte-stable so `execute.ts` / MCP / the dispatcher are unaffected: the
+ * transport still NEVER throws on an HTTP status — every status (incl. 4xx/5xx)
+ * comes back as `{ status, json | text | blob }`. The SDK's `requestRaw()` throws
+ * a typed `IdaptError` on non-2xx, so we catch it and rebuild that flat shape
+ * from the error's preserved `.status` + `.body`. Only a transport-level failure
+ * (network error / abort) propagates as a thrown error, exactly as before.
  */
+
 interface AgentToolsRequest {
-    readonly method: "GET" | "POST" | "PATCH" | "DELETE";
+    readonly method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
     /** Absolute-from-origin path, e.g. "/api/v1/drive/files/file_abc". */
     readonly path: string;
     readonly query?: Record<string, string | number | boolean | undefined>;
@@ -225,6 +299,15 @@ interface AgentToolsResponse {
 }
 interface AgentToolsTransport {
     request(req: AgentToolsRequest): Promise<AgentToolsResponse>;
+    /**
+     * The underlying SDK {@link HttpContext} this transport sends through, when it
+     * is the default fetch transport. The spec executor delegates request
+     * assembly, the HTTP call, envelope unwrap, and operation polling to the SDK's
+     * `executeCommand` over THIS context — so the CLI and SDK share ONE executor
+     * with zero duplicated logic. Absent only on bespoke (non-fetch) transports,
+     * in which case the executor reports the command is not runnable.
+     */
+    readonly ctx?: HttpContext;
 }
 interface FetchTransportOptions {
     /** Origin, e.g. "https://idapt.app" or "http://localhost:3000". */
@@ -241,17 +324,21 @@ interface FetchTransportOptions {
      */
     readonly userAgent?: string;
 }
-/** Default bearer-auth fetch transport. */
+/** Default bearer-auth transport — sends through the SDK's `requestRaw()`. */
 declare function createFetchTransport(opts: FetchTransportOptions): AgentToolsTransport;
 
 /**
  * Execute an `idapt <resource> <verb> …` command against the v1 API.
  *
- * Pure translation: resolve the command spec, bind path params, validate the
- * remaining args against the contract's request schema, build the REST request
- * per the spec's `argLocation`, call the transport, unwrap the envelope by
- * `responseKind`, and render per the chosen mode. No per-verb code — the spec
- * (from `shared/api/v1/contracts`) drives everything.
+ * The CLI is the **spec/positional/validation/render adapter** around the SINGLE
+ * spec executor that lives in `@idapt/sdk` (`executeCommand`): it resolves the
+ * command spec, binds path params from positionals + named args, validates the
+ * remaining args against the contract's request schema, then DELEGATES request
+ * assembly, the HTTP call, envelope unwrap, and async-operation polling to the
+ * SDK over the transport's shared {@link HttpContext}. The CLI layers on what is
+ * its own — positional binding, pre-flight validation with repair hints, binary
+ * text-detection, render mode, and the soft `ExecuteResult` (it never throws on
+ * an HTTP status). One executor, zero duplicated transport logic.
  */
 
 interface ExecuteOptions {

package/dist/index.js

@@ -1,3 +1,3 @@
-export { VERB_OVERRIDES, autoMode, commandsForResource, createFetchTransport, execute, executeCommand, findCommand, getResourcePlaybook, listCommands, listResources, mapArgsToV1, parseInvocation, reconcileToV1, render, renderHelp, renderInstructions, resolveCommand, toSnakeKey } from './chunk-TYSHO65D.js';
+export { VERB_OVERRIDES, autoMode, commandsForResource, createFetchTransport, execute, executeCommand, findCommand, getResourcePlaybook, listCommands, listResources, mapArgsToV1, parseInvocation, reconcileToV1, render, renderHelp, renderInstructions, resolveCommand, toSnakeKey } from './chunk-3CWHRMLZ.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idapt/cli",
-  "version": "1.9.0",
+  "version": "1.11.0",
   "description": "The idapt CLI — the `idapt <resource> <verb>` grammar, command→REST translation, help/instructions, output formatting, SOTA auth (OAuth 2.1 + PKCE / device-code / API-key) and self-update, over the public v1 API. One implementation shared by the in-chat dispatcher, MCP, and the `idapt` CLI binary.",
   "license": "Apache-2.0",
   "homepage": "https://idapt.app/cli",
@@ -31,6 +31,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
+    "@idapt/sdk": "*",
     "zod": "^4.1.12"
   },
   "devDependencies": {