@deepraxis/sdk 0.1.1-dev.d775f1e → 0.1.1-dev.d8d3f52

package/README.md

@@ -4,7 +4,7 @@
 
 **Models, agents, sandboxes, search, data and automation, typed end to end.**
 
-The official TypeScript SDK for [知行云 Praxis](https://deepraxis.com), the cloud where AI agents are built, run and hosted.
+The official TypeScript SDK for [Praxis](https://deepraxis.com), the cloud where AI agents are built, run and hosted.
 
 [![npm](https://img.shields.io/npm/v/@deepraxis/sdk?label=npm&color=2e8555)](https://www.npmjs.com/package/@deepraxis/sdk)
 [![Bundle size](https://img.shields.io/bundlephobia/minzip/@deepraxis/sdk?color=2e8555)](https://bundlephobia.com/package/@deepraxis/sdk)
@@ -33,7 +33,7 @@ console.log(completion.choices[0]?.message.content);
 ## Why this SDK
 
 - **The whole platform, one client.** About 350 operations across models, agents, sandboxes,
-  cloud browsers, web search, databases, knowledge bases, files, media, automation and hosted
+  browsers, web search, databases, knowledge bases, files, media, automation and hosted
   applications, generated from the same contract as the API.
 - **Types from the contract.** Every path, query, body and response is typed, including the
   events of each stream, so your editor knows what comes back.
@@ -55,7 +55,7 @@ server. You need a Praxis account; sign up at [deepraxis.com](https://deepraxis.
 const praxis = new Praxis({
   apiKey: process.env.PRAXIS_API_KEY!,
   baseUrl: 'https://api.deepraxis.com',  // default
-  timeoutMs: 60_000,   // default; the whole call, body included
+  timeoutMs: 600_000,  // default (10 minutes, as the OpenAI and Anthropic SDKs); the whole call, body included
   maxRetries: 2,       // default
   // fetch: customFetch,  // bring your own fetch
 });
@@ -276,5 +276,5 @@ sandboxes, search, data, automation and the rest of the platform.
 
 [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0). Copyright 2026 南京深度实践人工智能科技有限公司 (Deepractice).
 
-"Praxis", "知行云" and "Deepraxis" are trademarks of Deepractice; the license does not grant
+"Praxis" and "Deepraxis" are trademarks of Deepractice; the license does not grant
 rights to use them.

package/dist/automation.d.ts

@@ -23,6 +23,13 @@ export declare function createAutomationClient(options: PraxisOptions): {
     hooks: {
         send: (options: import("./core/transport.js").CallOptions<import("./generated/types.gen.js").AutomationHooksReceiveData>) => Promise<import("./generated/types.gen.js").AutomationFiring>;
     };
+    humanTasks: {
+        cancel: (options: import("./core/transport.js").CallOptions<import("./generated/types.gen.js").AutomationHumanTasksCancelData>) => Promise<import("./generated/types.gen.js").AutomationHumanTask>;
+        delegate: (options: import("./core/transport.js").CallOptions<import("./generated/types.gen.js").AutomationHumanTasksDelegateData>) => Promise<import("./generated/types.gen.js").AutomationHumanTask>;
+        list: (options?: import("./core/transport.js").CallOptions<import("./generated/types.gen.js").AutomationHumanTasksListData> | undefined) => Promise<import("./automation.js").Page<import("./generated/types.gen.js").AutomationHumanTask>>;
+        respond: (options: import("./core/transport.js").CallOptions<import("./generated/types.gen.js").AutomationHumanTasksRespondData>) => Promise<import("./generated/types.gen.js").AutomationHumanTask>;
+        retrieve: (options: import("./core/transport.js").CallOptions<import("./generated/types.gen.js").AutomationHumanTasksGetData>) => Promise<import("./generated/types.gen.js").AutomationHumanTask>;
+    };
     resolve: {
         retrieve: (options: import("./core/transport.js").CallOptions<import("./generated/types.gen.js").AutomationResolveResolveData>) => Promise<import("./generated/types.gen.js").AutomationResolveResult>;
     };
@@ -89,6 +96,33 @@ export declare function createAutomationClient(options: PraxisOptions): {
         restore: (options: import("./core/transport.js").CallOptions<import("./generated/types.gen.js").AutomationScriptsRestoreData>) => Promise<import("./generated/types.gen.js").AutomationDefinition>;
         retrieve: (options: import("./core/transport.js").CallOptions<import("./generated/types.gen.js").AutomationScriptsGetData>) => Promise<import("./generated/types.gen.js").AutomationDefinitionDetail>;
         update: (options: import("./core/transport.js").CallOptions<import("./generated/types.gen.js").AutomationScriptsPatchData>) => Promise<import("./generated/types.gen.js").AutomationDefinitionDetail>;
+        vaults: {
+            delete: (options: import("./core/transport.js").CallOptions<import("./generated/types.gen.js").AutomationScriptsVaultsDeleteData>) => Promise<void>;
+            list: (options: import("./core/transport.js").CallOptions<import("./generated/types.gen.js").AutomationScriptsVaultsListData>) => Promise<{
+                data: Array<{
+                    alias: string;
+                    vault: {
+                        id: string;
+                        name: string;
+                    };
+                    secrets: Array<{
+                        name: string;
+                    }>;
+                    secrets_unavailable?: true;
+                }>;
+            }>;
+            set: (options: import("./core/transport.js").CallOptions<import("./generated/types.gen.js").AutomationScriptsVaultsSetData>) => Promise<{
+                alias: string;
+                vault: {
+                    id: string;
+                    name: string;
+                };
+                secrets: Array<{
+                    name: string;
+                }>;
+                secrets_unavailable?: true;
+            }>;
+        };
         versions: {
             create: (options: import("./core/transport.js").CallOptions<import("./generated/types.gen.js").AutomationScriptsPublishData>) => Promise<import("./generated/types.gen.js").AutomationVersion>;
             deprecate: (options: import("./core/transport.js").CallOptions<import("./generated/types.gen.js").AutomationScriptsDeprecateData>) => Promise<import("./generated/types.gen.js").AutomationVersion>;
@@ -136,6 +170,33 @@ export declare function createAutomationClient(options: PraxisOptions): {
         restore: (options: import("./core/transport.js").CallOptions<import("./generated/types.gen.js").AutomationWorkflowsRestoreData>) => Promise<import("./generated/types.gen.js").AutomationDefinition>;
         retrieve: (options: import("./core/transport.js").CallOptions<import("./generated/types.gen.js").AutomationWorkflowsGetData>) => Promise<import("./generated/types.gen.js").AutomationDefinitionDetail>;
         update: (options: import("./core/transport.js").CallOptions<import("./generated/types.gen.js").AutomationWorkflowsPatchData>) => Promise<import("./generated/types.gen.js").AutomationDefinitionDetail>;
+        vaults: {
+            delete: (options: import("./core/transport.js").CallOptions<import("./generated/types.gen.js").AutomationWorkflowsVaultsDeleteData>) => Promise<void>;
+            list: (options: import("./core/transport.js").CallOptions<import("./generated/types.gen.js").AutomationWorkflowsVaultsListData>) => Promise<{
+                data: Array<{
+                    alias: string;
+                    vault: {
+                        id: string;
+                        name: string;
+                    };
+                    secrets: Array<{
+                        name: string;
+                    }>;
+                    secrets_unavailable?: true;
+                }>;
+            }>;
+            set: (options: import("./core/transport.js").CallOptions<import("./generated/types.gen.js").AutomationWorkflowsVaultsSetData>) => Promise<{
+                alias: string;
+                vault: {
+                    id: string;
+                    name: string;
+                };
+                secrets: Array<{
+                    name: string;
+                }>;
+                secrets_unavailable?: true;
+            }>;
+        };
         versions: {
             create: (options: import("./core/transport.js").CallOptions<import("./generated/types.gen.js").AutomationWorkflowsPublishData>) => Promise<import("./generated/types.gen.js").AutomationVersion>;
             deprecate: (options: import("./core/transport.js").CallOptions<import("./generated/types.gen.js").AutomationWorkflowsDeprecateData>) => Promise<import("./generated/types.gen.js").AutomationVersion>;

package/dist/core/client.d.ts

@@ -1,12 +1,22 @@
+import { type SandboxTemplateBuildInput, type SandboxTemplateBuildResult } from "../helpers/sandbox-templates.js";
 import { type UploadFileOptions, type UploadedFile } from '../helpers/file-upload.js';
 import { resourceFactories } from '../resources.generated.js';
 import { type PraxisOptions } from './transport.js';
 import { type PublishInput, type PublishResult } from '../helpers/application-publish.js';
+import { type BrowserConnectOptions, type PraxisBrowser } from '../helpers/browser-connect.js';
 import { type CountInput, type CountResult } from '../helpers/database-count.js';
 type Resources = {
     readonly [K in keyof typeof resourceFactories]: ReturnType<(typeof resourceFactories)[K]>;
 };
-export interface Praxis extends Omit<Resources, 'application' | 'database' | 'file'> {
+export interface Praxis extends Omit<Resources, 'application' | 'browser' | 'database' | 'file' | 'sandbox'> {
+    readonly sandbox: Omit<Resources['sandbox'], 'templates'> & {
+        templates: Resources['sandbox']['templates'] & {
+            build(input: SandboxTemplateBuildInput): Promise<SandboxTemplateBuildResult>;
+        };
+    };
+    readonly browser: Resources['browser'] & {
+        connect(options?: BrowserConnectOptions): Promise<PraxisBrowser>;
+    };
     readonly file: Resources['file'] & {
         uploadFile(file: Blob | File, options: UploadFileOptions): Promise<UploadedFile>;
     };

package/dist/core/client.js

@@ -1,7 +1,9 @@
+import { buildSandboxTemplate } from "../helpers/sandbox-templates.js";
 import { uploadFile } from "../helpers/file-upload.js";
 import { resourceFactories } from "../resources.generated.js";
 import { Transport } from "./transport.js";
 import { publish } from "../helpers/application-publish.js";
+import { connectBrowser } from "../helpers/browser-connect.js";
 import { count } from "../helpers/database-count.js";
 export class Praxis {
     constructor(options) {
@@ -9,10 +11,21 @@ export class Praxis {
         for (const [name, create] of Object.entries(resourceFactories)) {
             const resource = create(transport);
             // Assemble before sealing the resource property; never replace a readonly SDK resource.
+            if (name === 'sandbox')
+                Object.assign(resource.templates, { build: (input) => buildSandboxTemplate(this, input) });
             if (name === 'file')
                 Object.assign(resource, { uploadFile: (file, options) => uploadFile(this, file, options) });
             if (name === 'database')
                 Object.assign(resource, { count: (input) => count(transport, input) });
+            if (name === 'browser') {
+                // The npm build has no Node globals in scope; name the process shape this helper reads.
+                const host = globalThis.process;
+                Object.assign(resource, { connect: (options) => connectBrowser({
+                        contexts: resource.contexts,
+                        env: host?.env ?? {},
+                        builtin: host?.getBuiltinModule?.bind(host),
+                    }, options) });
+            }
             if (name === 'application')
                 Object.assign(resource, { publish: (input) => publish(this, input) });
             Object.defineProperty(this, name, { value: resource, enumerable: true });

package/dist/core/errors.d.ts

@@ -9,6 +9,9 @@ export interface ProblemDetails {
     requestId?: string;
     message?: string;
     param?: string | null;
+    /** ticket-681 — the documentation page the failure points at, and the exact section to read. */
+    docUrl?: string;
+    describe?: string;
     raw?: unknown;
 }
 /** Pure normalization shared by HTTP clients and the automation call ledger.
@@ -26,6 +29,9 @@ export declare class PraxisError extends Error {
     readonly errors: unknown[];
     readonly requestId?: string;
     readonly param?: string | null;
+    /** ticket-681 — the documented page and the exact section an agent should read to fix the call. */
+    readonly docUrl?: string;
+    readonly describe?: string;
     readonly raw?: unknown;
     constructor(problem?: ProblemDetails, options?: ErrorOptions);
     static fromResponse(response: Response, body: unknown): PraxisError;

package/dist/core/errors.js

@@ -16,6 +16,9 @@ export function problemFrom(status, headers, body, statusText) {
         param: typeof param === 'string' ? param : param === null || nested.param === null ? null : undefined,
         errors: Array.isArray(value.errors) ? value.errors : [],
         requestId: headers.get('x-request-id') ?? string(value.requestId) ?? string(value.request_id),
+        // Both spellings reach here: the own face writes snake_case, an in-process problem keeps docUrl.
+        docUrl: string(nested.doc_url) ?? string(value.doc_url) ?? string(nested.docUrl) ?? string(value.docUrl),
+        describe: string(nested.describe) ?? string(value.describe),
         raw: body,
     };
 }
@@ -28,6 +31,9 @@ export class PraxisError extends Error {
     errors;
     requestId;
     param;
+    /** ticket-681 — the documented page and the exact section an agent should read to fix the call. */
+    docUrl;
+    describe;
     raw;
     constructor(problem = {}, options) {
         super(problem.message ?? problem.detail ?? problem.title ?? `Praxis request failed${problem.status ? ` (${problem.status})` : ''}`, options);
@@ -40,6 +46,8 @@ export class PraxisError extends Error {
         this.errors = problem.errors ?? [];
         this.requestId = problem.requestId;
         this.param = problem.param;
+        this.docUrl = problem.docUrl;
+        this.describe = problem.describe;
         this.raw = problem.raw;
     }
     static fromResponse(response, body) {

package/dist/core/transport.d.ts

@@ -25,6 +25,15 @@ type InternalOptions = RequestOptions & {
     query?: unknown;
     lastEventId?: string;
 };
+/** Margin over a server-side execution deadline: the response still has to travel back after it. */
+export declare const SERVER_DEADLINE_MARGIN_MS = 30000;
+/**
+ * A request body that carries its own execution deadline (`timeoutMs`, as in sandbox commands.run) is
+ * waited for at least that long plus a margin, so the client never gives up before the server answers.
+ */
+export declare function serverDeadlineMs(options: {
+    body?: unknown;
+}): number;
 export declare class Transport {
     private readonly config;
     constructor(options: PraxisOptions);

package/dist/core/transport.js

@@ -32,10 +32,21 @@ function assertKnownOptions(options) {
         detail: `Unrecognised option ${stray.length > 1 ? 'keys' : 'key'} ${names}. Request parameters are not flat: put each under \`query\` (GET/DELETE: filters, pagination), \`path\` (URL segments) or \`body\` (POST/PATCH/PUT payload), e.g. call({ query: { ${stray[0]} } }) or call({ body: { ${stray[0]} } }). Common top-level keys: path, query, body, headers, signal, timeoutMs, maxRetries.`,
     });
 }
+/** Margin over a server-side execution deadline: the response still has to travel back after it. */
+export const SERVER_DEADLINE_MARGIN_MS = 30_000;
+/**
+ * A request body that carries its own execution deadline (`timeoutMs`, as in sandbox commands.run) is
+ * waited for at least that long plus a margin, so the client never gives up before the server answers.
+ */
+export function serverDeadlineMs(options) {
+    const body = options.body;
+    const deadline = body && typeof body === 'object' ? body.timeoutMs : undefined;
+    return typeof deadline === 'number' && Number.isFinite(deadline) && deadline > 0 ? deadline + SERVER_DEADLINE_MARGIN_MS : 0;
+}
 export class Transport {
     config;
     constructor(options) {
-        this.config = { timeoutMs: 60_000, maxRetries: 2, fetch: globalThis.fetch, ...options };
+        this.config = { timeoutMs: 600_000, maxRetries: 2, fetch: globalThis.fetch, ...options };
         this.validate(this.config.timeoutMs, this.config.maxRetries);
     }
     validate(timeout, retries) {
@@ -46,7 +57,7 @@ export class Transport {
     }
     scope(options, streaming) {
         assertKnownOptions(options);
-        const timeoutMs = options.timeoutMs ?? this.config.timeoutMs;
+        const timeoutMs = options.timeoutMs ?? Math.max(this.config.timeoutMs, serverDeadlineMs(options));
         const maxRetries = options.maxRetries ?? this.config.maxRetries;
         this.validate(timeoutMs, maxRetries);
         const controller = new AbortController();