@byok-sdk/cloud-do 0.0.0-stage → 0.24.0

package/dist/input-guard.d.ts

@@ -0,0 +1,13 @@
+import { type PlatformProfileId } from './platform-credentials';
+/** Keep the existing pre-storage text guard shared by submission and tool data. */
+export declare function admitCloudText(env: Readonly<Record<string, unknown>>, text: string, selected?: PlatformProfileId): Promise<void>;
+/** Check decoded JSON values before any part enters pi or the invocation ledger. */
+export declare function admitCloudPayload(env: Readonly<Record<string, unknown>>, value: unknown, selected?: PlatformProfileId): Promise<void>;
+/** Keys belong to one operation. Dispose the guard when that operation ends. */
+export interface CloudOperationGuard {
+    guardText(text: string): void;
+    /** Decode first. Check every key and value before admitted re-serialization. */
+    guardPayload(dataJson: string): string;
+    dispose(): void;
+}
+export declare function prepareCloudGuard(env: Readonly<Record<string, unknown>>, selected?: PlatformProfileId): Promise<CloudOperationGuard>;

package/dist/invocation-ledger.d.ts

@@ -0,0 +1,99 @@
+import { type CloudDoErrorCode } from './errors';
+import type { CloudOperationGuard } from './input-guard';
+export type InvocationState = 'accepted' | 'running' | 'succeeded' | 'failed' | 'aborted' | 'interrupted' | 'timed_out';
+export type InvocationTerminalState = Exclude<InvocationState, 'accepted' | 'running'>;
+export interface InvocationInput {
+    invocationId: string;
+    sessionId: string;
+    conversationId: number;
+    assistantEntryId: number;
+    toolCallId: string;
+    toolName: string;
+    argsDigest: string;
+    argsJson: string;
+    replay: 'safe' | 'unsafe';
+    deadlineAt: number;
+}
+export interface InvocationRow extends InvocationInput {
+    seq: number;
+    state: InvocationState;
+    attempt: number;
+    replayCount: number;
+    abortRequested: number;
+    resultJson: string | null;
+    settledAt: number | null;
+    settledEventSeq: number | null;
+    errorCode: CloudDoErrorCode | null;
+    mode: 'inline' | 'job';
+    segmentStartedAt: number | null;
+    nextSegmentAt: number | null;
+    jobStateJson: string | null;
+    progressJson: string | null;
+    deliveredState?: 'delivered' | 'undelivered';
+    taskId?: number | null;
+    resultEntryId?: number | null;
+}
+export interface ExecutionRow {
+    conversationId: number;
+    deadlineAt: number;
+    steps: number;
+    tools: number;
+    inputTokens: number;
+    outputTokens: number;
+    credits: number;
+    sentRequests: number;
+    fatalCode: CloudDoErrorCode | null;
+    aborted: number;
+}
+export interface InvocationFinishOptions {
+    /** An old attempt cannot settle an invocation claimed by recovery. */
+    attempt?: number;
+    clientConnected?: boolean;
+    /** Ledger recovery may settle after the old native conversation was aborted. */
+    recovery?: boolean;
+    creditCap?: number;
+}
+export interface InvocationLedgerOptions {
+    started?(row: InvocationRow, guard?: CloudOperationGuard): void;
+    startedCommitted?(row: InvocationRow): void;
+    /** Runs inside the state transaction. Errors roll back state and events together. */
+    terminal?(row: InvocationRow, recovery: boolean): {
+        seq: number;
+        createdAt: number;
+    } | void;
+    /** Post-commit notification cannot affect the invocation outcome. */
+    committed?(row: InvocationRow): void;
+}
+/** Host tables share the DO database with the pi_ tables. No function enters storage. */
+export declare class InvocationLedger {
+    #private;
+    private readonly storage;
+    private readonly options;
+    constructor(storage: DurableObjectStorage, options?: InvocationLedgerOptions);
+    /** The host calls this only after credential and identity preflight. */
+    ensureSchema(): void;
+    read(id: string): InvocationRow | undefined;
+    pending(): InvocationRow[];
+    begin(input: InvocationInput, guard?: CloudOperationGuard): {
+        kind: 'started' | 'pending' | 'settled';
+        row: InvocationRow;
+    };
+    finish(id: string, state: InvocationTerminalState, result?: Record<string, unknown>, errorCode?: CloudDoErrorCode, now?: number, options?: InvocationFinishOptions): InvocationRow | undefined;
+    /** Claim before network replay. A second restart never dispatches a claimed row again. */
+    claimRecovery(now?: number): InvocationRow[];
+    forConversation(conversationId: number): InvocationRow[];
+    startExecution(conversationId: number, deadlineAt: number): ExecutionRow;
+    execution(conversationId: number): ExecutionRow | undefined;
+    failExecution(conversationId: number, code: CloudDoErrorCode): ExecutionRow | undefined;
+    abortExecution(conversationId: number, code: CloudDoErrorCode): ExecutionRow | undefined;
+    private executionRejection;
+    countModel(conversationId: number, maxSteps?: number, now?: number, budget?: {
+        inputBytes: number;
+        inputTokens: number;
+        outputTokens: number;
+    }): ExecutionRow;
+    addModelUsage(conversationId: number, input: number, output: number): void;
+    /** This mark records durable dispatch intent. It does not prove network receipt. */
+    markModelSent(conversationId: number): void;
+    countTool(conversationId: number, taskId: string, maxTools?: number, now?: number): ExecutionRow;
+}

