@arbidocs/client 0.3.167 → 0.3.169

package/dist/index.d.cts

@@ -427,10 +427,11 @@ interface paths {
         head?: never;
         /**
          * Patch Session
-         * @description Expire (ttl=0) or reset the remaining TTL of one of the caller's own sessions.
+         * @description Expire (ttl=0) or shorten the remaining TTL of one of the caller's own sessions.
          *
          *     Agents (as with /logout) may only touch their own session; principals may target
          *     any session in their session set, including ones other than the one they're on.
+         *     Cannot increase a session's TTL — see patch_session_ttl's docstring for why.
          */
         patch: operations['patch_session'];
         trace?: never;
@@ -2345,6 +2346,53 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    '/v1/agents/authorize-limits': {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Get Authorize Limits */
+        get: operations['get_authorize_limits'];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    '/v1/agents/{agent_ext_id}/authorize': {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Authorize Agent
+         * @description Mint a fresh, TTL'd session for the caller's own agent.
+         *
+         *     Standalone version of the session-mint step ``useRunTaskWithAuth`` performs
+         *     inline for a task run (``POST /v1/tasks/{id}/run``) — same primitive
+         *     (:func:`mint_agent_session`), just triggerable on its own instead of bundled
+         *     into running something. Returns the session's public key so the caller's
+         *     client can immediately deposit a temporary workspace key onto it via the
+         *     ordinary ``POST /v1/workspace/users`` (``session_pubkey_b64`` branch) —
+         *     mirroring the task flow's second step exactly. The session's remaining
+         *     time can be checked or ended early afterward via the generic session
+         *     endpoints, not extended (see the module docstring above).
+         */
+        post: operations['authorize_agent'];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     '/v1/agents/{agent_ext_id}': {
         parameters: {
             query?: never;
@@ -3689,6 +3737,12 @@ interface components {
              * @default false
              */
             WORKSPACE_TOOLS_ENABLED: boolean;
+            /**
+             * Remote Control Enabled
+             * @description Enable the control_ui tool so the agent can drive the user's frontend with a guided cursor (click/type on their screen), gated by the user's consent. Pushes a remote_control WebSocket message to the user's session. Off by default.
+             * @default false
+             */
+            REMOTE_CONTROL_ENABLED: boolean;
             /**
              * Enabled Skills
              * @description Allowlist of skill slugs this config may invoke via run_skill/list_skills. None = no restriction (every skill the caller can see — back-compat default). A list (including []) restricts to exactly those slugs. Set a list on an agent's config to scope which skills that agent can use.
@@ -3944,6 +3998,12 @@ interface components {
              * @default false
              */
             WORKSPACE_TOOLS_ENABLED: boolean;
+            /**
+             * Remote Control Enabled
+             * @description Enable the control_ui tool so the agent can drive the user's frontend with a guided cursor (click/type on their screen), gated by the user's consent. Pushes a remote_control WebSocket message to the user's session. Off by default.
+             * @default false
+             */
+            REMOTE_CONTROL_ENABLED: boolean;
             /**
              * Enabled Skills
              * @description Allowlist of skill slugs this config may invoke via run_skill/list_skills. None = no restriction (every skill the caller can see — back-compat default). A list (including []) restricts to exactly those slugs. Set a list on an agent's config to scope which skills that agent can use.
@@ -4015,6 +4075,7 @@ interface components {
              *       "SKILLS_ENABLED": false,
              *       "SKILL_CREATION": false,
              *       "WORKSPACE_TOOLS_ENABLED": false,
+             *       "REMOTE_CONTROL_ENABLED": false,
              *       "MEMORY_CREATION": false,
              *       "GOALS_ENABLED": false,
              *       "GOAL_MAX_OUTER_LOOPS": 6,
@@ -4653,6 +4714,46 @@ interface components {
             /** Reason */
             reason?: string | null;
         };
+        /**
+         * AuthorizeAgentRequest
+         * @description Body for POST /agents/{agent_ext_id}/authorize.
+         */
+        AuthorizeAgentRequest: {
+            /** Workspace Ext Id */
+            workspace_ext_id: string;
+            /**
+             * Ttl Seconds
+             * @description Omit for the deployment default (see GET /agents/authorize-limits).
+             */
+            ttl_seconds?: number | null;
+        };
+        /**
+         * AuthorizeAgentResponse
+         * @description What the caller's client needs to deposit a temporary workspace key onto
+         *     the freshly-minted session — the same shape a task run's
+         *     ``pending_auth_session_pubkey`` / ``pending_auth_agent_email`` fields carry.
+         */
+        AuthorizeAgentResponse: {
+            /** Session Pubkey B64 */
+            session_pubkey_b64: string;
+            /** Agent Email */
+            agent_email: string;
+            /** Ttl */
+            ttl: number;
+        };
+        /**
+         * AuthorizeLimitsResponse
+         * @description Bounds for ``authorize``'s ``ttl_seconds`` — lets a client show/enforce
+         *     the real default and max instead of guessing or discovering them via a 422.
+         *     Deployment-tunable (``AGENT_AUTHORIZE_DEFAULT_TTL_SECONDS`` /
+         *     ``AGENT_AUTHORIZE_MAX_TTL_SECONDS`` env vars), not hardcoded to 4h.
+         */
+        AuthorizeLimitsResponse: {
+            /** Default Ttl Seconds */
+            default_ttl_seconds: number;
+            /** Max Ttl Seconds */
+            max_ttl_seconds: number;
+        };
         /**
          * BatchCompleteMessage
          * @description Notification that a batch operation (upload or doctag generation) completed.
@@ -8799,6 +8900,55 @@ interface components {
             /** Lead Minutes */
             lead_minutes?: number | null;
         };
+        /**
+         * RemoteControlMessage
+         * @description Ask the user's frontend to run a guided-cursor UI action (remote control).
+         *
+         *     The model emits this via the ``control_ui`` tool to demonstrate or perform
+         *     an action on the user's screen. The frontend gates it behind the user's
+         *     consent, then either replays a registered ``sequence_id`` or the explicit
+         *     ``steps``. Exactly one of ``sequence_id`` / ``steps`` is set.
+         */
+        RemoteControlMessage: {
+            /**
+             * Type
+             * @default remote_control
+             * @constant
+             */
+            type: 'remote_control';
+            /** Agent Name */
+            agent_name: string;
+            /** Agent Ext Id */
+            agent_ext_id?: string | null;
+            /** Sequence Id */
+            sequence_id?: string | null;
+            /** Steps */
+            steps?: components['schemas']['RemoteControlStep'][] | null;
+        };
+        /**
+         * RemoteControlStep
+         * @description One guided-cursor step the frontend action runner replays.
+         *
+         *     Field names are the ones the frontend's guided-step runner consumes
+         *     verbatim, so ``pauseMs``/``waitMs`` stay camelCase even though the envelope
+         *     around them is snake_case. ``target`` is a ``[data-testid=…]`` selector and
+         *     is required; ``do`` defaults to a click; ``value`` is the text for a
+         *     ``type`` step.
+         */
+        RemoteControlStep: {
+            /** Target */
+            target: string;
+            /** Do */
+            do?: ('click' | 'type') | null;
+            /** Value */
+            value?: string | null;
+            /** Note */
+            note?: string | null;
+            /** Pausems */
+            pauseMs?: number | null;
+            /** Waitms */
+            waitMs?: number | null;
+        };
         /**
          * RemoveWorkspaceUserItem
          * @description A user or agent to remove from a workspace.
@@ -10019,7 +10169,7 @@ interface components {
         SessionTTLPatchRequest: {
             /**
              * Ttl
-             * @description New remaining TTL in seconds. 0 expires the session immediately; any other value resets its remaining time (capped at the server's max session TTL).
+             * @description New remaining TTL in seconds. 0 expires the session immediately; any other value must be LESS than the session's current remaining TTL — sessions can be ended early or shortened, never extended.
              */
             ttl: number;
         };
@@ -11677,6 +11827,7 @@ interface components {
             response_complete?: components['schemas']['ResponseCompleteMessage'] | null;
             conversation_title_updated?: components['schemas']['ConversationTitleUpdatedMessage'] | null;
             skills_updated?: components['schemas']['SkillsUpdatedMessage'] | null;
+            remote_control?: components['schemas']['RemoteControlMessage'] | null;
             notification?: components['schemas']['NotificationResponse'] | null;
             auth?: components['schemas']['AuthMessage'] | null;
             send_message?: components['schemas']['SendMessageRequest'] | null;
@@ -15271,6 +15422,62 @@ interface operations {
             };
         };
     };
+    get_authorize_limits: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    'application/json': components['schemas']['AuthorizeLimitsResponse'];
+                };
+            };
+        };
+    };
+    authorize_agent: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description Agent external id (agt-XXXXXXXX) */
+                agent_ext_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                'application/json': components['schemas']['AuthorizeAgentRequest'];
+            };
+        };
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    'application/json': components['schemas']['AuthorizeAgentResponse'];
+                };
+            };
+            /** @description Validation Error */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    'application/json': components['schemas']['HTTPValidationError'];
+                };
+            };
+        };
+    };
     update_agent: {
         parameters: {
             query?: never;

package/dist/index.d.ts

@@ -427,10 +427,11 @@ interface paths {
         head?: never;
         /**
          * Patch Session
-         * @description Expire (ttl=0) or reset the remaining TTL of one of the caller's own sessions.
+         * @description Expire (ttl=0) or shorten the remaining TTL of one of the caller's own sessions.
          *
          *     Agents (as with /logout) may only touch their own session; principals may target
          *     any session in their session set, including ones other than the one they're on.
+         *     Cannot increase a session's TTL — see patch_session_ttl's docstring for why.
          */
         patch: operations['patch_session'];
         trace?: never;
@@ -2345,6 +2346,53 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    '/v1/agents/authorize-limits': {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Get Authorize Limits */
+        get: operations['get_authorize_limits'];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    '/v1/agents/{agent_ext_id}/authorize': {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Authorize Agent
+         * @description Mint a fresh, TTL'd session for the caller's own agent.
+         *
+         *     Standalone version of the session-mint step ``useRunTaskWithAuth`` performs
+         *     inline for a task run (``POST /v1/tasks/{id}/run``) — same primitive
+         *     (:func:`mint_agent_session`), just triggerable on its own instead of bundled
+         *     into running something. Returns the session's public key so the caller's
+         *     client can immediately deposit a temporary workspace key onto it via the
+         *     ordinary ``POST /v1/workspace/users`` (``session_pubkey_b64`` branch) —
+         *     mirroring the task flow's second step exactly. The session's remaining
+         *     time can be checked or ended early afterward via the generic session
+         *     endpoints, not extended (see the module docstring above).
+         */
+        post: operations['authorize_agent'];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     '/v1/agents/{agent_ext_id}': {
         parameters: {
             query?: never;
@@ -3689,6 +3737,12 @@ interface components {
              * @default false
              */
             WORKSPACE_TOOLS_ENABLED: boolean;
+            /**
+             * Remote Control Enabled
+             * @description Enable the control_ui tool so the agent can drive the user's frontend with a guided cursor (click/type on their screen), gated by the user's consent. Pushes a remote_control WebSocket message to the user's session. Off by default.
+             * @default false
+             */
+            REMOTE_CONTROL_ENABLED: boolean;
             /**
              * Enabled Skills
              * @description Allowlist of skill slugs this config may invoke via run_skill/list_skills. None = no restriction (every skill the caller can see — back-compat default). A list (including []) restricts to exactly those slugs. Set a list on an agent's config to scope which skills that agent can use.
@@ -3944,6 +3998,12 @@ interface components {
              * @default false
              */
             WORKSPACE_TOOLS_ENABLED: boolean;
+            /**
+             * Remote Control Enabled
+             * @description Enable the control_ui tool so the agent can drive the user's frontend with a guided cursor (click/type on their screen), gated by the user's consent. Pushes a remote_control WebSocket message to the user's session. Off by default.
+             * @default false
+             */
+            REMOTE_CONTROL_ENABLED: boolean;
             /**
              * Enabled Skills
              * @description Allowlist of skill slugs this config may invoke via run_skill/list_skills. None = no restriction (every skill the caller can see — back-compat default). A list (including []) restricts to exactly those slugs. Set a list on an agent's config to scope which skills that agent can use.
@@ -4015,6 +4075,7 @@ interface components {
              *       "SKILLS_ENABLED": false,
              *       "SKILL_CREATION": false,
              *       "WORKSPACE_TOOLS_ENABLED": false,
+             *       "REMOTE_CONTROL_ENABLED": false,
              *       "MEMORY_CREATION": false,
              *       "GOALS_ENABLED": false,
              *       "GOAL_MAX_OUTER_LOOPS": 6,
@@ -4653,6 +4714,46 @@ interface components {
             /** Reason */
             reason?: string | null;
         };
+        /**
+         * AuthorizeAgentRequest
+         * @description Body for POST /agents/{agent_ext_id}/authorize.
+         */
+        AuthorizeAgentRequest: {
+            /** Workspace Ext Id */
+            workspace_ext_id: string;
+            /**
+             * Ttl Seconds
+             * @description Omit for the deployment default (see GET /agents/authorize-limits).
+             */
+            ttl_seconds?: number | null;
+        };
+        /**
+         * AuthorizeAgentResponse
+         * @description What the caller's client needs to deposit a temporary workspace key onto
+         *     the freshly-minted session — the same shape a task run's
+         *     ``pending_auth_session_pubkey`` / ``pending_auth_agent_email`` fields carry.
+         */
+        AuthorizeAgentResponse: {
+            /** Session Pubkey B64 */
+            session_pubkey_b64: string;
+            /** Agent Email */
+            agent_email: string;
+            /** Ttl */
+            ttl: number;
+        };
+        /**
+         * AuthorizeLimitsResponse
+         * @description Bounds for ``authorize``'s ``ttl_seconds`` — lets a client show/enforce
+         *     the real default and max instead of guessing or discovering them via a 422.
+         *     Deployment-tunable (``AGENT_AUTHORIZE_DEFAULT_TTL_SECONDS`` /
+         *     ``AGENT_AUTHORIZE_MAX_TTL_SECONDS`` env vars), not hardcoded to 4h.
+         */
+        AuthorizeLimitsResponse: {
+            /** Default Ttl Seconds */
+            default_ttl_seconds: number;
+            /** Max Ttl Seconds */
+            max_ttl_seconds: number;
+        };
         /**
          * BatchCompleteMessage
          * @description Notification that a batch operation (upload or doctag generation) completed.
@@ -8799,6 +8900,55 @@ interface components {
             /** Lead Minutes */
             lead_minutes?: number | null;
         };
+        /**
+         * RemoteControlMessage
+         * @description Ask the user's frontend to run a guided-cursor UI action (remote control).
+         *
+         *     The model emits this via the ``control_ui`` tool to demonstrate or perform
+         *     an action on the user's screen. The frontend gates it behind the user's
+         *     consent, then either replays a registered ``sequence_id`` or the explicit
+         *     ``steps``. Exactly one of ``sequence_id`` / ``steps`` is set.
+         */
+        RemoteControlMessage: {
+            /**
+             * Type
+             * @default remote_control
+             * @constant
+             */
+            type: 'remote_control';
+            /** Agent Name */
+            agent_name: string;
+            /** Agent Ext Id */
+            agent_ext_id?: string | null;
+            /** Sequence Id */
+            sequence_id?: string | null;
+            /** Steps */
+            steps?: components['schemas']['RemoteControlStep'][] | null;
+        };
+        /**
+         * RemoteControlStep
+         * @description One guided-cursor step the frontend action runner replays.
+         *
+         *     Field names are the ones the frontend's guided-step runner consumes
+         *     verbatim, so ``pauseMs``/``waitMs`` stay camelCase even though the envelope
+         *     around them is snake_case. ``target`` is a ``[data-testid=…]`` selector and
+         *     is required; ``do`` defaults to a click; ``value`` is the text for a
+         *     ``type`` step.
+         */
+        RemoteControlStep: {
+            /** Target */
+            target: string;
+            /** Do */
+            do?: ('click' | 'type') | null;
+            /** Value */
+            value?: string | null;
+            /** Note */
+            note?: string | null;
+            /** Pausems */
+            pauseMs?: number | null;
+            /** Waitms */
+            waitMs?: number | null;
+        };
         /**
          * RemoveWorkspaceUserItem
          * @description A user or agent to remove from a workspace.
@@ -10019,7 +10169,7 @@ interface components {
         SessionTTLPatchRequest: {
             /**
              * Ttl
-             * @description New remaining TTL in seconds. 0 expires the session immediately; any other value resets its remaining time (capped at the server's max session TTL).
+             * @description New remaining TTL in seconds. 0 expires the session immediately; any other value must be LESS than the session's current remaining TTL — sessions can be ended early or shortened, never extended.
              */
             ttl: number;
         };
@@ -11677,6 +11827,7 @@ interface components {
             response_complete?: components['schemas']['ResponseCompleteMessage'] | null;
             conversation_title_updated?: components['schemas']['ConversationTitleUpdatedMessage'] | null;
             skills_updated?: components['schemas']['SkillsUpdatedMessage'] | null;
+            remote_control?: components['schemas']['RemoteControlMessage'] | null;
             notification?: components['schemas']['NotificationResponse'] | null;
             auth?: components['schemas']['AuthMessage'] | null;
             send_message?: components['schemas']['SendMessageRequest'] | null;
@@ -15271,6 +15422,62 @@ interface operations {
             };
         };
     };
+    get_authorize_limits: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    'application/json': components['schemas']['AuthorizeLimitsResponse'];
+                };
+            };
+        };
+    };
+    authorize_agent: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description Agent external id (agt-XXXXXXXX) */
+                agent_ext_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                'application/json': components['schemas']['AuthorizeAgentRequest'];
+            };
+        };
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    'application/json': components['schemas']['AuthorizeAgentResponse'];
+                };
+            };
+            /** @description Validation Error */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    'application/json': components['schemas']['HTTPValidationError'];
+                };
+            };
+        };
+    };
     update_agent: {
         parameters: {
             query?: never;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arbidocs/client",
-  "version": "0.3.167",
+  "version": "0.3.169",
   "description": "TypeScript SDK for the ARBI API — zero-knowledge auth, E2E encryption, and type-safe REST client",
   "type": "module",
   "main": "dist/index.cjs",