@deepraxis/sdk 0.1.1-dev.f0ef747 → 0.1.1-dev.fcdebee

package/dist/helpers/application-build.d.ts

@@ -0,0 +1,10 @@
+import type { PublishInput } from './application-publish.js';
+/** A vite/vinext build read into memory: paths are relative to dist/server and dist/client. */
+export interface BuildOutput {
+    serverFiles: Record<string, Uint8Array>;
+    clientFiles: Record<string, Uint8Array>;
+    /** Parsed dist/server/wrangler.json. */
+    wranglerJson: unknown;
+}
+/** Pure mapping from a vite/vinext build (dist/server + dist/client + wrangler.json) to `praxis.application.publish` input. No fs, no network. */
+export declare function publishInputFromBuild(build: BuildOutput, name: string): PublishInput;

package/dist/helpers/application-build.js

@@ -0,0 +1,98 @@
+import { PraxisError } from "../core/errors.js";
+// wrangler.json keys that declare a binding the platform does not accept (it answers UNSUPPORTED).
+const UNSUPPORTED_BINDING_KEYS = ['services', 'queues', 'durable_objects', 'ai', 'analytics_engine_datasets', 'vectorize', 'hyperdrive',
+    'browser', 'send_email', 'mtls_certificates', 'dispatch_namespaces', 'unsafe', 'version_metadata', 'images', 'workflows', 'pipelines',
+    'secrets_store_secrets', 'ratelimits', 'vpc_services', 'media', 'tail_consumers', 'worker_loaders'];
+// A key declares something only if it holds a value somewhere inside: vite's generated wrangler.json writes
+// empty containers such as `queues: { producers: [], consumers: [] }` and `durable_objects: { bindings: [] }`.
+const isPresent = (value) => {
+    if (value === undefined || value === null)
+        return false;
+    if (Array.isArray(value))
+        return value.some(isPresent);
+    if (typeof value === 'object')
+        return Object.values(value).some(isPresent);
+    return true;
+};
+/** Compile one .assetsignore line (gitignore subset: names, `*`, `**`, leading /, trailing /) to a matcher over a relative path. */
+function ignoreMatcher(line) {
+    let pattern = line.trim();
+    if (!pattern || pattern.startsWith('#') || pattern.startsWith('!'))
+        return null;
+    const anchored = pattern.startsWith('/') || pattern.slice(0, -1).includes('/');
+    pattern = pattern.replace(/^\//, '').replace(/\/$/, '');
+    const source = pattern.split('**').map(part => part.split('*').map(piece => piece.replace(/[.+?^${}()|[\]\\]/g, '\\$&')).join('[^/]*')).join('.*');
+    const regex = new RegExp(`^${source}$`);
+    return path => {
+        const segments = path.split('/');
+        // The path or any of its parent directories matches, as in gitignore.
+        for (let end = 1; end <= segments.length; end++) {
+            if (anchored ? regex.test(segments.slice(0, end).join('/')) : regex.test(segments[end - 1]))
+                return true;
+        }
+        return false;
+    };
+}
+function bindingsFrom(wrangler) {
+    const bindings = [];
+    const fromList = (key, type) => {
+        const list = wrangler[key];
+        if (!isPresent(list))
+            return;
+        if (!Array.isArray(list))
+            throw new PraxisError({ code: 'INVALID_PARAMS', message: `wrangler.json ${key} must be an array` });
+        for (const entry of list) {
+            if (typeof entry?.binding !== 'string')
+                throw new PraxisError({ code: 'INVALID_PARAMS', message: `wrangler.json ${key} entry has no binding name` });
+            bindings.push({ type, name: entry.binding });
+        }
+    };
+    fromList('d1_databases', 'd1');
+    fromList('kv_namespaces', 'kv_namespace');
+    fromList('r2_buckets', 'r2_bucket');
+    for (const [name, value] of Object.entries((wrangler.vars ?? {}))) {
+        bindings.push((typeof value === 'string' ? { type: 'plain_text', name, text: value } : { type: 'json', name, json: value }));
+    }
+    if (typeof wrangler.assets?.binding === 'string')
+        bindings.push({ type: 'assets', name: wrangler.assets.binding });
+    return bindings;
+}
+/** Pure mapping from a vite/vinext build (dist/server + dist/client + wrangler.json) to `praxis.application.publish` input. No fs, no network. */
+export function publishInputFromBuild(build, name) {
+    const wrangler = build.wranglerJson;
+    if (!wrangler || typeof wrangler !== 'object' || Array.isArray(wrangler)) {
+        throw new PraxisError({ code: 'INVALID_PARAMS', message: 'wranglerJson must be the parsed dist/server/wrangler.json object' });
+    }
+    const offending = UNSUPPORTED_BINDING_KEYS.filter(key => isPresent(wrangler[key]));
+    if (offending.length) {
+        throw new PraxisError({ code: 'UNSUPPORTED', message: `wrangler.json declares bindings the platform does not support: ${offending.join(', ')}` });
+    }
+    const modules = Object.entries(build.serverFiles)
+        .filter(([path]) => path.endsWith('.js'))
+        .map(([path, content]) => ({ name: path, content, content_type: 'application/javascript+module' }));
+    if (typeof wrangler.main !== 'string')
+        throw new PraxisError({ code: 'INVALID_PARAMS', message: 'wrangler.json has no main entry' });
+    if (!modules.some(module => module.name === wrangler.main)) {
+        throw new PraxisError({ code: 'INVALID_PARAMS', message: `wrangler.json main ${wrangler.main} is not a .js file under dist/server` });
+    }
+    const ignored = new TextDecoder().decode(build.clientFiles['.assetsignore'] ?? new Uint8Array()).split(/\r?\n/)
+        .map(ignoreMatcher).filter((matcher) => matcher !== null);
+    const files = {};
+    for (const [path, content] of Object.entries(build.clientFiles)) {
+        if (path === '.assetsignore' || ignored.some(matches => matches(path)))
+            continue;
+        files[`/${path}`] = content;
+    }
+    const { binding: _binding, directory: _directory, ...assetsConfig } = (wrangler.assets ?? {});
+    const bindings = bindingsFrom(wrangler);
+    return {
+        name,
+        files,
+        modules,
+        main_module: wrangler.main,
+        ...(typeof wrangler.compatibility_date === 'string' ? { compatibility_date: wrangler.compatibility_date } : {}),
+        ...(Array.isArray(wrangler.compatibility_flags) ? { compatibility_flags: wrangler.compatibility_flags } : {}),
+        ...(bindings.length ? { bindings } : {}),
+        ...(Object.keys(assetsConfig).length ? { assets_config: assetsConfig } : {}),
+    };
+}

package/dist/helpers/application-publish.d.ts

@@ -12,6 +12,14 @@ export interface PublishInput {
         content: string;
         content_type?: string;
     };
+    /** Multi-module Worker (e.g. a vite/vinext build). Names pass through unchanged; relative paths with / are legal. Mutually exclusive with main. */
+    modules?: {
+        name: string;
+        content: string | Uint8Array;
+        content_type?: string;
+    }[];
+    /** Entry module name; defaults to the first module and must name one of modules. */
+    main_module?: string;
     /** 运行时兼容日期，默认当天 UTC（YYYY-MM-DD）。 */
     compatibility_date?: string;
     /** 运行时兼容标志，原样传递；平台固定附加 global_fetch_strictly_public。 */

package/dist/helpers/application-publish.js

@@ -21,11 +21,30 @@ export async function publish(client, input) {
     const timeout = input.timeout_ms ?? 120_000;
     if (!Number.isFinite(timeout) || timeout < 0)
         throw new RangeError('timeout_ms must be non-negative and finite');
-    const contentType = ['application/javascript+module', 'text/javascript', 'application/javascript', 'application/json',
-        'text/plain', 'application/wasm', 'application/octet-stream', 'application/x-python']
-        .find(type => type === (input.main?.content_type ?? 'application/javascript+module'));
-    if (!contentType)
-        throw new PraxisError({ code: 'INVALID_PARAMS', message: `Unsupported module content_type: ${input.main?.content_type}` });
+    const moduleTypes = ['application/javascript+module', 'text/javascript', 'application/javascript', 'application/json',
+        'text/plain', 'application/wasm', 'application/octet-stream', 'application/x-python'];
+    const moduleType = (type) => {
+        const found = moduleTypes.find(candidate => candidate === (type ?? 'application/javascript+module'));
+        if (!found)
+            throw new PraxisError({ code: 'INVALID_PARAMS', message: `Unsupported module content_type: ${type}` });
+        return found;
+    };
+    if (input.main && input.modules)
+        throw new PraxisError({ code: 'INVALID_PARAMS', message: 'Pass either main or modules, not both' });
+    if (input.main_module !== undefined && !input.modules)
+        throw new PraxisError({ code: 'INVALID_PARAMS', message: 'main_module requires modules; with main the entry is main.name' });
+    if (input.modules && input.modules.length === 0)
+        throw new PraxisError({ code: 'INVALID_PARAMS', message: 'modules must not be empty' });
+    const entryModules = input.main
+        ? [{ name: input.main.name, content_type: moduleType(input.main.content_type), content_base64: base64(new TextEncoder().encode(input.main.content)) }]
+        : input.modules?.map(module => ({ name: module.name, content_type: moduleType(module.content_type),
+            content_base64: base64(typeof module.content === 'string' ? new TextEncoder().encode(module.content) : module.content) }));
+    if (new Set(entryModules?.map(module => module.name)).size !== (entryModules?.length ?? 0))
+        throw new PraxisError({ code: 'INVALID_PARAMS', message: 'Duplicate module name' });
+    const mainModule = input.main ? input.main.name : input.modules ? (input.main_module ?? input.modules[0].name) : undefined;
+    if (input.modules && !input.modules.some(module => module.name === mainModule)) {
+        throw new PraxisError({ code: 'INVALID_PARAMS', message: `main_module ${mainModule} is not among modules` });
+    }
     const files = Object.entries(input.files);
     if (files.length > 100_000)
         throw new PraxisError({ code: 'LIMIT_EXCEEDED', message: 'At most 100000 asset paths can be published' });
@@ -80,7 +99,7 @@ export async function publish(client, input) {
     const removed = Object.keys(previous).filter(key => !Object.hasOwn(manifest, key));
     const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(JSON.stringify(manifest))));
     const manifestHash = Array.from(digest, byte => byte.toString(16).padStart(2, '0')).join('');
-    const staticOnly = !['main', 'bindings', 'compatibility_date', 'compatibility_flags', 'assets_config'].some(key => Object.hasOwn(input, key));
+    const staticOnly = !['main', 'modules', 'main_module', 'bindings', 'compatibility_date', 'compatibility_flags', 'assets_config'].some(key => Object.hasOwn(input, key));
     const unchanged = staticOnly && !!currentVersion && manifestHash === currentVersion.praxis.assets_manifest?.manifest_hash;
     const hashes = new Set(Object.values(manifest).map(entry => entry.hash));
     const currentResult = { url: worker.subdomain.url, worker_id: worker.id, version_id: currentVersion?.id ?? null,
@@ -127,9 +146,7 @@ export async function publish(client, input) {
             assets: versionAssets,
             ...(input.compatibility_flags ? { compatibility_flags: input.compatibility_flags } : {}),
             ...(input.bindings ? { bindings: input.bindings } : {}),
-            ...(input.main ? { main_module: input.main.name, modules: [{ name: input.main.name,
-                        content_type: contentType,
-                        content_base64: base64(new TextEncoder().encode(input.main.content)) }] } : {}),
+            ...(entryModules ? { main_module: mainModule, modules: entryModules } : {}),
         } });
     let deployment = result.deployment;
     if (!deployment)

