@ixo/oracle-runtime-workers 0.13.0 → 0.15.0

package/src/artifacts/store.ts

@@ -0,0 +1,238 @@
+/**
+ * Artefacts: long chat output kept as a document the user opens in a browser.
+ *
+ * The canonical copy is a row in the user's own SQLite, so it travels with
+ * the working copy into the user's VFS file like the rest of their history.
+ * The share copy is ciphertext in R2 under `art/<id>`, expiring with the
+ * link; the key lives in the row and in the link's fragment. Creation is
+ * idempotent per id, which is what lets a recovered run rebuild its reply
+ * without minting a second document.
+ */
+import type { DoSqliteDatabase } from '../sqlite/database';
+import type { ArtifactRef } from '../delivery/types';
+import { artifactLink, type ArtifactStorageConfig } from './config';
+import { newShareKey, sealArtifact } from './crypto';
+
+export const ARTIFACT_ID_RE = /^[0-9a-f]{32}$/;
+
+/** Every share copy lives under this R2 prefix, and nothing else does. */
+export const ARTIFACT_OBJECT_PREFIX = 'art/';
+
+export function artifactObjectKey(artifactId: string): string {
+  return `${ARTIFACT_OBJECT_PREFIX}${artifactId}`;
+}
+
+/** A stable id for (run, source): the tool call id, or a spill's step key. */
+export async function artifactIdFor(
+  runId: string,
+  source: string,
+): Promise<string> {
+  const digest = await crypto.subtle.digest(
+    'SHA-256',
+    new TextEncoder().encode(`artifact\0${runId}\0${source}`),
+  );
+  return Array.from(new Uint8Array(digest).slice(0, 16), (b) =>
+    b.toString(16).padStart(2, '0'),
+  ).join('');
+}
+
+type ArtifactRow = {
+  artifact_id: string;
+  session_id: string;
+  title: string;
+  content: string;
+  bytes: number;
+  share_key: string;
+  created_at: string;
+  expires_at: string;
+  uploaded: number;
+  revoked_at: string | null;
+} & Record<string, string | number | null>;
+
+export interface StoredArtifact {
+  /** `url` is absent while no public origin is configured. */
+  ref: Omit<ArtifactRef, 'url'> & { url?: string };
+  sessionId: string;
+  content: string;
+  createdAt: string;
+  revoked: boolean;
+}
+
+/** An artefact as its owner reads it: `url` only while the link works. */
+export interface OwnedArtifact extends Omit<ArtifactRef, 'url'> {
+  url?: string;
+  sessionId: string;
+  createdAt: string;
+  revoked: boolean;
+  content: string;
+}
+
+export class ArtifactStore {
+  private setupPromise: Promise<void> | undefined;
+
+  constructor(
+    private readonly db: DoSqliteDatabase,
+    private readonly config: ArtifactStorageConfig,
+    private readonly now: () => number = () => Date.now(),
+  ) {}
+
+  /** Whether new artefacts can be created: a public origin for their links is set. */
+  get canShare(): boolean {
+    return this.config.links !== null;
+  }
+
+  setup(): Promise<void> {
+    this.setupPromise ??= this.db
+      .run(
+        `CREATE TABLE IF NOT EXISTS artifacts (
+          artifact_id TEXT PRIMARY KEY,
+          session_id TEXT NOT NULL,
+          run_id TEXT NOT NULL,
+          title TEXT NOT NULL,
+          mime TEXT NOT NULL,
+          content TEXT NOT NULL,
+          bytes INTEGER NOT NULL,
+          share_key TEXT NOT NULL,
+          created_at TEXT NOT NULL,
+          expires_at TEXT NOT NULL,
+          uploaded INTEGER NOT NULL DEFAULT 0,
+          revoked_at TEXT
+        )`,
+      )
+      .then(() => undefined)
+      .catch((error: unknown) => {
+        this.setupPromise = undefined;
+        throw error;
+      });
+    return this.setupPromise;
+  }
+
+  private refOf(row: ArtifactRow): StoredArtifact['ref'] {
+    const links = this.config.links;
+    return {
+      artifactId: row.artifact_id,
+      title: row.title,
+      ...(links
+        ? { url: artifactLink(links, row.artifact_id, row.share_key) }
+        : {}),
+      mime: 'text/markdown',
+      bytes: Number(row.bytes),
+      expiresAt: row.expires_at,
+    };
+  }
+
+  private row(artifactId: string): Promise<ArtifactRow | undefined> {
+    return this.db.get<ArtifactRow>(
+      `SELECT artifact_id, session_id, title, content, bytes, share_key,
+        created_at, expires_at, uploaded, revoked_at
+       FROM artifacts WHERE artifact_id = ?`,
+      [artifactId],
+    );
+  }
+
+  /** Create (or return the existing) artefact and make sure its share copy exists. */
+  async create(input: {
+    artifactId: string;
+    sessionId: string;
+    runId: string;
+    title: string;
+    content: string;
+  }): Promise<ArtifactRef> {
+    const links = this.config.links;
+    if (!links)
+      throw new Error(
+        'artifacts: no public origin (ORACLE_PUBLIC_URL) for share links',
+      );
+    await this.setup();
+    const createdAt = new Date(this.now());
+    await this.db.run(
+      `INSERT OR IGNORE INTO artifacts (artifact_id, session_id, run_id, title,
+        mime, content, bytes, share_key, created_at, expires_at)
+       VALUES (?, ?, ?, ?, 'text/markdown', ?, ?, ?, ?, ?)`,
+      [
+        input.artifactId,
+        input.sessionId,
+        input.runId,
+        input.title,
+        input.content,
+        new TextEncoder().encode(input.content).byteLength,
+        newShareKey(),
+        createdAt.toISOString(),
+        new Date(createdAt.getTime() + this.config.ttlMs).toISOString(),
+      ],
+    );
+    const row = await this.row(input.artifactId);
+    if (!row) throw new Error(`artifacts: ${input.artifactId} was not stored`);
+    if (!Number(row.uploaded) && !row.revoked_at) {
+      await this.config.bucket.put(
+        artifactObjectKey(row.artifact_id),
+        await sealArtifact(row.share_key, {
+          v: 1,
+          title: row.title,
+          mime: 'text/markdown',
+          content: row.content,
+          createdAt: row.created_at,
+        }),
+        {
+          httpMetadata: { contentType: 'application/octet-stream' },
+          customMetadata: { expiresAt: row.expires_at },
+        },
+      );
+      await this.db.run(
+        'UPDATE artifacts SET uploaded = 1 WHERE artifact_id = ?',
+        [row.artifact_id],
+      );
+    }
+    return {
+      ...this.refOf(row),
+      url: artifactLink(links, row.artifact_id, row.share_key),
+    };
+  }
+
+  async get(artifactId: string): Promise<StoredArtifact | undefined> {
+    await this.setup();
+    const row = await this.row(artifactId);
+    if (!row) return undefined;
+    return {
+      ref: this.refOf(row),
+      sessionId: row.session_id,
+      content: row.content,
+      createdAt: row.created_at,
+      revoked: row.revoked_at !== null,
+    };
+  }
+
+  /** Delete the share copy; the canonical copy stays with the user. */
+  async revoke(artifactId: string): Promise<boolean> {
+    await this.setup();
+    const row = await this.row(artifactId);
+    if (!row) return false;
+    await this.config.bucket.delete(artifactObjectKey(artifactId));
+    if (!row.revoked_at)
+      await this.db.run(
+        'UPDATE artifacts SET revoked_at = ? WHERE artifact_id = ?',
+        [new Date(this.now()).toISOString(), artifactId],
+      );
+    return true;
+  }
+
+  /**
+   * A deleted session takes its artefacts with it: the share copies first,
+   * so a failed delete keeps the rows (and the links still expire on time).
+   */
+  async deleteForSession(sessionId: string): Promise<number> {
+    await this.setup();
+    const rows = await this.db.exec<{ artifact_id: string }>(
+      'SELECT artifact_id FROM artifacts WHERE session_id = ?',
+      [sessionId],
+    );
+    if (rows.length === 0) return 0;
+    await this.config.bucket.delete(
+      rows.map((row) => artifactObjectKey(row.artifact_id)),
+    );
+    await this.db.run('DELETE FROM artifacts WHERE session_id = ?', [
+      sessionId,
+    ]);
+    return rows.length;
+  }
+}