package/dist/leak-guard.d.ts

@@ -0,0 +1,13 @@
+/** Scans decoded model text, before any of it reaches pi or persistence. */
+export declare class RollingLeakGuard {
+    readonly tailLength: number;
+    private readonly forms;
+    private readonly percentForms;
+    private pending;
+    private closed;
+    constructor(key: string);
+    push(text: string): string;
+    finish(): string;
+    discard(): void;
+    private scan;
+}

package/dist/platform-credentials.d.ts

@@ -0,0 +1,30 @@
+/** The platform reads one key. It does not own a local credential store. */
+export type ModelProviderSecretName = `model-${string}-api-key`;
+export interface PlatformCredentialReader {
+    get(name: ModelProviderSecretName): Promise<string | undefined>;
+}
+export declare const PLATFORM_PROFILES: Readonly<{
+    zai_openai: Readonly<{
+        vendor: "zai";
+        baseUrl: "https://api.z.ai/api/coding/paas/v4";
+        model: "glm-5.3-flash";
+        binding: "AIPHABEE_ZAI_API_KEY";
+        secretName: "model-zai_openai-api-key";
+    }>;
+    deepseek_direct: Readonly<{
+        vendor: "deepseek";
+        baseUrl: "https://api.deepseek.com";
+        model: "deepseek-v4-flash";
+        binding: "AIPHABEE_DEEPSEEK_API_KEY";
+        secretName: "model-deepseek_direct-api-key";
+    }>;
+}>;
+export type PlatformProfileId = keyof typeof PLATFORM_PROFILES;
+export type PlatformProfile = (typeof PLATFORM_PROFILES)[PlatformProfileId];
+export declare function platformProfile(id: unknown): PlatformProfileId;
+/** A small bounded ASCII token, never whitespace/control characters or a header fragment. */
+export declare function requirePlatformKey(value: unknown): string;
+/** The concrete reader returns a valid key or rejects with a fixed error. */
+export declare function platformCredentialReader(env: Readonly<Record<string, unknown>>): {
+    get(name: ModelProviderSecretName): Promise<string>;
+};

package/dist/platform-provider.d.ts