package/dist/helpers/browser-decisions.d.ts

@@ -40,3 +40,5 @@ export interface ContextLike {
 export declare function pickAgentContext<T extends ContextLike>(contexts: readonly T[], agentId: string): T | undefined;
 /** Context names accept ASCII letters, digits and . _ : - only. */
 export declare const agentContextName: (agentId: string) => string;
+/** Start pages are expendable only on Console hosts, never arbitrary sites' /start pages. */
+export declare function isBlankTab(value: string): boolean;

package/dist/helpers/browser-decisions.js

@@ -48,7 +48,7 @@ export function decideTabReuse(targetUrl, tabs) {
         if (best === undefined || rank < best.rank || rank === best.rank && (tab.active || !best.tab.active))
             best = { tab, rank };
     }
-    return best?.tab;
+    return best?.tab ?? tabs.find(tab => isBlankTab(tab.url));
 }
 /** The `/browser/v1/connect` WebSocket URL. The token travels in a header, never in this URL. */
 export function buildConnectUrl(parts) {
@@ -69,3 +69,16 @@ export function pickAgentContext(contexts, agentId) {
 }
 /** Context names accept ASCII letters, digits and . _ : - only. */
 export const agentContextName = (agentId) => `agent-${agentId}`.replace(/[^A-Za-z0-9._:-]/g, '-').slice(0, 128);
+/** Start pages are expendable only on Console hosts, never arbitrary sites' /start pages. */
+export function isBlankTab(value) {
+    if (value === "" || value === "about:blank")
+        return true;
+    try {
+        const url = new URL(value);
+        return (url.protocol === "https:" || url.protocol === "http:") && url.pathname === "/start" &&
+            (url.hostname.startsWith("console-") || url.hostname === "console.deepraxis.com");
+    }
+    catch {
+        return false;
+    }
+}

package/dist/helpers/file-upload.d.ts

@@ -1,8 +1,8 @@
 import type { Praxis } from '../core/client.js';
 import type { OwnFileOpenAiFile } from '../generated/types.gen.js';
 export interface UploadFileOptions {
-    /** user_data for conversation attachments; assistants for assistant files; vision for PNG/JPEG/GIF/WebP. */
-    purpose: 'user_data' | 'assistants' | 'vision';
+    /** user_data for conversation attachments and documents; vision for PNG/JPEG/GIF/WebP. */
+    purpose: 'user_data' | 'vision';
     /** Defaults to File.name, or upload for a Blob. */
     filename?: string;
     /** Fixed part size in bytes, 5 MiB–64 MB; defaults to 50 MiB. */

package/dist/helpers/sandbox-templates.d.ts

@@ -0,0 +1,121 @@
+export interface TemplateBuildLog {
+    timestamp: string;
+    level: 'debug' | 'info' | 'warn' | 'error';
+    message: string;
+    step?: string;
+}
+export interface TemplateBuildReason {
+    message: string;
+    step?: string;
+    logEntries?: TemplateBuildLog[];
+}
+export interface TemplateBuildStatus {
+    templateID: string;
+    buildID: string;
+    status: 'waiting' | 'building' | 'ready' | 'error';
+    logEntries: TemplateBuildLog[];
+    logs: string[];
+    reason?: TemplateBuildReason;
+}
+export type SandboxTemplateBuildInput = {
+    /** Organization-local name. Reusing it reserves another build of the same template. */
+    name: string;
+    /** Optional resource counts; defaults to 2 vCPUs and 1024 MiB. */
+    cpuCount?: number;
+    memoryMB?: number;
+    /** Disk size in GiB, a positive integer; default 10. */
+    diskGb?: number;
+    /** Labels assigned only after a successful build. */
+    tags?: string[];
+    /** Structured build steps; COPY is rejected. Mutually exclusive with dockerfile. */
+    steps?: {
+        type: 'RUN' | 'ENV' | 'WORKDIR' | 'USER';
+        args: string[];
+    }[];
+    /** Called sequentially for newly read log entries. */
+    onLog?: (entry: TemplateBuildLog) => void | Promise<void>;
+    /** Stops requests and polling; the remote build continues. */
+    signal?: AbortSignal;
+    /** Nonnegative polling delay in milliseconds; default 1000. */
+    pollIntervalMs?: number;
+} & ({
+    dockerfile: string;
+    fromTemplate?: never;
+    fromImage?: never;
+    steps?: never;
+} | {
+    dockerfile?: never;
+    fromTemplate: string;
+    fromImage?: never;
+} | {
+    dockerfile?: never;
+    fromTemplate?: never;
+    fromImage: string;
+});
+export interface SandboxTemplateBuildResult extends TemplateBuildStatus {
+    status: 'ready';
+}
+export declare class SandboxTemplateBuildError extends Error {
+    readonly templateID: string;
+    readonly buildID: string;
+    readonly reason: TemplateBuildReason | undefined;
+    readonly logEntries: readonly TemplateBuildLog[];
+    readonly name = "SandboxTemplateBuildError";
+    constructor(templateID: string, buildID: string, reason: TemplateBuildReason | undefined, logEntries: readonly TemplateBuildLog[]);
+}
+/** Structural port keeps the helper independent of the client that attaches it. */
+export interface SandboxTemplateBuildClient {
+    sandbox: {
+        templates: {
+            create(input: {
+                body: {
+                    name: string;
+                    cpuCount?: number;
+                    memoryMB?: number;
+                    diskGb?: number;
+                    tags?: string[];
+                };
+                signal: AbortSignal;
+            }): Promise<{
+                templateID: string;
+                buildID: string;
+            }>;
+            builds: {
+                update(input: {
+                    path: {
+                        templateID: string;
+                        buildID: string;
+                    };
+                    body: {
+                        dockerfile?: string;
+                        fromTemplate?: string;
+                        fromImage?: string;
+                        steps?: {
+                            type: string;
+                            args: string[];
+                        }[];
+                    };
+                    signal: AbortSignal;
+                }): Promise<unknown>;
+                status: {
+                    list(input: {
+                        path: {
+                            templateID: string;
+                            buildID: string;
+                        };
+                        query: {
+                            logsOffset: number;
+                        };
+                        signal: AbortSignal;
+                    }): Promise<TemplateBuildStatus>;
+                };
+            };
+        };
+    };
+}
+/** Build an organization-local template and wait until it is ready, streaming logs in order.
+ * Uses create, source submission and status polling. COPY is unavailable; use RUN curl or git clone.
+ * fromTemplate accepts official catalog names only. Abort stops the client; it does not cancel the build.
+ * Terminal errors include the provider reason and the final twenty bounded log entries.
+ */
+export declare function buildSandboxTemplate(client: SandboxTemplateBuildClient, input: SandboxTemplateBuildInput): Promise<SandboxTemplateBuildResult>;

package/dist/helpers/sandbox-templates.js

@@ -0,0 +1,60 @@
+import { sleep } from "../core/retry.js";
+export class SandboxTemplateBuildError extends Error {
+    templateID;
+    buildID;
+    reason;
+    logEntries;
+    name = 'SandboxTemplateBuildError';
+    constructor(templateID, buildID, reason, logEntries) {
+        super(`Template build failed: ${reason?.message ?? 'Unknown build error'}${logEntries.length ? `\n${logEntries.map(log => log.message).join('\n')}` : ''}`);
+        this.templateID = templateID;
+        this.buildID = buildID;
+        this.reason = reason;
+        this.logEntries = logEntries;
+    }
+}
+/** Build an organization-local template and wait until it is ready, streaming logs in order.
+ * Uses create, source submission and status polling. COPY is unavailable; use RUN curl or git clone.
+ * fromTemplate accepts official catalog names only. Abort stops the client; it does not cancel the build.
+ * Terminal errors include the provider reason and the final twenty bounded log entries.
+ */
+export async function buildSandboxTemplate(client, input) {
+    const signal = input.signal ?? new AbortController().signal;
+    signal.throwIfAborted();
+    const interval = input.pollIntervalMs ?? 1000;
+    if (!Number.isSafeInteger(interval) || interval < 0)
+        throw new RangeError('pollIntervalMs must be a nonnegative integer');
+    if ([input.dockerfile, input.fromTemplate, input.fromImage].filter(value => value !== undefined).length !== 1
+        || (input.dockerfile !== undefined && input.steps !== undefined))
+        throw new TypeError('Supply dockerfile, fromTemplate or fromImage; dockerfile cannot include steps');
+    const created = await client.sandbox.templates.create({ body: {
+            name: input.name, cpuCount: input.cpuCount, memoryMB: input.memoryMB, diskGb: input.diskGb, tags: input.tags,
+        }, signal });
+    const path = { templateID: created.templateID, buildID: created.buildID };
+    await client.sandbox.templates.builds.update({ path, body: input.dockerfile !== undefined ? { dockerfile: input.dockerfile }
+            : { fromTemplate: input.fromTemplate, fromImage: input.fromImage, steps: input.steps }, signal });
+    let logsOffset = 0;
+    const tail = [];
+    let terminal;
+    while (true) {
+        signal.throwIfAborted();
+        const result = await client.sandbox.templates.builds.status.list({ path, query: { logsOffset }, signal });
+        for (const entry of result.logEntries) {
+            signal.throwIfAborted();
+            await input.onLog?.(entry);
+            // Bound retained diagnostics even when one provider log message is enormous.
+            tail.push({ ...entry, message: entry.message.slice(-4096) });
+            if (tail.length > 20)
+                tail.shift();
+        }
+        logsOffset += result.logEntries.length;
+        if (!terminal && (result.status === 'ready' || result.status === 'error'))
+            terminal = result;
+        if (terminal && result.logEntries.length === 0) {
+            if (terminal.status === 'error')
+                throw new SandboxTemplateBuildError(path.templateID, path.buildID, terminal.reason, tail);
+            return { ...terminal, status: 'ready', logEntries: [] };
+        }
+        await sleep(interval, signal);
+    }
+}

package/dist/index.d.ts

@@ -7,9 +7,13 @@ export { parseSSE } from './core/sse.js';
 export type { SSEEvent, SSEOptions } from './core/sse.js';
 export { publish } from './helpers/application-publish.js';
 export type { PublishInput, PublishResult, AssetsConfig } from './helpers/application-publish.js';
+export { publishInputFromBuild } from './helpers/application-build.js';
+export type { BuildOutput } from './helpers/application-build.js';
 export { count } from './helpers/database-count.js';
 export type { CountInput, CountResult } from './helpers/database-count.js';
 export { uploadFile } from './helpers/file-upload.js';
 export type { UploadFileOptions, UploadedFile } from './helpers/file-upload.js';
 export { connectBrowser } from './helpers/browser-connect.js';
 export type { PraxisBrowser, BrowserTab, BrowserConnectOptions } from './helpers/browser-connect.js';
+export { buildSandboxTemplate, SandboxTemplateBuildError } from './helpers/sandbox-templates.js';
+export type { SandboxTemplateBuildInput, SandboxTemplateBuildResult, TemplateBuildLog, TemplateBuildReason } from './helpers/sandbox-templates.js';

package/dist/index.js

@@ -3,6 +3,8 @@ export { PraxisError, PraxisConnectionError, PraxisTimeoutError } from "./core/e
 export { Page } from "./core/pagination.js";
 export { parseSSE } from "./core/sse.js";
 export { publish } from "./helpers/application-publish.js";
+export { publishInputFromBuild } from "./helpers/application-build.js";
 export { count } from "./helpers/database-count.js";
 export { uploadFile } from "./helpers/file-upload.js";
 export { connectBrowser } from "./helpers/browser-connect.js";
+export { buildSandboxTemplate, SandboxTemplateBuildError } from "./helpers/sandbox-templates.js";