package/src/artifacts/sweep.ts

@@ -0,0 +1,200 @@
+/**
+ * Removes expired artefact share copies from R2 on the cron tick.
+ *
+ * The data route deletes an expired copy only when someone opens it, so a
+ * copy nobody opens again would stay in the bucket for good. This sweep lists
+ * `art/` with each object's custom metadata (no per-object read) and deletes
+ * the ones whose `expiresAt` has passed.
+ *
+ * Cost per tick is kept to one state read while the last full sweep is
+ * recent. A sweep lists at most `maxPages` pages per tick; a larger bucket is
+ * finished over the next ticks from the stored cursor. The state object lives
+ * outside `art/`, so an operator's lifecycle rule on that prefix never removes
+ * it.
+ *
+ * Two overlapping runs need no lock: the second one only re-deletes keys the
+ * first already deleted (a no-op) and writes the same kind of state.
+ */
+import { z } from 'zod';
+import type { Logger } from '../plugin-api/types';
+import { ARTIFACT_OBJECT_PREFIX } from './store';
+
+export const ARTIFACT_SWEEP_STATE_KEY = 'artifact-sweep/state';
+
+/** R2's own ceiling for one `list` page and for one multi-key `delete`. */
+const R2_MAX_BATCH = 1000;
+const DEFAULT_SWEEP_MAX_PAGES = 20;
+
+const sweepStateSchema = z.object({
+  v: z.literal(1),
+  sweptAt: z.string().nullable(),
+  cursor: z.string().nullable(),
+});
+
+export type ArtifactSweepState = z.infer<typeof sweepStateSchema>;
+
+const NEVER_SWEPT: ArtifactSweepState = { v: 1, sweptAt: null, cursor: null };
+
+export interface SweepStats {
+  pages: number;
+  seen: number;
+  deleted: number;
+  /** Objects without a readable `expiresAt`: left alone. */
+  unknown: number;
+  /** The call continued a sweep an earlier tick left unfinished. */
+  resumed: boolean;
+  elapsedMs: number;
+}
+
+export type SweepOutcome =
+  | { skipped: true }
+  | ({ skipped: false; done: boolean } & SweepStats)
+  | ({ skipped: false; error: string } & SweepStats);
+
+export interface SweepOptions {
+  bucket: R2Bucket;
+  /** Clock for the expiry comparison and `sweptAt` (default `Date.now()`). */
+  now?: number;
+  /** A full sweep starts at most this often; an unfinished one resumes on every call. */
+  intervalMs: number;
+  /** Objects per `list` call (default and maximum 1000). */
+  pageSize?: number;
+  /** `list` calls per invocation (default 20). */
+  maxPages?: number;
+  /** Keys per `delete` call (default and maximum 1000). */
+  deleteBatchSize?: number;
+  log: Pick<Logger, 'log' | 'error'>;
+}
+
+function clampBatch(value: number | undefined, fallback: number): number {
+  if (value === undefined || !Number.isInteger(value) || value < 1)
+    return fallback;
+  return Math.min(value, R2_MAX_BATCH);
+}
+
+/** A missing, unreadable or unknown-version state counts as "never swept". */
+async function readState(bucket: R2Bucket): Promise<ArtifactSweepState> {
+  const object = await bucket.get(ARTIFACT_SWEEP_STATE_KEY);
+  if (!object) return NEVER_SWEPT;
+  const text = await object.text();
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text);
+  } catch {
+    return NEVER_SWEPT;
+  }
+  const parsed = sweepStateSchema.safeParse(raw);
+  return parsed.success ? parsed.data : NEVER_SWEPT;
+}
+
+function isExpired(
+  expiresAt: string | undefined,
+  now: number,
+): boolean | undefined {
+  const at = Date.parse(expiresAt ?? '');
+  return Number.isFinite(at) ? at <= now : undefined;
+}
+
+/** Never throws: an R2 failure is logged once and returned as `error`. */
+export async function sweepExpiredArtifacts(
+  opts: SweepOptions,
+): Promise<SweepOutcome> {
+  const started = Date.now();
+  const stats: SweepStats = {
+    pages: 0,
+    seen: 0,
+    deleted: 0,
+    unknown: 0,
+    resumed: false,
+    elapsedMs: 0,
+  };
+  const summary = (): string =>
+    `pages=${stats.pages} seen=${stats.seen} deleted=${stats.deleted} unknown=${stats.unknown} resumed=${stats.resumed} elapsedMs=${stats.elapsedMs}`;
+  try {
+    const { bucket } = opts;
+    const now = opts.now ?? Date.now();
+    const pageSize = clampBatch(opts.pageSize, R2_MAX_BATCH);
+    const deleteBatchSize = clampBatch(opts.deleteBatchSize, R2_MAX_BATCH);
+    const maxPages =
+      opts.maxPages !== undefined &&
+      Number.isInteger(opts.maxPages) &&
+      opts.maxPages >= 1
+        ? opts.maxPages
+        : DEFAULT_SWEEP_MAX_PAGES;
+
+    const state = await readState(bucket);
+    if (state.cursor === null && state.sweptAt !== null) {
+      const sweptAt = Date.parse(state.sweptAt);
+      if (Number.isFinite(sweptAt) && now - sweptAt < opts.intervalMs)
+        return { skipped: true };
+    }
+
+    stats.resumed = state.cursor !== null;
+    let cursor: string | undefined = state.cursor ?? undefined;
+    let finished = false;
+    while (stats.pages < maxPages) {
+      const page = await bucket.list({
+        prefix: ARTIFACT_OBJECT_PREFIX,
+        limit: pageSize,
+        include: ['customMetadata'],
+        ...(cursor !== undefined ? { cursor } : {}),
+      });
+      stats.pages++;
+      stats.seen += page.objects.length;
+      const expired: string[] = [];
+      for (const object of page.objects) {
+        const verdict = isExpired(object.customMetadata?.expiresAt, now);
+        if (verdict === undefined) stats.unknown++;
+        else if (verdict) expired.push(object.key);
+      }
+      for (let i = 0; i < expired.length; i += deleteBatchSize) {
+        const batch = expired.slice(i, i + deleteBatchSize);
+        await bucket.delete(batch);
+        stats.deleted += batch.length;
+      }
+      // `truncated`, never the page length: with `include` set R2 may return
+      // fewer objects than `limit` while more remain.
+      if (!page.truncated) {
+        finished = true;
+        break;
+      }
+      cursor = page.cursor;
+    }
+
+    const next: ArtifactSweepState = finished
+      ? { v: 1, sweptAt: new Date(now).toISOString(), cursor: null }
+      : { v: 1, sweptAt: state.sweptAt, cursor: cursor ?? null };
+    await bucket.put(ARTIFACT_SWEEP_STATE_KEY, JSON.stringify(next), {
+      httpMetadata: { contentType: 'application/json' },
+    });
+    stats.elapsedMs = Date.now() - started;
+    opts.log.log(
+      `[artifacts] sweep ${finished ? 'finished' : 'paused, resumes next tick'}: ${summary()}`,
+    );
+    return { skipped: false, done: finished, ...stats };
+  } catch (error) {
+    stats.elapsedMs = Date.now() - started;
+    const message = error instanceof Error ? error.message : String(error);
+    opts.log.error(`[artifacts] sweep failed: ${message} (${summary()})`);
+    // A stored cursor R2 no longer accepts would fail every tick at its
+    // first list. Dropping it costs one write now and a sweep from the start
+    // next tick; a transient failure at that point pays the same price.
+    if (stats.resumed && stats.pages === 0)
+      await dropCursor(opts.bucket, opts.log).catch(() => undefined);
+    return { skipped: false, error: message, ...stats };
+  }
+}
+
+async function dropCursor(
+  bucket: R2Bucket,
+  log: Pick<Logger, 'log'>,
+): Promise<void> {
+  const state = await readState(bucket);
+  if (state.cursor === null) return;
+  await bucket.put(
+    ARTIFACT_SWEEP_STATE_KEY,
+    JSON.stringify({ ...state, cursor: null }),
+    { httpMetadata: { contentType: 'application/json' } },
+  );
+  log.log('[artifacts] sweep dropped its stored cursor; next tick starts over');
+}

