@idapt/cli 1.10.0 → 1.12.0

package/dist/index.d.cts

@@ -37,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
@@ -114,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;
@@ -139,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 /
@@ -306,6 +358,14 @@ interface ExecuteOptions {
     readonly maxPollAttempts?: number;
     /** Injectable delay (tests pass a no-op); defaults to real setTimeout. */
     readonly sleep?: (ms: number) => Promise<void>;
+    /**
+     * CLI ambient workspace (resourceId | UUID) from `idapt workspace use`.
+     * Injected as `workspace_id` ONLY on the CLI-string path ({@link execute}),
+     * only for verbs whose request declares `workspace_id`, and only when the
+     * call didn't already name a workspace. The programmatic
+     * {@link executeCommand} seam (in-chat dispatcher / MCP) never sets it.
+     */
+    readonly defaultWorkspaceRef?: string;
 }
 interface ExecuteResult {
     readonly ok: boolean;

package/dist/index.d.ts

@@ -37,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
@@ -114,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;
@@ -139,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 /
@@ -306,6 +358,14 @@ interface ExecuteOptions {
     readonly maxPollAttempts?: number;
     /** Injectable delay (tests pass a no-op); defaults to real setTimeout. */
     readonly sleep?: (ms: number) => Promise<void>;
+    /**
+     * CLI ambient workspace (resourceId | UUID) from `idapt workspace use`.
+     * Injected as `workspace_id` ONLY on the CLI-string path ({@link execute}),
+     * only for verbs whose request declares `workspace_id`, and only when the
+     * call didn't already name a workspace. The programmatic
+     * {@link executeCommand} seam (in-chat dispatcher / MCP) never sets it.
+     */
+    readonly defaultWorkspaceRef?: string;
 }
 interface ExecuteResult {
     readonly ok: boolean;

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-CX7FTE47.js';
+export { VERB_OVERRIDES, autoMode, commandsForResource, createFetchTransport, execute, executeCommand, findCommand, getResourcePlaybook, listCommands, listResources, mapArgsToV1, parseInvocation, reconcileToV1, render, renderHelp, renderInstructions, resolveCommand, toSnakeKey } from './chunk-GISKSK4V.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idapt/cli",
-  "version": "1.10.0",
+  "version": "1.12.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",