@@ -0,0 +1,18 @@
+import { type PlatformCredentialReader } from './platform-credentials';
+export declare const PLATFORM_MAX_OUTPUT_TOKENS = 4096;
+export declare const REQUEST_FRAMING_BYTES = 4096;
+export interface CloudModelAccount {
+    sent(): void;
+    usage(usage: {
+        input?: number;
+        output?: number;
+    }): void;
+}
+export interface CloudModelRuntime {
+    beforeRequest(info: {
+        inputBytes: number;
+    }): void | CloudModelAccount | Promise<void | CloudModelAccount>;
+    admitToolCall(name: string, id: string, args: Record<string, unknown>): void | Promise<void>;
+    requestSignal?(signal?: AbortSignal): AbortSignal;
+}
+export declare function createPlatformModels(env: Readonly<Record<string, unknown>>, credentials?: PlatformCredentialReader, runtime?: CloudModelRuntime): import("@earendil-works/pi-ai").MutableModels;

package/dist/provider-fetch.d.ts

@@ -0,0 +1,11 @@
+import type { FetchFunction } from '@earendil-works/pi-ai';
+import { type PlatformProfile } from './platform-credentials';
+export interface CloudToolTransport {
+    readonly offeredToolNames: readonly string[];
+    admitToolCall(name: string, rawId: string, args: Record<string, unknown>): void | Promise<void>;
+    onSend?(): void;
+    onUsage?(usage: Record<string, number>): void;
+}
+export declare function readSseData(body: ReadableStream<Uint8Array>): AsyncGenerator<string>;
+/** Credential only in auth headers; never follow any redirect, even same origin. */
+export declare function createProviderFetch(profile: PlatformProfile, secret: string, fetchImpl?: FetchFunction, transport?: CloudToolTransport): FetchFunction;

package/dist/session-config.d.ts

@@ -0,0 +1,20 @@
+import type { CloudDispatchContext } from './tools';
+export interface CloudLimits {
+    readonly modelSteps: number;
+    readonly toolCalls: number;
+    readonly inlineFetches: number;
+    readonly callTimeoutMs: number;
+    readonly turnTimeoutMs: number;
+    readonly resultBytes: number;
+}
+export declare const CLOUD_LIMITS: Readonly<CloudLimits>;
+export declare const CLOUD_BUDGET: Readonly<{
+    credits: 100;
+    inputTokens: 128000;
+    outputTokens: 32768;
+}>;
+export interface CloudSessionConfig extends Omit<CloudDispatchContext, 'call' | 'lookup'> {
+    readonly limits: CloudLimits;
+}
+/** The consuming platform authorizes this data. It supplies the dispatcher in code. */
+export declare function admitSessionConfig(input: unknown): CloudSessionConfig;

package/dist/session-runtime.d.ts