package/src/artifacts/tool.ts

@@ -0,0 +1,103 @@
+import { z } from 'zod';
+import { tool } from '../plugin-api/tool-helper';
+import type { PluginTool } from '../plugin-api/types';
+import type { ArtifactRef, ReplyContent } from '../delivery/types';
+
+export const CREATE_ARTIFACT_TOOL = 'create_artifact';
+
+export const CreateArtifactArgs = z.object({
+  title: z
+    .string()
+    .trim()
+    .min(1)
+    .max(120)
+    .describe('A short title for the document, shown on the link card.'),
+  content: z
+    .string()
+    .min(1)
+    .max(200_000)
+    .describe('The full document in Markdown.'),
+  message: z
+    .string()
+    .trim()
+    .min(1)
+    .max(600)
+    .describe(
+      'One or two short sentences sent as the chat message before the link: the answer or the gist, not "here is the document".',
+    ),
+  followUp: z
+    .string()
+    .trim()
+    .max(300)
+    .optional()
+    .describe('At most one short question, sent after the link.'),
+});
+
+/** What the tool returns; the Reply Plan reads it back off the ToolMessage. */
+export const CreateArtifactResult = z.object({
+  ok: z.literal(true),
+  artifactId: z.string(),
+  title: z.string(),
+  url: z.string(),
+  mime: z.literal('text/markdown'),
+  bytes: z.number(),
+  expiresAt: z.string(),
+});
+
+function resultRef(raw: string | undefined): ArtifactRef | null {
+  if (!raw) return null;
+  try {
+    const parsed = CreateArtifactResult.safeParse(JSON.parse(raw));
+    if (!parsed.success) return null;
+    const { artifactId, title, url, mime, bytes, expiresAt } = parsed.data;
+    return { artifactId, title, url, mime, bytes, expiresAt };
+  } catch {
+    return null;
+  }
+}
+
+/** What one call delivered, from its arguments and its (JSON) result. */
+export function createArtifactParts(
+  args: unknown,
+  result: string | undefined,
+): ReplyContent[] {
+  const parsed = CreateArtifactArgs.safeParse(args);
+  const ref = resultRef(result);
+  const parts: ReplyContent[] = [];
+  if (parsed.success) parts.push({ kind: 'text', text: parsed.data.message });
+  if (ref) parts.push({ kind: 'artifact', artifact: ref });
+  if (parsed.success && parsed.data.followUp)
+    parts.push({ kind: 'text', text: parsed.data.followUp });
+  return parts;
+}
+
+/**
+ * Bound on chat surfaces only. Idempotent per tool call id, so a run resumed
+ * after a reset may run it again (`effect: 'read'`) and gets the same link.
+ */
+export function buildCreateArtifactTool(
+  create: (input: {
+    source: string;
+    title: string;
+    content: string;
+  }) => Promise<ArtifactRef>,
+): PluginTool {
+  return tool(
+    async (rawArgs, ctx) => {
+      const args = CreateArtifactArgs.parse(rawArgs);
+      const ref = await create({
+        source: ctx.toolCallId ?? crypto.randomUUID(),
+        title: args.title,
+        content: args.content,
+      });
+      return { ok: true, ...ref };
+    },
+    {
+      name: CREATE_ARTIFACT_TOOL,
+      description:
+        'Send the user a document they open in their browser, together with a short chat message. Use it for anything too long or too structured for chat: a plan, report, comparison, table, draft, list of more than a few items, or code. Put the full Markdown in `content`, the answer or gist in `message`, and at most one question in `followUp`. Call it last and on its own: the reply ends after it, and the user receives the message, the link, then the question.',
+      schema: CreateArtifactArgs,
+      effect: 'read',
+    },
+  );
+}