@ixo/oracle-runtime-workers 0.2.0

package/src/owner-store/tus-upload.ts

@@ -0,0 +1,333 @@
+/**
+ * Minimal tus 1.0.0 client (creation + resume) for the IXO VFS
+ * (`/api/fs/upload`, see the VFS repo's RESUMABLE_UPLOADS.md).
+ *
+ * Reads `source()` part by part — never more than one `partSize` buffer in
+ * memory — and PATCHes each part at its offset. A failed part is retried
+ * with backoff after probing `HEAD` for the committed offset, so a part the
+ * server did take (response lost) is not sent twice and a part it did not
+ * take is resent from the same buffer. The VFS does not support
+ * `Upload-Defer-Length`, so the caller must know `totalLength` up front (the
+ * owner store measures it with a counting pass over the same source).
+ *
+ * Part rules enforced by the server: every non-final part must be a
+ * multiple of 64 KiB and at least 5 MiB; a single part covering the whole
+ * upload has no alignment demands. Every request carries fresh auth
+ * headers from `authHeaders()` (single-use UCAN invocations).
+ */
+import { DEFAULT_RETRY_DELAYS_MS, isNetworkError } from './retry';
+
+export const TUS_VERSION = '1.0.0';
+export const TUS_PART_ALIGN_BYTES = 64 * 1024;
+export const TUS_MIN_PART_BYTES = 5 * 1024 * 1024;
+
+/** Statuses after which resending the same part can never succeed. */
+const FATAL_STATUSES = new Set([400, 401, 403, 404, 410, 411, 412, 413, 415]);
+
+export class TusUploadError extends Error {
+  constructor(
+    message: string,
+    readonly status: number | undefined,
+    readonly retryable: boolean,
+  ) {
+    super(message);
+    this.name = 'TusUploadError';
+  }
+}
+
+export interface TusUploadOptions {
+  /** Creation endpoint, e.g. `https://vfs/api/fs/upload`. */
+  endpoint: string;
+  path: string;
+  contentType: string;
+  totalLength: number;
+  partSize: number;
+  /** Re-openable byte source; read exactly once per upload attempt. */
+  source: () => ReadableStream<Uint8Array>;
+  /** Fresh auth headers for every request. */
+  authHeaders: () => Promise<Record<string, string>>;
+  fetchImpl: typeof fetch;
+  /** Per-request timeout (headers + body for parts). */
+  timeoutMs?: number;
+  retryDelaysMs?: readonly number[];
+  sleep?: (ms: number) => Promise<void>;
+  log?: (message: string) => void;
+}
+
+export interface TusUploadResult {
+  /** Null when the final PATCH was committed but its response was lost. */
+  fileId: string | null;
+  contentHash: string | null;
+  cid: string | null;
+  parts: number;
+}
+
+function base64(text: string): string {
+  const bytes = new TextEncoder().encode(text);
+  let binary = '';
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+
+export function uploadMetadata(fields: Record<string, string>): string {
+  return Object.entries(fields)
+    .map(([key, value]) => `${key} ${base64(value)}`)
+    .join(',');
+}
+
+/** Reads fixed-size parts from a stream; the last one may be shorter. */
+class PartReader {
+  private readonly reader: ReadableStreamDefaultReader<Uint8Array>;
+  private carry: Uint8Array | null = null;
+  private ended = false;
+
+  constructor(
+    stream: ReadableStream<Uint8Array>,
+    private readonly partSize: number,
+  ) {
+    this.reader = stream.getReader();
+  }
+
+  /** Next part, or null at end of stream. */
+  async next(): Promise<Uint8Array | null> {
+    if (this.ended && this.carry === null) return null;
+    const out = new Uint8Array(this.partSize);
+    let fill = 0;
+    while (fill < this.partSize) {
+      let chunk: Uint8Array;
+      if (this.carry !== null) {
+        chunk = this.carry;
+        this.carry = null;
+      } else if (this.ended) {
+        break;
+      } else {
+        const { done, value } = await this.reader.read();
+        if (done) {
+          this.ended = true;
+          break;
+        }
+        chunk = value;
+      }
+      const n = Math.min(chunk.byteLength, this.partSize - fill);
+      out.set(chunk.subarray(0, n), fill);
+      fill += n;
+      if (n < chunk.byteLength) this.carry = chunk.subarray(n);
+    }
+    if (fill === 0) return null;
+    return fill === this.partSize ? out : out.subarray(0, fill);
+  }
+
+  release(): void {
+    this.reader.releaseLock();
+  }
+}
+
+export async function tusUpload(
+  options: TusUploadOptions,
+): Promise<TusUploadResult> {
+  const {
+    totalLength,
+    partSize,
+    fetchImpl,
+    authHeaders,
+    timeoutMs = 120_000,
+  } = options;
+  const delays = options.retryDelaysMs ?? DEFAULT_RETRY_DELAYS_MS;
+  const sleep =
+    options.sleep ??
+    ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+  const log = options.log ?? (() => undefined);
+  if (totalLength < 1)
+    throw new TusUploadError('tus: totalLength must be ≥ 1', undefined, false);
+  if (
+    totalLength > partSize &&
+    (partSize < TUS_MIN_PART_BYTES || partSize % TUS_PART_ALIGN_BYTES !== 0)
+  ) {
+    throw new TusUploadError(
+      `tus: partSize ${partSize} must be a multiple of ${TUS_PART_ALIGN_BYTES} and ≥ ${TUS_MIN_PART_BYTES}`,
+      undefined,
+      false,
+    );
+  }
+
+  const request = async (
+    method: string,
+    url: string,
+    headers: Record<string, string>,
+    body?: Uint8Array,
+  ): Promise<Response> => {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      return await fetchImpl(url, {
+        method,
+        headers: {
+          ...(await authHeaders()),
+          'Tus-Resumable': TUS_VERSION,
+          ...headers,
+        },
+        body,
+        signal: controller.signal,
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+  };
+
+  const failure = async (
+    what: string,
+    res: Response,
+  ): Promise<TusUploadError> => {
+    const text = await res.text().catch(() => '');
+    return new TusUploadError(
+      `tus: ${what} → ${res.status} ${text.slice(0, 200)}`,
+      res.status,
+      !FATAL_STATUSES.has(res.status),
+    );
+  };
+
+  // ── creation ──────────────────────────────────────────────────────────
+  let sessionUrl: string | null = null;
+  for (let attempt = 0; sessionUrl === null; attempt++) {
+    try {
+      const res = await request('POST', options.endpoint, {
+        'Upload-Length': String(totalLength),
+        'Upload-Metadata': uploadMetadata({
+          path: options.path,
+          contentType: options.contentType,
+        }),
+      });
+      if (res.status !== 201) throw await failure('create', res);
+      const location = res.headers.get('location');
+      if (!location)
+        throw new TusUploadError(
+          'tus: create answered without Location',
+          201,
+          false,
+        );
+      sessionUrl = new URL(location, options.endpoint).toString();
+    } catch (error) {
+      const delay = delays[attempt];
+      if (delay === undefined || !isRetryable(error)) throw error;
+      log(`tus: create failed (${describe(error)}) — retry in ${delay} ms`);
+      await sleep(delay);
+    }
+  }
+
+  // ── parts ─────────────────────────────────────────────────────────────
+  const parts = new PartReader(options.source(), partSize);
+  let offset = 0;
+  let count = 0;
+  const result: TusUploadResult = {
+    fileId: null,
+    contentHash: null,
+    cid: null,
+    parts: 0,
+  };
+  const abortSession = async (): Promise<void> => {
+    try {
+      await request('DELETE', sessionUrl, {});
+    } catch {
+      // Best effort: R2's incomplete-multipart rule cleans up eventually.
+    }
+  };
+  try {
+    for (;;) {
+      const part = await parts.next();
+      if (part === null) break;
+      if (offset + part.byteLength > totalLength) {
+        throw new TusUploadError(
+          `tus: source produced more than the declared ${totalLength} bytes`,
+          undefined,
+          false,
+        );
+      }
+      count += 1;
+      const final = offset + part.byteLength === totalLength;
+      let sent = false;
+      for (let attempt = 0; !sent; attempt++) {
+        try {
+          const res = await request(
+            'PATCH',
+            sessionUrl,
+            {
+              'Upload-Offset': String(offset),
+              'Content-Type': 'application/offset+octet-stream',
+            },
+            part,
+          );
+          if (!res.ok) throw await failure(`part ${count} @${offset}`, res);
+          if (final) {
+            result.fileId = res.headers.get('x-vfs-file-id');
+            result.contentHash = res.headers.get('x-vfs-content-hash');
+            result.cid = res.headers.get('x-vfs-cid');
+          }
+          sent = true;
+        } catch (error) {
+          const delay = delays[attempt];
+          if (delay === undefined || !isRetryable(error)) throw error;
+          log(
+            `tus: part ${count} @${offset} failed (${describe(error)}) — probing offset, retry in ${delay} ms`,
+          );
+          await sleep(delay);
+          const committed = await committedOffset(request, sessionUrl);
+          if (committed === offset + part.byteLength) {
+            // The server took it; only the response was lost. For the final
+            // part the session is gone with it — the caller resolves the
+            // file by path.
+            sent = true;
+          } else if (committed !== null && committed !== offset) {
+            throw new TusUploadError(
+              `tus: committed offset ${committed} does not match our ${offset}; the session cannot be resumed`,
+              undefined,
+              false,
+            );
+          }
+        }
+      }
+      offset += part.byteLength;
+    }
+    if (offset !== totalLength) {
+      throw new TusUploadError(
+        `tus: source produced ${offset} bytes but ${totalLength} were declared`,
+        undefined,
+        false,
+      );
+    }
+  } catch (error) {
+    await abortSession();
+    throw error;
+  } finally {
+    parts.release();
+  }
+  result.parts = count;
+  return result;
+}
+
+/** `HEAD` the session; null when the probe itself failed or the session is gone. */
+async function committedOffset(
+  request: (
+    method: string,
+    url: string,
+    headers: Record<string, string>,
+  ) => Promise<Response>,
+  sessionUrl: string,
+): Promise<number | null> {
+  try {
+    const res = await request('HEAD', sessionUrl, {});
+    if (!res.ok) return null;
+    const value = res.headers.get('upload-offset');
+    return value === null ? null : Number(value);
+  } catch {
+    return null;
+  }
+}
+
+function isRetryable(error: unknown): boolean {
+  if (error instanceof TusUploadError) return error.retryable;
+  return isNetworkError(error);
+}
+
+function describe(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/plugin-api/define-plugin.ts

@@ -0,0 +1,45 @@
+import type { OraclePlugin } from './oracle-plugin';
+
+/**
+ * Input shape accepted by `defineOraclePlugin`. The three identity fields
+ * (`name`, `version`, `manifest`) are required; every other plugin method
+ * is optional.
+ */
+export type DefineOraclePluginInput = Partial<OraclePlugin> &
+  Pick<OraclePlugin, 'name' | 'version' | 'manifest'>;
+
+/**
+ * Identity-style helper for authoring a plugin as a plain object.
+ *
+ * Returns the same object the caller passed in, narrowed to `OraclePlugin`
+ * so type errors surface at the authoring site. The runtime treats the
+ * resulting POJO interchangeably with a class instance extending
+ * `OraclePlugin`.
+ *
+ * @throws TypeError when `name`, `version`, or `manifest` is missing.
+ */
+export function defineOraclePlugin(
+  spec: DefineOraclePluginInput,
+): OraclePlugin {
+  if (!spec || typeof spec !== 'object') {
+    throw new TypeError(
+      'defineOraclePlugin(spec): `spec` must be a plugin definition object.',
+    );
+  }
+  if (!spec.name || typeof spec.name !== 'string') {
+    throw new TypeError(
+      'defineOraclePlugin(spec): `name` is required and must be a non-empty string.',
+    );
+  }
+  if (!spec.version || typeof spec.version !== 'string') {
+    throw new TypeError(
+      'defineOraclePlugin(spec): `version` is required and must be a non-empty string.',
+    );
+  }
+  if (!spec.manifest || typeof spec.manifest !== 'object') {
+    throw new TypeError(
+      'defineOraclePlugin(spec): `manifest` is required and must be an object.',
+    );
+  }
+  return spec;
+}

package/src/plugin-api/index.ts

@@ -0,0 +1,56 @@
+/**
+ * Plugin authoring surface. A plugin written against `@ixo/oracle-runtime`
+ * that uses tools / sub-agents / middlewares / manifest / configSchema /
+ * autoDetect / getSharedState compiles unchanged against this module; the
+ * only Node-specific hook (`getNestModules`) is replaced by `getRoutes`.
+ */
+export { OraclePlugin } from './oracle-plugin';
+export type {
+  PluginEnv,
+  PluginRoute,
+  PluginRouteMethod,
+} from './oracle-plugin';
+export { defineOraclePlugin } from './define-plugin';
+export type { DefineOraclePluginInput } from './define-plugin';
+export { tool } from './tool-helper';
+export type { ToolHelperOptions } from './tool-helper';
+export { UcanMintUnavailableError } from './ucan-errors';
+export type {
+  ActionCallEventPayload,
+  AgentMiddleware,
+  AuthExcludedRoute,
+  BrowserToolCallEventPayload,
+  ChatOpenAIFields,
+  CommerceContext,
+  CommerceEngagement,
+  CommerceEngagementStatus,
+  CommerceGateFailure,
+  CommerceGateFailureReason,
+  CommerceInProgressEngagement,
+  CommerceMode,
+  CommercePaymentOutcome,
+  Logger,
+  ManifestExample,
+  MatrixEvent,
+  MergedConfig,
+  MessageCacheInvalidationPayload,
+  ModelRole,
+  OracleConfig,
+  OracleIdentity,
+  OraclePromptConfig,
+  PluginContext,
+  PluginManifest,
+  PluginSubAgent,
+  PluginTool,
+  ReadonlyState,
+  ReasoningEventPayload,
+  RenderComponentEventPayload,
+  RoomStateSnapshot,
+  RouterEventPayload,
+  RuntimeContext,
+  SecretIndex,
+  SharedAccessors,
+  ToolCallEventPayload,
+  UcanDelegation,
+  UserContextData,
+} from './types';

package/src/plugin-api/oracle-plugin.ts

@@ -0,0 +1,145 @@
+import type { z } from 'zod';
+import type { PluginRoute } from '../shell/app';
+import type {
+  AgentMiddleware,
+  AuthExcludedRoute,
+  PluginContext,
+  PluginManifest,
+  PluginSubAgent,
+  PluginTool,
+  RuntimeContext,
+} from './types';
+
+/**
+ * The environment the plugin loader hands to `autoDetect`. On Workers this
+ * is the `env` bindings object (secrets, vars, and — for keys a plugin never
+ * reads — Durable Object namespaces), never `process.env`. Values are typed
+ * `unknown` because bindings are not all strings; a plugin checking for a
+ * secret should test `typeof env.MY_KEY === 'string' && env.MY_KEY.length > 0`.
+ */
+export type PluginEnv = Record<string, unknown>;
+
+/**
+ * A route contributed by a plugin — `{ method, path, handler(request, env) }`,
+ * the exact shape the Hono shell mounts (`src/shell/app.ts` owns the type).
+ * `path` is mounted as given (leading slash optional) with the shell's router
+ * syntax, so `:param` segments work. Routes are auth-locked unless the same
+ * plugin lists them in `getAuthExcludedRoutes()`.
+ */
+export type { PluginRoute };
+
+/** HTTP methods a plugin route can be mounted on. */
+export type PluginRouteMethod = PluginRoute['method'];
+
+/**
+ * Base class every plugin implements. Identical to the Node runtime's contract
+ * except for two Workers-driven changes:
+ *
+ *  - `autoDetect` receives the Worker `env` bindings object (`PluginEnv`)
+ *    rather than `NodeJS.ProcessEnv`. A Node plugin whose predicate only reads
+ *    string keys compiles unchanged (method parameters are bivariant).
+ *  - `getNestModules` is replaced by `getRoutes`, which returns plain
+ *    `{ method, path, handler }` records the Hono shell mounts. There is no
+ *    dependency-injection container on Workers; plugins that need long-lived
+ *    state hold it on the instance (the instance lives as long as the isolate).
+ */
+export abstract class OraclePlugin {
+  /** Unique plugin identifier (kebab-case by convention). */
+  abstract readonly name: string;
+
+  /** Plugin version. */
+  abstract readonly version: string;
+
+  /** The agent's structured interface to this plugin. */
+  abstract readonly manifest: PluginManifest;
+
+  /** Hard dependencies — boot fails if any is missing. */
+  readonly dependsOn?: string[];
+
+  /** Soft dependencies — plugin loads either way; branches on availability. */
+  readonly softDependsOn?: string[];
+
+  /** Plugin-owned env vars. Merged into the runtime's Zod schema at boot. */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  readonly configSchema?: z.ZodObject<any>;
+
+  /**
+   * Predicate the loader runs against the Worker `env` bindings when the
+   * plugin is left at `'auto'` (or has no explicit toggle). Returning `false`
+   * skips the plugin. Plugins without an `autoDetect` are on-by-default.
+   */
+  autoDetect?(env: PluginEnv): boolean;
+
+  /**
+   * Human-readable description of what `autoDetect` checks (e.g. the env
+   * var name). Surfaced in boot-error messages so operators see exactly
+   * why the plugin was skipped.
+   */
+  readonly autoDetectHint?: string;
+
+  /** Tools the main agent can call. Called once per isolate (boot-cached). */
+  getTools?(ctx: PluginContext): PluginTool[] | Promise<PluginTool[]>;
+
+  /** Sub-agents the runtime auto-wraps as tools. */
+  getSubAgents?(ctx: PluginContext): PluginSubAgent[];
+
+  /**
+   * Request-time tool contributions. Called once per `createMainAgent`
+   * invocation with the full per-request `RuntimeContext`, so the plugin
+   * can decide which tools to expose based on live state (e.g. AG-UI
+   * actions in `state.agActions`).
+   *
+   * Results are merged with `getTools(ctx)` — both can fire on the same
+   * build. Plugins should pick whichever hook fits: boot-time when only
+   * config/identity matters; request-time when state/user/session matters.
+   */
+  getRequestTools?(rtCtx: RuntimeContext): PluginTool[] | Promise<PluginTool[]>;
+
+  /**
+   * Request-time sub-agent contributions. Same merge semantics as
+   * `getRequestTools` — boot-time `getSubAgents` and request-time
+   * `getRequestSubAgents` outputs are both collected.
+   */
+  getRequestSubAgents?(
+    rtCtx: RuntimeContext,
+  ): PluginSubAgent[] | Promise<PluginSubAgent[]>;
+
+  /**
+   * LangChain middlewares inserted after the runtime's always-on middlewares
+   * (summarization, capability gate, tool validation, repetition guard, retry).
+   */
+  getMiddlewares?(ctx: PluginContext): AgentMiddleware[];
+
+  /**
+   * Read-only accessors this plugin exposes to other plugins via `ctx.shared`.
+   * Pattern: this plugin computes/owns some derived value from state; others
+   * read it.
+   */
+  getSharedState?(): Record<
+    string,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (state: any, runCtx: RuntimeContext) => unknown
+  >;
+
+  /**
+   * HTTP routes the plugin contributes. The Hono shell mounts every returned
+   * route under the Worker's root; handlers receive the raw `Request` and the
+   * Worker `env`. Use for webhooks, public probes, or plugin-owned REST
+   * endpoints. Replaces the Node runtime's `getNestModules`.
+   *
+   * `ctx` carries the validated merged config + identity + logger so handlers
+   * can close over config without reading `env` themselves.
+   */
+  getRoutes?(ctx: PluginContext): PluginRoute[];
+
+  /**
+   * Routes owned by this plugin's `getRoutes()` that MUST NOT pass through
+   * the shell's UCAN auth middleware. Use for webhooks, OAuth callbacks,
+   * public probes — anything that doesn't authenticate via UCAN. Returning an
+   * empty array (or omitting the method) keeps every plugin route auth-locked.
+   *
+   * The returned `path` is matched against the request URL with the leading
+   * slash optional and should be the full mounted path (e.g. `weather/now`).
+   */
+  getAuthExcludedRoutes?(): AuthExcludedRoute[];
+}

package/src/plugin-api/tool-helper.ts

@@ -0,0 +1,82 @@
+import type { z } from 'zod';
+import type { PluginTool, RuntimeContext } from './types';
+
+/**
+ * Authoring options for `tool()`. Mirrors the public surface of `PluginTool`
+ * minus the handler (which is the first positional argument).
+ */
+export interface ToolHelperOptions {
+  /** Tool name shown to the agent. Must be unique within the plugin. */
+  name: string;
+  /** Tool description shown to the agent. */
+  description: string;
+  /** Zod schema validating the tool's input arguments. */
+  schema: z.ZodType;
+  /**
+   * Override visibility — by default the tool inherits the plugin's
+   * `manifest.visibility` setting.
+   */
+  visibility?: PluginTool['visibility'];
+  /**
+   * Billing gate marker, kept for source compatibility with the Node
+   * runtime's plugin contract. The Workers runtime has no commerce lane, so
+   * the marker is carried on the `PluginTool` but never gates binding.
+   */
+  billing?: PluginTool['billing'];
+}
+
+/**
+ * User-facing helper to author a plugin tool.
+ *
+ * The handler receives the validated arguments and a `RuntimeContext` built
+ * fresh per invocation. The runtime is responsible for bridging LangChain's
+ * `(args, runConfig)` calling convention into `(args, ctx)` when it wires
+ * the tool into the agent.
+ *
+ * @param handler - Async function invoked when the agent calls the tool.
+ * @param options - Tool descriptor (name, description, schema, optional visibility).
+ * @returns A `PluginTool` consumable by the runtime's tool registration step.
+ */
+export function tool(
+  handler: (args: unknown, ctx: RuntimeContext) => Promise<unknown>,
+  options: ToolHelperOptions,
+): PluginTool {
+  if (typeof handler !== 'function') {
+    throw new TypeError(
+      'tool(handler, options): `handler` must be a function.',
+    );
+  }
+  if (!options || typeof options !== 'object') {
+    throw new TypeError('tool(handler, options): `options` is required.');
+  }
+  const { name, description, schema, visibility, billing } = options;
+  if (!name || typeof name !== 'string') {
+    throw new TypeError(
+      'tool(handler, options): `options.name` must be a non-empty string.',
+    );
+  }
+  if (!description || typeof description !== 'string') {
+    throw new TypeError(
+      'tool(handler, options): `options.description` must be a non-empty string.',
+    );
+  }
+  if (!schema) {
+    throw new TypeError(
+      'tool(handler, options): `options.schema` (Zod schema) is required.',
+    );
+  }
+
+  const pluginTool: PluginTool = {
+    name,
+    description,
+    schema,
+    handler,
+  };
+  if (visibility !== undefined) {
+    pluginTool.visibility = visibility;
+  }
+  if (billing !== undefined) {
+    pluginTool.billing = billing;
+  }
+  return pluginTool;
+}