@ixo/oracle-runtime-workers 0.13.0 → 0.15.0

package/src/plugins/pod-creator/blueprint-store.ts

@@ -0,0 +1,163 @@
+import type { RuntimeContext, UserKvSurface } from '../../plugin-api/types';
+import {
+  podBlueprintSchema,
+  type BlueprintSection,
+  type PodBlueprint,
+} from './blueprint-types';
+
+/**
+ * Durable per-thread store for the evolving POD blueprint. The blueprint must
+ * outlive a single request (each request builds a fresh `RuntimeContext`), so
+ * it is held outside the graph state — never as a graph-state field.
+ */
+export interface BlueprintStore {
+  /** Create the blueprint for a thread, or return the existing one. */
+  init(threadId: string, brief: string | undefined): Promise<PodBlueprint>;
+  /** Read the current blueprint, or `null` if no session has started. */
+  get(threadId: string): Promise<PodBlueprint | null>;
+  /** Record or replace a section; returns the updated blueprint. */
+  putSection(
+    threadId: string,
+    section: BlueprintSection,
+  ): Promise<PodBlueprint>;
+  /** Discard the thread's blueprint so a fresh design can start. */
+  reset(threadId: string): Promise<void>;
+}
+
+/** Resolves the blueprint store for one request (it lives in the user's database). */
+export type BlueprintStoreFor = (ctx: RuntimeContext) => BlueprintStore;
+
+/** `ctx.kv` namespace holding one blueprint per thread. */
+export const BLUEPRINT_NAMESPACE = 'pod-creator/blueprints';
+
+/** A design session that idles longer than this is discarded. */
+const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
+/** Design sessions retained per user before LRU eviction. */
+const DEFAULT_MAX_ENTRIES = 500;
+
+export interface KvBlueprintStoreOptions {
+  maxEntries?: number;
+  ttlMs?: number;
+}
+
+const nowIso = (): string => new Date().toISOString();
+
+/**
+ * Parse a stored blueprint. A row that no longer matches the schema is
+ * reported rather than silently treated as absent: the user can discard it
+ * with `start_pod_design({ restart: true })`.
+ */
+function parseStored(threadId: string, value: unknown): PodBlueprint | null {
+  if (value === undefined) return null;
+  const parsed = podBlueprintSchema.safeParse(value);
+  if (!parsed.success) {
+    throw new Error(
+      `The stored POD blueprint for thread ${threadId} is unreadable (${parsed.error.issues
+        .map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`)
+        .join(
+          '; ',
+        )}). Restart the design with start_pod_design({ restart: true }).`,
+    );
+  }
+  return parsed.data;
+}
+
+/**
+ * {@link BlueprintStore} over the host's `ctx.kv` rows in the user's own
+ * database: the blueprint survives the user object being evicted and restored
+ * from its owner copy. Bounded per user (LRU + idle TTL, enforced by the KV
+ * store on every write), and every mutation is one atomic read-modify-write,
+ * so specialists submitting sections concurrently never lose one another's.
+ * Values cross the store as JSON, so a caller can never mutate the stored
+ * document in place.
+ */
+export class KvBlueprintStore implements BlueprintStore {
+  private readonly writeOptions: { idleTtlMs: number; maxEntries: number };
+
+  constructor(
+    private readonly kv: UserKvSurface,
+    options: KvBlueprintStoreOptions = {},
+  ) {
+    this.writeOptions = {
+      idleTtlMs: options.ttlMs ?? DEFAULT_TTL_MS,
+      maxEntries: options.maxEntries ?? DEFAULT_MAX_ENTRIES,
+    };
+  }
+
+  async init(
+    threadId: string,
+    brief: string | undefined,
+  ): Promise<PodBlueprint> {
+    const written = await this.kv.update(
+      BLUEPRINT_NAMESPACE,
+      threadId,
+      (current) => {
+        const existing = parseStored(threadId, current);
+        if (existing) {
+          if (brief && existing.brief === undefined) {
+            return { ...existing, brief, updatedAt: nowIso() };
+          }
+          return existing;
+        }
+        const now = nowIso();
+        const created: PodBlueprint = {
+          threadId,
+          sections: {},
+          createdAt: now,
+          updatedAt: now,
+        };
+        if (brief !== undefined) {
+          created.brief = brief;
+        }
+        return created;
+      },
+      this.writeOptions,
+    );
+    return this.required(threadId, written);
+  }
+
+  async get(threadId: string): Promise<PodBlueprint | null> {
+    return parseStored(
+      threadId,
+      await this.kv.get(BLUEPRINT_NAMESPACE, threadId),
+    );
+  }
+
+  async putSection(
+    threadId: string,
+    section: BlueprintSection,
+  ): Promise<PodBlueprint> {
+    const written = await this.kv.update(
+      BLUEPRINT_NAMESPACE,
+      threadId,
+      (current) => {
+        const now = nowIso();
+        const bp = parseStored(threadId, current) ?? {
+          threadId,
+          sections: {},
+          createdAt: now,
+          updatedAt: now,
+        };
+        return {
+          ...bp,
+          sections: { ...bp.sections, [section.role]: section },
+          updatedAt: now,
+        };
+      },
+      this.writeOptions,
+    );
+    return this.required(threadId, written);
+  }
+
+  async reset(threadId: string): Promise<void> {
+    await this.kv.delete(BLUEPRINT_NAMESPACE, threadId);
+  }
+
+  private required(threadId: string, written: unknown): PodBlueprint {
+    const bp = parseStored(threadId, written);
+    if (!bp) {
+      throw new Error(`POD blueprint for thread ${threadId} was not written`);
+    }
+    return bp;
+  }
+}

package/src/plugins/pod-creator/blueprint-types.ts

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+import { DESIGN_POD_STAGES, type DesignPodStage } from './design-pod-roles';
+
+/**
+ * One section of the blueprint, produced by a specialist role. The `content`
+ * is role-defined and opaque to the conductor — it is recorded, never parsed,
+ * by the orchestration layer. Gate-bearing roles (the evaluate oracles and the
+ * launch-readiness gate) additionally carry a `verdict`.
+ *
+ * Declared as a schema because the blueprint is stored as JSON in the user's
+ * database and read back as `unknown`.
+ */
+export const blueprintSectionSchema = z.object({
+  /** The role id that produced this section (e.g. `service_architect`). */
+  role: z.string(),
+  /** The lifecycle stage the section belongs to. */
+  stage: z.enum(DESIGN_POD_STAGES),
+  /** The section's structured content (role-defined). */
+  content: z.unknown(),
+  /** Gate verdict for gate-bearing roles; absent for plain sections. */
+  verdict: z.enum(['pass', 'fail']).optional(),
+  /** Blocking issues when `verdict` is `'fail'`. */
+  blockers: z.array(z.string()).optional(),
+  /** ISO-8601 timestamp when the section was recorded. */
+  recordedAt: z.string(),
+});
+
+export type BlueprintSection = z.infer<typeof blueprintSectionSchema>;
+
+/**
+ * The per-thread blueprint document the conductor builds up across a design
+ * session. Sections are keyed by role id (one section per specialist). Stage
+ * and readiness are DERIVED from these sections — they are never stored, so the
+ * document stays a single source of truth.
+ */
+export const podBlueprintSchema = z.object({
+  /** The owning thread id (`RuntimeContext.session.id`). */
+  threadId: z.string(),
+  /** A concise statement of the POD's intent, set at session start. */
+  brief: z.string().optional(),
+  /** Recorded sections, keyed by role id. */
+  sections: z.record(z.string(), blueprintSectionSchema),
+  /** ISO-8601 timestamps. */
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+
+export type PodBlueprint = z.infer<typeof podBlueprintSchema>;
+
+/**
+ * The assembled artifact produced once the launch-readiness gate passes — the
+ * `service_pod_blueprint`. The exact registry schema is refined when the
+ * design-pod templates are wired; this is the structural assembly of the
+ * recorded sections grouped by stage.
+ */
+export interface ServicePodBlueprint {
+  threadId: string;
+  brief?: string;
+  stages: Record<DesignPodStage, BlueprintSection[]>;
+  assembledAt: string;
+}

package/src/plugins/pod-creator/bounded-map.ts

@@ -0,0 +1,87 @@
+/**
+ * A Map with an entry cap and an idle TTL, for caches held on the plugin
+ * instance, which lives as long as the isolate and is shared by every user
+ * object the isolate hosts. Reads and writes refresh an entry's recency and
+ * idle deadline; when the cap is exceeded the least-recently-used entry is
+ * evicted. Expiry is lazy — enforced on access, not by timers (a pending
+ * timer would keep a Durable Object resident) — so the structure is safe to
+ * hold indefinitely. Durable per-user state does not belong here: it goes
+ * through `ctx.kv`, which applies the same bounds in the user's database.
+ */
+export interface BoundedMapOptions {
+  /** Maximum live entries; the least-recently-used entry is evicted beyond it. */
+  maxEntries: number;
+  /** Idle time after the last read/write before an entry expires. */
+  ttlMs: number;
+  /** Clock override for tests. */
+  now?: () => number;
+}
+
+interface Entry<V> {
+  value: V;
+  expiresAt: number;
+}
+
+export class BoundedMap<V> {
+  private readonly entries = new Map<string, Entry<V>>();
+  private readonly maxEntries: number;
+  private readonly ttlMs: number;
+  private readonly now: () => number;
+
+  constructor(options: BoundedMapOptions) {
+    this.maxEntries = options.maxEntries;
+    this.ttlMs = options.ttlMs;
+    this.now = options.now ?? Date.now;
+  }
+
+  get(key: string): V | undefined {
+    const entry = this.entries.get(key);
+    if (!entry) {
+      return undefined;
+    }
+    if (entry.expiresAt <= this.now()) {
+      this.entries.delete(key);
+      return undefined;
+    }
+    // Re-insert to mark as most-recently-used and extend the idle deadline.
+    this.entries.delete(key);
+    entry.expiresAt = this.now() + this.ttlMs;
+    this.entries.set(key, entry);
+    return entry.value;
+  }
+
+  set(key: string, value: V): void {
+    this.entries.delete(key);
+    this.entries.set(key, { value, expiresAt: this.now() + this.ttlMs });
+    this.evict();
+  }
+
+  delete(key: string): void {
+    this.entries.delete(key);
+  }
+
+  clear(): void {
+    this.entries.clear();
+  }
+
+  get size(): number {
+    return this.entries.size;
+  }
+
+  /** Drop expired entries, then trim oldest-first down to the cap. */
+  private evict(): void {
+    const cutoff = this.now();
+    for (const [key, entry] of this.entries) {
+      if (entry.expiresAt <= cutoff) {
+        this.entries.delete(key);
+      }
+    }
+    while (this.entries.size > this.maxEntries) {
+      const oldest = this.entries.keys().next();
+      if (oldest.done) {
+        break;
+      }
+      this.entries.delete(oldest.value);
+    }
+  }
+}

package/src/plugins/pod-creator/capsule-content-client.ts

@@ -0,0 +1,285 @@
+import type { RuntimeContext } from '../../plugin-api/types';
+import { mintInvocationSafely, resolveServiceDidSafely } from '../ucan-failure';
+import { BoundedMap } from './bounded-map';
+import { DEFAULT_NETWORK } from './config';
+
+/** Public capsules registry served by ai-skills. */
+export const DEFAULT_CAPSULES_BASE_URL = 'https://capsules.skills.ixo.earth';
+
+/**
+ * Capsule texts cached across requests. Keyed by capsule name only, so the
+ * twelve roles fill at most twelve entries; the cap is a guard, not a budget.
+ */
+const CACHE_MAX_ENTRIES = 64;
+const CACHE_TTL_MS = 6 * 60 * 60 * 1000;
+
+/**
+ * How long a failed fetch is remembered: within it every turn uses the
+ * built-in prompt without another request (and without another log line).
+ */
+export const CAPSULE_FAILURE_TTL_MS = 5 * 60 * 1000;
+
+/** Default deadline of one registry instructions request. */
+export const DEFAULT_CAPSULE_FETCH_TIMEOUT_MS = 10_000;
+
+/** Largest instructions body accepted from the registry (a larger one is refused). */
+export const MAX_CAPSULE_INSTRUCTIONS_BYTES = 64 * 1024;
+
+/** The registry's skill-name rule (`GET /skills/{name}/instructions`). */
+const SKILL_NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const SKILL_NAME_MAX_LENGTH = 64;
+
+/**
+ * Mints an `ixo:skills` invocation for an outbound capsules-registry call, or
+ * returns `undefined` so the caller falls back to public-only. Never throws.
+ */
+export type CapsuleUcanBuilder = (
+  serviceUrl: string,
+  rt: RuntimeContext,
+) => Promise<string | undefined>;
+
+/** Carrier handed to a {@link CapsuleContentFetcher} for one retrieval. */
+export interface CapsuleFetchContext {
+  baseUrl: string;
+  network: string;
+  headers: Record<string, string>;
+  /** The turn's abort signal: a cancelled turn abandons the fetch. */
+  signal?: AbortSignal;
+}
+
+/**
+ * Retrieves a capsule's `SKILL.md` text from the registry. Injected so tests
+ * stub it and so a deployment chooses the retrieval path without touching the
+ * client's auth / caching concerns.
+ */
+export type CapsuleContentFetcher = (
+  capsuleName: string,
+  ctx: CapsuleFetchContext,
+) => Promise<string>;
+
+export interface CapsuleContentClientOptions {
+  /** Registry base URL. Defaults to {@link DEFAULT_CAPSULES_BASE_URL}. */
+  baseUrl?: string;
+  /** Routing hint forwarded as `X-IXO-Network`. Defaults to {@link DEFAULT_NETWORK}. */
+  network?: string;
+  /** UCAN minter. Defaults to a shared-helper builder for `ixo:skills`. */
+  ucanBuilder?: CapsuleUcanBuilder;
+  /**
+   * Registry retrieval. Omitted: no registry is contacted (no fetch, no UCAN
+   * mint) and every specialist runs on its built-in prompt.
+   */
+  fetcher?: CapsuleContentFetcher;
+  /** Clock override for tests (failure-cache expiry). */
+  now?: () => number;
+}
+
+const defaultUcanBuilder: CapsuleUcanBuilder = async (serviceUrl, rt) => {
+  const did = await resolveServiceDidSafely(rt, serviceUrl, 'pod-creator');
+  if (!did) {
+    return undefined;
+  }
+  // Claim the ability the user's delegation grants for the registry: on
+  // Workers an unqualified mint claims `'*'`, which only a `'*'` grant covers
+  // (same claim as the skills plugin).
+  const invocation = await mintInvocationSafely(
+    rt,
+    { did, capability: 'ixo:skills' },
+    'pod-creator',
+    { can: 'skills/*' },
+  );
+  return invocation ?? undefined;
+};
+
+/**
+ * A {@link CapsuleContentFetcher} over the registry's
+ * `GET /skills/{name}/instructions`, which returns the `SKILL.md` body
+ * (frontmatter stripped) of the latest PUBLIC version of a skill. The
+ * endpoint serves public mainnet skills only: the auth and network headers
+ * are sent but do not widen what it returns. Each request is bounded by
+ * `timeoutMs`, by the turn's abort signal and by
+ * {@link MAX_CAPSULE_INSTRUCTIONS_BYTES} (a larger body is refused, not
+ * truncated). A non-2xx answer (404 for an unpublished capsule) is an error,
+ * which the client turns into the built-in fallback prompt.
+ */
+export function createRegistryInstructionsFetcher(
+  options: { timeoutMs?: number } = {},
+): CapsuleContentFetcher {
+  const timeoutMs = options.timeoutMs ?? DEFAULT_CAPSULE_FETCH_TIMEOUT_MS;
+  return async (capsuleName, ctx) => {
+    if (
+      capsuleName.length > SKILL_NAME_MAX_LENGTH ||
+      !SKILL_NAME_PATTERN.test(capsuleName)
+    ) {
+      throw new Error(`"${capsuleName}" is not a valid registry skill name`);
+    }
+    const url = new URL(
+      `/skills/${encodeURIComponent(capsuleName)}/instructions`,
+      ctx.baseUrl,
+    );
+    // A timer that is always cleared, not `AbortSignal.timeout`: a pending
+    // timer keeps the user's Durable Object resident until it fires.
+    const deadline = new AbortController();
+    const timer = setTimeout(() => deadline.abort(), timeoutMs);
+    try {
+      const response = await fetch(url.toString(), {
+        headers: { ...ctx.headers, Accept: 'text/markdown' },
+        signal: ctx.signal
+          ? AbortSignal.any([ctx.signal, deadline.signal])
+          : deadline.signal,
+      });
+      if (!response.ok) {
+        // Release the connection without reading an error body we discard.
+        await response.body?.cancel();
+        throw new Error(
+          `registry answered ${response.status} for the instructions of "${capsuleName}"`,
+        );
+      }
+      const text = await readCapped(response, capsuleName);
+      if (text.trim().length === 0) {
+        throw new Error(
+          `registry returned empty instructions for "${capsuleName}"`,
+        );
+      }
+      return text;
+    } finally {
+      clearTimeout(timer);
+    }
+  };
+}
+
+/**
+ * The response body as text, refusing it once it passes
+ * {@link MAX_CAPSULE_INSTRUCTIONS_BYTES} — by the declared length when there
+ * is one, and by the bytes actually read either way.
+ */
+async function readCapped(
+  response: Response,
+  capsuleName: string,
+): Promise<string> {
+  const tooLarge = (): Error =>
+    new Error(
+      `registry instructions for "${capsuleName}" exceed ${MAX_CAPSULE_INSTRUCTIONS_BYTES} bytes`,
+    );
+  const declared = Number(response.headers.get('content-length'));
+  if (Number.isFinite(declared) && declared > MAX_CAPSULE_INSTRUCTIONS_BYTES) {
+    await response.body?.cancel();
+    throw tooLarge();
+  }
+  if (!response.body) return '';
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    total += value.byteLength;
+    if (total > MAX_CAPSULE_INSTRUCTIONS_BYTES) {
+      await reader.cancel();
+      throw tooLarge();
+    }
+    chunks.push(value);
+  }
+  const bytes = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return new TextDecoder().decode(bytes);
+}
+
+function buildRegistryHeaders(
+  network: string,
+  ucan: string | undefined,
+): Record<string, string> {
+  const headers: Record<string, string> = { 'X-IXO-Network': network };
+  if (ucan) {
+    headers.Authorization = `Bearer ${ucan}`;
+    headers['X-Auth-Type'] = 'ucan';
+  }
+  return headers;
+}
+
+/**
+ * Resolves design-pod role capsules to their `SKILL.md` text for use as
+ * sub-agent system prompts, or to `undefined` when the built-in prompt should
+ * be used. Owns the cross-cutting concerns — `ixo:skills` auth, the network
+ * header, caching — and delegates the retrieval to an injectable
+ * {@link CapsuleContentFetcher}.
+ *
+ * Without a fetcher (the bundled default) it answers `undefined` at once: no
+ * request, no UCAN mint, no log line.
+ *
+ * The cache lives on the plugin instance — isolate memory shared by every
+ * user object the isolate hosts — and is keyed by capsule name alone. That
+ * is sound because the registry endpoint serves public content only; a
+ * custom fetcher must likewise return text that is the same for every user.
+ * A failure is remembered for {@link CAPSULE_FAILURE_TTL_MS} and logged once
+ * per capsule per window, so an unpublished capsule costs one request and one
+ * warn line per window, not one per turn.
+ */
+export class CapsuleContentClient {
+  private readonly baseUrl: string;
+  private readonly network: string;
+  private readonly ucanBuilder: CapsuleUcanBuilder;
+  private readonly fetcher?: CapsuleContentFetcher;
+  private readonly cache: BoundedMap<string>;
+  private readonly failures: BoundedMap<true>;
+
+  constructor(options: CapsuleContentClientOptions = {}) {
+    this.baseUrl = options.baseUrl ?? DEFAULT_CAPSULES_BASE_URL;
+    this.network = options.network ?? DEFAULT_NETWORK;
+    this.ucanBuilder = options.ucanBuilder ?? defaultUcanBuilder;
+    this.fetcher = options.fetcher;
+    const clock = options.now ? { now: options.now } : {};
+    this.cache = new BoundedMap({
+      maxEntries: CACHE_MAX_ENTRIES,
+      ttlMs: CACHE_TTL_MS,
+      ...clock,
+    });
+    this.failures = new BoundedMap({
+      maxEntries: CACHE_MAX_ENTRIES,
+      ttlMs: CAPSULE_FAILURE_TTL_MS,
+      ...clock,
+    });
+  }
+
+  /**
+   * The capsule's `SKILL.md` text, or `undefined` when there is no fetcher,
+   * when the fetch fails, or while a recent failure is remembered. Never
+   * throws. Mints an `ixo:skills` invocation for the request when possible
+   * and degrades to unauthenticated on auth failure.
+   */
+  async getSkillMarkdown(
+    capsuleName: string,
+    rt: RuntimeContext,
+  ): Promise<string | undefined> {
+    if (!this.fetcher) return undefined;
+    const cached = this.cache.get(capsuleName);
+    if (cached !== undefined) return cached;
+    if (this.failures.get(capsuleName)) return undefined;
+    try {
+      const ucan = await this.ucanBuilder(this.baseUrl, rt);
+      const markdown = await this.fetcher(capsuleName, {
+        baseUrl: this.baseUrl,
+        network: this.network,
+        headers: buildRegistryHeaders(this.network, ucan),
+        signal: rt.abortSignal,
+      });
+      this.cache.set(capsuleName, markdown);
+      return markdown;
+    } catch (error) {
+      // A cancelled turn says nothing about the registry: don't remember it.
+      if (rt.abortSignal.aborted) return undefined;
+      this.failures.set(capsuleName, true);
+      rt.logger.warn(
+        `[pod-creator] registry instructions for "${capsuleName}" unavailable (${
+          error instanceof Error ? error.message : String(error)
+        }); using the built-in prompt for ${Math.round(
+          CAPSULE_FAILURE_TTL_MS / 60_000,
+        )} min before retrying.`,
+      );
+      return undefined;
+    }
+  }
+}