@@ -0,0 +1,121 @@
+import { Harness, type AgentChange } from '@earendil-works/pi-durable';
+import { type CloudDoErrorCode } from './errors';
+import { type CloudOperationGuard } from './input-guard';
+import { CloudState, type RunRow } from './cloud-state';
+import { InvocationLedger, type InvocationRow, type InvocationTerminalState } from './invocation-ledger';
+import { type PlatformProfileId } from './platform-credentials';
+import { type CloudToolDispatcher } from './tools';
+export declare const CLOUD_HARNESS_SETTINGS: {
+    readonly compaction: {
+        readonly enabled: false;
+    };
+    readonly retry: {
+        readonly enabled: false;
+        readonly maxRetries: 0;
+    };
+    readonly stream: {
+        readonly maxRetries: 0;
+    };
+};
+export interface ExecutionLease {
+    conversationId?: number;
+    trigger?: 'submit' | 'wake';
+    readonly profile: PlatformProfileId;
+    readonly deadlineAt: number;
+    readonly controller: AbortController;
+    connected: boolean;
+    timer?: ReturnType<typeof setTimeout>;
+    guard?: CloudOperationGuard;
+    liveOwner: boolean;
+    settled: boolean;
+}
+export interface CloudRenewRequest {
+    nativeRunId: number;
+    requestId: string | null;
+    kind: 'model' | 'tool';
+    toolName?: string;
+    recovery: boolean;
+}
+export type CloudRenewResult = {
+    ok: true;
+} | {
+    ok: false;
+    code: CloudDoErrorCode;
+};
+export interface CloudRunSettlement {
+    nativeRunId: number;
+    requestId: string | null;
+    trigger: RunRow['trigger'];
+    state: 'completed' | 'failed' | 'interrupted';
+    errorCode: CloudDoErrorCode | null;
+    reservation: RunRow['reservation'];
+    admissionDigest: string | null;
+    admittedSeqs: readonly number[];
+    claimedSeqs: readonly number[];
+    usage: Readonly<{
+        steps: number;
+        sentRequests: number;
+        inputTokens: number;
+        outputTokens: number;
+        credits: number;
+    }>;
+}
+/** Bound consumer work even when it ignores the supplied signal. */
+export declare function raceLease<T>(work: Promise<T>, lease: ExecutionLease): Promise<T>;
+export interface RuntimeOptions {
+    createDispatcher(id: string): CloudToolDispatcher | undefined;
+    projectInvocation?(row: InvocationRow): {
+        key: string;
+        dataJson: string;
+    } | undefined;
+    onCommit?(): void;
+    onInvocationSettled?(id: string, state: InvocationTerminalState): void | Promise<void>;
+    instructions?(profile: PlatformProfileId): string | undefined;
+    renew?(request: CloudRenewRequest, signal: AbortSignal): CloudRenewResult | Promise<CloudRenewResult>;
+    settleRun?(run: CloudRunSettlement, signal: AbortSignal): void | Promise<void>;
+}
+export interface RunOutcome {
+    state: 'completed' | 'failed' | 'interrupted';
+    errorCode?: CloudDoErrorCode;
+    text?: string;
+    entryId?: number;
+    requeue?: boolean;
+}
+/** One physical DO owns this runtime. Native pi owns all model and task scheduling. */
+export declare class SessionRuntime {
+    #private;
+    private readonly state;
+    private readonly env;
+    private readonly options;
+    readonly ledger: InvocationLedger;
+    readonly cloud: CloudState;
+    constructor(state: DurableObjectState, env: Readonly<Record<string, unknown>>, options: RuntimeOptions);
+    get recovering(): boolean;
+    get activeLease(): ExecutionLease | undefined;
+    get hasLiveOwner(): boolean;
+    get busy(): boolean;
+    get repairRetrying(): boolean;
+    prepareGuard(profile?: PlatformProfileId): Promise<CloudOperationGuard>;
+    /** Binding/RPC callers authorize the session before calling this immutable configuration operation. */
+    configure(input: unknown): Promise<void>;
+    open(selected?: PlatformProfileId): Promise<Harness>;
+    ready(selected?: PlatformProfileId): Promise<Harness>;
+    agentChange(profile: PlatformProfileId, guard: CloudOperationGuard): AgentChange;
+    reserve(profile: PlatformProfileId, guard?: CloudOperationGuard): ExecutionLease;
+    attach(lease: ExecutionLease, conversationId: number, trigger?: 'submit' | 'wake', guard?: CloudOperationGuard | undefined): void;
+    cancel(lease: ExecutionLease, code?: CloudDoErrorCode): void;
+    release(lease: ExecutionLease, retryCount?: number): Promise<void>;
+    recordSubmission(conversationId: number, submissionId: number): void;
+    markReservation(conversationId: number, reservation: 'pending' | 'held' | 'none', admission?: {
+        digest: string;
+        seqs: number[];
+    }): void;
+    claimWake(lease: ExecutionLease, seqs: readonly number[], profile?: "deepseek_direct" | "zai_openai"): import("./cloud-state").InboxRow[];
+    settle(lease: ExecutionLease, outcome: RunOutcome): Promise<void>;
+    cancelActive(code?: CloudDoErrorCode): boolean;
+    /** Only an owner that exited may be repaired. A live provider run is never adjudicated here. */
+    repairPendingRuns(retryCount?: number): Promise<boolean>;
+    deliverSettlementsForAlarm(retryCount?: number, providedGuard?: CloudOperationGuard): Promise<void>;
+    fatal(conversationId: number): CloudDoErrorCode | undefined;
+    readInvocation(id: string): InvocationRow | undefined;
+}

