@deepraxis/sdk 0.1.1-dev.f8aa5de → 0.1.1-dev.faa3b25

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
 });
@@ -122,7 +122,7 @@ conversation with it, on its own machine.
 ```ts
 const { sandboxes } = praxis.sandbox;
 const sandbox = await sandboxes.create({
-  body: { templateID: 'base' },
+  body: { templateID: 'base', autoPause: false }, // ends at its timeout; autoPause: true keeps a long-lived computer
 });
 const result = await sandboxes.commands.run({
   path: { sandbox_id: sandbox.sandboxID },
@@ -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

@@ -96,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>;
@@ -143,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,3 +1,4 @@
+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';
@@ -7,7 +8,12 @@ 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' | 'browser' | '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>;
     };

package/dist/core/client.js

@@ -1,3 +1,4 @@
+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";
@@ -10,6 +11,8 @@ 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')

package/dist/core/credentials.d.ts

@@ -1,7 +1,9 @@
 /**
- * Default credential chain for code running on a Praxis computer (ticket-5367):
- * PRAXIS_API_TOKEN environment variable, then ~/.praxis/credentials. Resolved at call time so a
- * token the platform renewed in the file is picked up by an already-running process.
+ * Default credential chain for code running on a Praxis computer (ticket-5367, ADR-098 §2):
+ * the PRAXIS_API_TOKEN environment variable, then the login file of the environment,
+ * `~/.praxis/cli/<env>.json` — the one file `praxis login` writes for a person and the platform writes
+ * for a managed login. Resolved at call time so a token the platform renewed in the file is picked up
+ * by an already-running process.
  */
 export interface ResolvedCredentials {
     token?: string;
@@ -9,6 +11,13 @@ export interface ResolvedCredentials {
 }
 type Env = Record<string, string | undefined>;
 type ReadFile = (path: string) => string | null;
+/**
+ * Which environment's login file applies: PRAXIS_ENV when it names one, otherwise a `-develop.` host in
+ * PRAXIS_API_URL means develop and any other host production — the rule apps/cli/src/config/env.ts
+ * applies. A PRAXIS_ENV that is not a plain name is no environment at all and is ignored. Pure.
+ */
+export declare function credentialsEnv(env: Env): string;
+/** The one login file, the same path the CLI reads for this environment. Null without a home directory. Pure. */
 export declare function credentialsPath(env: Env): string | null;
 export declare function resolveDefaultCredentials(env?: Env, readFile?: ReadFile): ResolvedCredentials;
 export {};

package/dist/core/credentials.js

@@ -8,9 +8,29 @@ function defaultReadFile(path) {
         return null;
     }
 }
+/**
+ * Which environment's login file applies: PRAXIS_ENV when it names one, otherwise a `-develop.` host in
+ * PRAXIS_API_URL means develop and any other host production — the rule apps/cli/src/config/env.ts
+ * applies. A PRAXIS_ENV that is not a plain name is no environment at all and is ignored. Pure.
+ */
+export function credentialsEnv(env) {
+    const declared = nonEmpty(env.PRAXIS_ENV);
+    if (declared && /^[A-Za-z0-9_-]+$/.test(declared))
+        return declared;
+    const apiUrl = nonEmpty(env.PRAXIS_API_URL);
+    if (apiUrl) {
+        try {
+            if (new URL(apiUrl).hostname.includes('-develop.'))
+                return 'develop';
+        }
+        catch { /* a malformed URL is not evidence of develop */ }
+    }
+    return 'production';
+}
+/** The one login file, the same path the CLI reads for this environment. Null without a home directory. Pure. */
 export function credentialsPath(env) {
     const home = nonEmpty(env.HOME) ?? nonEmpty(env.USERPROFILE);
-    return home ? `${home.replace(/\/$/, '')}/.praxis/credentials` : null;
+    return home ? `${home.replace(/[/\\]+$/, '')}/.praxis/cli/${credentialsEnv(env)}.json` : null;
 }
 export function resolveDefaultCredentials(env = globalThis.process?.env ?? {}, readFile = defaultReadFile) {
     const envToken = nonEmpty(env.PRAXIS_API_TOKEN);
@@ -23,7 +43,7 @@ export function resolveDefaultCredentials(env = globalThis.process?.env ?? {}, r
         return envUrl ? { apiUrl: envUrl } : {};
     try {
         const file = JSON.parse(text);
-        const token = nonEmpty(file.token);
+        const token = nonEmpty(file.access_token);
         const apiUrl = envUrl ?? nonEmpty(file.api_url);
         return { ...(token ? { token } : {}), ...(apiUrl ? { apiUrl } : {}) };
     }

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

@@ -1,6 +1,6 @@
 import { type SSEEvent } from './sse.js';
 export interface PraxisOptions {
-    /** Explicit key. Omitted on a Praxis computer: PRAXIS_API_TOKEN, then ~/.praxis/credentials, are used. */
+    /** Explicit key. Omitted on a Praxis computer: PRAXIS_API_TOKEN, then the login file `~/.praxis/cli/<env>.json`, are used. */
     apiKey?: string;
     baseUrl?: string;
     timeoutMs?: number;
@@ -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();