package/dist/storage.d.ts

@@ -0,0 +1,21 @@
+import { type SqliteDatabase, type SqliteExecutor, type SqliteValue } from '@earendil-works/pi-durable/storage/sqlite';
+import type { Storage } from '@earendil-works/pi-durable';
+/** Construction returns pi's native Storage interface. */
+type DurableStorageFactory<Location> = (location: Location) => Promise<Storage>;
+/** One adapter per DO database: unrelated reads, writes, transactions and close share this queue. */
+export declare class DurableObjectSqliteDatabase implements SqliteDatabase {
+    private readonly storage;
+    private tail;
+    private closed;
+    constructor(storage: DurableObjectStorage);
+    private queued;
+    private executor;
+    exec(sql: string): Promise<void>;
+    run(sql: string, ...params: SqliteValue[]): Promise<void>;
+    get<T extends object>(sql: string, ...params: SqliteValue[]): Promise<T | undefined>;
+    all<T extends object>(sql: string, ...params: SqliteValue[]): Promise<T[]>;
+    transaction<T>(callback: (transaction: SqliteExecutor) => Promise<T>): Promise<T>;
+    close(): Promise<void>;
+}
+export declare const openDurableObjectStorage: DurableStorageFactory<DurableObjectStorage>;
+export {};

package/dist/tools.d.ts

@@ -0,0 +1,68 @@
+import type { JsonValue } from '@earendil-works/pi-ai';
+import type { ToolRegistration } from '@earendil-works/pi-durable';
+import { type CloudDoErrorCode } from './errors';
+import type { SessionIdentity } from './identity';
+export declare const CLOUD_SAFE_REPLAY_TOOLS: readonly ["load_financial_analysis_skill", "resolve_security", "guarded_screen", "search_f10_datasets", "query_f10_dataset", "get_security_profile", "get_quote_snapshot", "get_corporate_actions", "get_financial_statements", "get_financial_facts", "get_financial_ratios", "get_sdi_disclosures", "get_directorate", "get_ownership", "get_related_warrants"];
+export declare const CLOUD_LIVE_IPO_TOOLS: readonly ["get_ipo_profile", "search_ipo_calendar", "get_ipo_timetable", "get_ipo_offering", "get_ipo_allotment", "screen_ipos", "compare_ipos"];
+export interface CloudToolDefinition {
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: ToolRegistration['parameters'];
+    readonly execution: 'read_only_live' | 'skill' | 'scaffold' | 'pure';
+    readonly resolverRpc?: string;
+    readonly mode?: 'inline' | 'job';
+    readonly requiredCapabilities?: readonly string[];
+}
+export interface CloudDispatchContext {
+    readonly identity: SessionIdentity;
+    readonly principal: {
+        readonly accountId: string;
+        readonly workspaceId: string;
+        readonly channel: string;
+    };
+    readonly scopes: readonly string[];
+    readonly dispatcherId: string;
+    readonly call?: {
+        readonly invocationId: string;
+        readonly conversationId: number;
+        readonly toolCallId: string;
+        readonly attempt: number;
+    };
+    /** Session-local lookup can return a non-terminal invocation. */
+    readonly lookup?: (invocationId: string) => {
+        toolName: string;
+        state: string;
+        errorCode: string | null;
+        resultJson: string | null;
+        conversationId: number;
+        toolCallId: string;
+        settledAt: number | null;
+        settledEventSeq: number | null;
+    } | undefined;
+}
+/** Runtime calls supply these fields. Configuration remains source compatible. */
+export interface CloudToolCallContext extends CloudDispatchContext {
+    readonly call: NonNullable<CloudDispatchContext['call']>;
+    readonly lookup: NonNullable<CloudDispatchContext['lookup']>;
+}
+export type CloudToolResult = Record<string, unknown> & {
+    modelView?: JsonValue;
+};
+export interface CloudToolDispatcher {
+    readonly pureTools?: readonly string[];
+    readonly domainErrors?: readonly string[];
+    readonly modelViews?: boolean;
+    readonly tools: readonly CloudToolDefinition[];
+    execute(context: CloudDispatchContext, name: string, args: Record<string, unknown>, signal: AbortSignal): Promise<CloudToolResult>;
+}
+export declare const CLOUD_DOMAIN_ERROR_CODES: Readonly<Record<string, CloudDoErrorCode>>;
+/** Admission does not grant resolver access. The trusted dispatcher checks access at execution. */
+export declare function admitCloudTools(tools: readonly CloudToolDefinition[], pureTools?: readonly string[]): readonly CloudToolDefinition[];
+/** Copy policy values so consumer mutation cannot change an installed policy. */
+export declare function admitCloudDispatcher(dispatcher: CloudToolDispatcher): CloudToolDispatcher;
+export declare function dispatcherDigest(dispatcher: CloudToolDispatcher): Promise<string>;
+/** This policy is stored in the ledger only. Native pi registrations always use unsafe. */
+export declare function replayForTool(name: string): 'safe' | 'unsafe';
+export declare function canonicalArgs(args: Record<string, unknown>): string;
+export declare function invocationId(conversationId: number, assistantEntryId: number, toolCallId: string): Promise<string>;
+export declare function argsDigest(toolName: string, args: Record<string, unknown>): Promise<string>;

package/dist/wake-runner.d.ts

@@ -0,0 +1,16 @@
+import type { Conversation, Harness } from '@earendil-works/pi-durable';
+import { type AdmissionIdentity, type InboxRow, type RunHistory } from './cloud-state';
+import { type CloudDoErrorCode } from './errors';
+import { type RunOutcome, type SessionRuntime } from './session-runtime';
+export type CloudWakeAdmission = {
+    accepted: true;
+    reservation: 'held' | 'none';
+} | {
+    accepted: false;
+    code: CloudDoErrorCode;
+};
+export type WakeAdmission = (items: readonly InboxRow[], signal: AbortSignal, key: string, admission: AdmissionIdentity) => CloudWakeAdmission | Promise<CloudWakeAdmission>;
+export declare function cloudRunHistory(runtime: SessionRuntime, harness: Harness): Promise<RunHistory[]>;
+export declare function committedRunOutcome(conversation: Conversation, runtime: SessionRuntime, status: string, detail?: unknown): Promise<RunOutcome>;
+/** Each invocation of this function owns a fresh conversation and one shared runtime lease. */
+export declare function runCloudWake(runtime: SessionRuntime, harness: Harness, env: Readonly<Record<string, unknown>>, admit: WakeAdmission, notify: () => void, retryCount?: number): Promise<boolean>;

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@byok-sdk/cloud-do",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.24.0",
+  "type": "module",
+  "engines": {
+    "node": ">=24.15.0"
+  },
+  "description": "Cloudflare Durable Object session host for native pi-durable storage and execution",
+  "scripts": {
+    "build": "tsup && tsc -p tsconfig.build.json && node scripts/check-dist.mjs && wrangler deploy --dry-run --outdir dist-worker",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run && node --test test/recovery-walltime.node.mjs test/wake-alarm-retry.node.mjs test/wake-events-walltime.node.mjs test/check-dist.node.mjs"
+  },
+  "dependencies": {
+    "@earendil-works/pi-durable": "1.0.4",
+    "@earendil-works/pi-ai": "1.0.4",
+    "@earendil-works/chord": "1.0.4"
+  },
+  "devDependencies": {
+    "@byok-sdk/keys": "0.9.0",
+    "@cloudflare/workers-types": "5.20260811.1",
+    "miniflare": "5.20260811.1-alpha",
+    "esbuild": "0.28.1",
+    "wrangler": "4.123.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ancienttwo/byok-sdk.git",
+    "directory": "packages/cloud-do"
+  },
+  "bugs": {
+    "url": "https://github.com/Ancienttwo/byok-sdk/issues"
+  },
+  "homepage": "https://github.com/Ancienttwo/byok-sdk#readme",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}