@ixo/oracle-runtime-workers 0.13.0 → 0.16.0

package/src/plugins/pod-creator/index.ts

@@ -0,0 +1,65 @@
+export {
+  PodCreatorPlugin,
+  type PodCreatorPluginOptions,
+} from './pod-creator.plugin';
+export {
+  CapsuleContentClient,
+  DEFAULT_CAPSULES_BASE_URL,
+  createRegistryInstructionsFetcher,
+  MAX_CAPSULE_INSTRUCTIONS_BYTES,
+  type CapsuleContentClientOptions,
+  type CapsuleContentFetcher,
+  type CapsuleFetchContext,
+  type CapsuleUcanBuilder,
+} from './capsule-content-client';
+export {
+  DESIGN_POD_ROLES,
+  DESIGN_POD_STAGES,
+  type DesignPodRole,
+  type DesignPodStage,
+} from './design-pod-roles';
+export {
+  type BlueprintSection,
+  type PodBlueprint,
+  type ServicePodBlueprint,
+} from './blueprint-types';
+export {
+  KvBlueprintStore,
+  type BlueprintStore,
+  type BlueprintStoreFor,
+} from './blueprint-store';
+export {
+  SPECIALISTS_FOR_STAGE,
+  STAGE_ORDER,
+  assembleServicePodBlueprint,
+  computeReadiness,
+  deriveStage,
+  type Readiness,
+} from './stage';
+export { createOrchestrationTools } from './orchestration-tools';
+export { buildStageSubAgents } from './sub-agents';
+export {
+  SIGN_TRANSACTION_ACTION,
+  createCreateTools,
+  type RequestPodSignatureResult,
+} from './create-tools';
+export {
+  POD_BATCH_TYPE_URLS,
+  notConfiguredChainGateway,
+  podBatchProblem,
+  type ChainGateway,
+  type CreatedPod,
+  type PreparedPodBatch,
+} from './chain-gateway';
+export {
+  KvCreateSessionStore,
+  type ApproveOutcome,
+  type CreateSessionStore,
+  type CreateSessionStoreFor,
+} from './create-session-store';
+export {
+  DEFAULT_NETWORK,
+  podCreatorConfigSchema,
+  readPodCreatorConfig,
+} from './config';
+export { BoundedMap, type BoundedMapOptions } from './bounded-map';

package/src/plugins/pod-creator/orchestration-tools.ts

@@ -0,0 +1,172 @@
+import { z } from 'zod';
+import { computeSubAgentToolName } from '../../core/subagent-as-tool';
+import { tool } from '../../plugin-api/tool-helper';
+import type { PluginTool, RuntimeContext } from '../../plugin-api/types';
+import type { BlueprintStoreFor } from './blueprint-store';
+import type { CreateSessionStoreFor } from './create-session-store';
+import {
+  SPECIALISTS_FOR_STAGE,
+  assembleServicePodBlueprint,
+  computeReadiness,
+  sectionsView,
+} from './stage';
+
+const startSchema = z.object({
+  brief: z
+    .string()
+    .min(1)
+    .describe(
+      'A concise statement of what the POD should do — the service, who it serves, and the outcome it produces.',
+    ),
+  restart: z
+    .boolean()
+    .optional()
+    .describe(
+      'Discard any existing design in this conversation and start fresh with the new brief.',
+    ),
+});
+
+const getBlueprintSchema = z.object({
+  roles: z
+    .array(z.string())
+    .optional()
+    .describe(
+      'Role ids whose full section content to include. Omit for the compact per-section summary.',
+    ),
+});
+
+const emptySchema = z.object({});
+
+const threadId = (ctx: RuntimeContext): string => ctx.session.id;
+
+/**
+ * The conductor's orchestration tools. They own the blueprint lifecycle —
+ * starting a session, scoring readiness, and assembling the final
+ * `service_pod_blueprint`. Sections are written ONLY by the specialist
+ * sub-agents' `submit_section`; the conductor gets no write path, so it cannot
+ * self-certify gate verdicts and skip the specialists. Stage and readiness are
+ * always derived from the recorded sections, never stored.
+ *
+ * The stores are resolved per call from the request context: on Workers they
+ * are the user's own database (`ctx.kv`), not plugin-instance memory.
+ * Discarding a design also discards any batch prepared or approved for it, so
+ * nothing prepared from the old design can reach the wallet.
+ */
+export function createOrchestrationTools(
+  storeFor: BlueprintStoreFor,
+  sessionsFor: CreateSessionStoreFor,
+): PluginTool[] {
+  const startPodDesign = tool(
+    async (args, ctx) => {
+      const { brief, restart } = startSchema.parse(args);
+      const store = storeFor(ctx);
+      if (restart) {
+        await sessionsFor(ctx).clear(ctx.user.did, threadId(ctx));
+        await store.reset(threadId(ctx));
+      }
+      const bp = await store.init(threadId(ctx), brief);
+      const readiness = computeReadiness(bp);
+      return {
+        started: true,
+        threadId: bp.threadId,
+        brief: bp.brief,
+        stage: readiness.stage,
+        nextSpecialists: SPECIALISTS_FOR_STAGE[readiness.stage].map((id) =>
+          computeSubAgentToolName(id),
+        ),
+      };
+    },
+    {
+      name: 'start_pod_design',
+      description:
+        'Open a POD design session and initialise the blueprint. Call this first when the user wants to create a POD; pass restart=true to discard the existing design and begin again.',
+      schema: startSchema,
+    },
+  );
+
+  const getBlueprint = tool(
+    async (args, ctx) => {
+      const { roles } = getBlueprintSchema.parse(args);
+      const bp = await storeFor(ctx).get(threadId(ctx));
+      if (!bp) {
+        return {
+          started: false,
+          message:
+            'No POD design session started yet. Call start_pod_design first.',
+        };
+      }
+      return {
+        started: true,
+        ...(bp.brief !== undefined ? { brief: bp.brief } : {}),
+        readiness: computeReadiness(bp),
+        ...sectionsView(bp, roles),
+      };
+    },
+    {
+      name: 'get_blueprint',
+      description:
+        'Read the POD blueprint: readiness plus a compact per-section summary. Pass roles=[...] to include the full content of specific sections.',
+      schema: getBlueprintSchema,
+      effect: 'read',
+    },
+  );
+
+  const computeReadinessTool = tool(
+    async (_args, ctx) => {
+      const bp = await storeFor(ctx).get(threadId(ctx));
+      if (!bp) {
+        return {
+          started: false,
+          message: 'No POD design session started yet.',
+        };
+      }
+      return computeReadiness(bp);
+    },
+    {
+      name: 'compute_readiness',
+      description:
+        "Score the blueprint's launch readiness and list the blockers that remain.",
+      schema: emptySchema,
+      effect: 'read',
+    },
+  );
+
+  const assembleBlueprint = tool(
+    async (_args, ctx) => {
+      const bp = await storeFor(ctx).get(threadId(ctx));
+      if (!bp) {
+        throw new Error(
+          'No POD design session started yet. Call start_pod_design first.',
+        );
+      }
+      const readiness = computeReadiness(bp);
+      if (!readiness.complete) {
+        return {
+          assembled: false,
+          stage: readiness.stage,
+          blockers: readiness.blockers,
+          message:
+            'Launch-readiness gate not passed. Resolve the blockers before assembling.',
+        };
+      }
+      return {
+        assembled: true,
+        blueprint: assembleServicePodBlueprint(bp),
+      };
+    },
+    {
+      name: 'assemble_blueprint',
+      description:
+        'Assemble the final service_pod_blueprint once the launch-readiness gate passes.',
+      schema: emptySchema,
+      effect: 'read',
+    },
+  );
+
+  return [
+    startPodDesign,
+    getBlueprint,
+    computeReadinessTool,
+    assembleBlueprint,
+  ];
+}

package/src/plugins/pod-creator/pod-creator.plugin.ts

@@ -0,0 +1,190 @@
+import { z } from 'zod';
+import { OraclePlugin } from '../../plugin-api/oracle-plugin';
+import type {
+  PluginManifest,
+  PluginSubAgent,
+  PluginTool,
+  RuntimeContext,
+  UserKvSurface,
+} from '../../plugin-api/types';
+import { KvBlueprintStore, type BlueprintStore } from './blueprint-store';
+import {
+  CapsuleContentClient,
+  type CapsuleContentClientOptions,
+  type CapsuleContentFetcher,
+} from './capsule-content-client';
+import { notConfiguredChainGateway, type ChainGateway } from './chain-gateway';
+import { podCreatorConfigSchema } from './config';
+import {
+  KvCreateSessionStore,
+  type CreateSessionStore,
+} from './create-session-store';
+import { createCreateTools } from './create-tools';
+import { createOrchestrationTools } from './orchestration-tools';
+import { buildStageSubAgents } from './sub-agents';
+
+/**
+ * Sibling env read at request time to configure the capsule client. The
+ * registry URL is owned by the skills plugin's configSchema and `NETWORK` by
+ * the base env schema; pod-creator reads them without redeclaring (which would
+ * collide in the config-schema registry).
+ */
+const capsuleEnvSchema = z.object({
+  SKILLS_CAPSULES_BASE_URL: z.url().optional(),
+  NETWORK: z.enum(['mainnet', 'testnet', 'devnet']).optional(),
+});
+
+const manifest: PluginManifest = {
+  title: 'POD Creator',
+  summary:
+    'Design and create an IXO Programmable Organisational Domain (POD) end to end — qualify, architect, build, evaluate, then prepare an on-chain creation batch for the user to sign.',
+  whenToUse: [
+    'User wants to create, design, or stand up a new POD (Programmable Organisational Domain) or service domain on IXO.',
+    'User describes a service or organisation they want to launch and asks the oracle to turn it into a working POD.',
+  ],
+  whenNotToUse: [
+    'Operating or supporting an already-live POD — out of scope for now.',
+    'Generic on-chain entity creation unrelated to POD design.',
+  ],
+  examples: [
+    {
+      user: 'Help me create a POD for a community solar monitoring service.',
+      thought:
+        'A POD creation request — open the design session, then drive the specialists stage by stage.',
+      tool: 'start_pod_design',
+      args: { brief: 'Community solar monitoring service' },
+    },
+  ],
+  tags: ['pod', 'domain', 'design', 'orchestration', 'on-chain'],
+  category: 'automation',
+  visibility: 'on-demand',
+  stability: 'experimental',
+};
+
+export interface PodCreatorPluginOptions {
+  /**
+   * Registry retrieval for capsule `SKILL.md` text. When omitted, specialist
+   * sub-agents run on their built-in prompts. Pass
+   * `createRegistryInstructionsFetcher()` to load the registry's published
+   * instructions (`GET /skills/{name}/instructions`), or a test stub.
+   */
+  capsuleContentFetcher?: CapsuleContentFetcher;
+  /**
+   * Chain gateway for the create path. Injected by tests; the real IXO MCP
+   * server binding wires in here. When omitted, the create tools report
+   * on-chain creation as unavailable.
+   */
+  chainGateway?: ChainGateway;
+}
+
+/**
+ * The plugin's durable state lives in the user's own database; a host
+ * without `ctx.kv` cannot run the design pipeline without silently losing
+ * the blueprint, so it is refused loudly instead.
+ */
+function requireUserKv(ctx: RuntimeContext): UserKvSurface {
+  if (!ctx.kv) {
+    throw new Error(
+      'pod-creator needs the host per-user store (ctx.kv), which this host does not provide.',
+    );
+  }
+  return ctx.kv;
+}
+
+/**
+ * POD-creator plugin.
+ *
+ * Runs the design-pod lifecycle: a conductor (the main agent) drives the
+ * specialist sub-agents to design a POD, then prepares an unsigned on-chain
+ * creation batch for the user's wallet to sign. Each specialist's instructions
+ * are loaded from the ai-skills capsule registry per stage via the
+ * `CapsuleContentClient`.
+ *
+ * Exposes the conductor's orchestration tools (the blueprint lifecycle), the
+ * stage-gated specialist sub-agents, and the on-chain create path — a
+ * propose → approve → commit handoff with single-use approvals, ending in the
+ * blocking `sign_transaction` AG-UI round-trip. The chain encoding sits behind
+ * an injectable gateway.
+ *
+ * Per-thread blueprints and create sessions are rows in the user's own
+ * database (`ctx.kv`), so a design survives the user object being evicted and
+ * restored from its owner copy. Only the capsule-text cache is held on the
+ * instance.
+ */
+export class PodCreatorPlugin extends OraclePlugin {
+  readonly name = 'pod-creator';
+  readonly version = '0.1.0';
+  readonly manifest = manifest;
+  override readonly softDependsOn = [
+    'agui',
+    'editor',
+    'domain-indexer',
+    'memory',
+  ];
+  override readonly configSchema = podCreatorConfigSchema;
+
+  private readonly capsuleContentFetcher?: CapsuleContentFetcher;
+
+  private readonly chainGateway: ChainGateway;
+
+  /**
+   * Built lazily from request config; cached so the per-thread prompt cache
+   * survives across requests.
+   */
+  private capsuleContent?: CapsuleContentClient;
+
+  constructor(options: PodCreatorPluginOptions = {}) {
+    super();
+    this.capsuleContentFetcher = options.capsuleContentFetcher;
+    this.chainGateway = options.chainGateway ?? notConfiguredChainGateway;
+  }
+
+  override getTools(): PluginTool[] {
+    return [
+      ...createOrchestrationTools(blueprintStoreFor, createSessionStoreFor),
+      ...createCreateTools(
+        blueprintStoreFor,
+        this.chainGateway,
+        createSessionStoreFor,
+      ),
+    ];
+  }
+
+  override async getRequestSubAgents(
+    rt: RuntimeContext,
+  ): Promise<PluginSubAgent[]> {
+    // This hook runs on every turn whether or not the capability is loaded:
+    // on a host without the store there is no design to offer specialists
+    // for, and the tools themselves report the missing store when called.
+    if (!rt.kv) return [];
+    return buildStageSubAgents(rt, blueprintStoreFor, this.capsuleClient(rt));
+  }
+
+  private capsuleClient(rt: RuntimeContext): CapsuleContentClient {
+    if (!this.capsuleContent) {
+      const env = capsuleEnvSchema.safeParse(rt.config);
+      const options: CapsuleContentClientOptions = {};
+      if (env.success) {
+        if (env.data.SKILLS_CAPSULES_BASE_URL !== undefined) {
+          options.baseUrl = env.data.SKILLS_CAPSULES_BASE_URL;
+        }
+        if (env.data.NETWORK !== undefined) {
+          options.network = env.data.NETWORK;
+        }
+      }
+      if (this.capsuleContentFetcher !== undefined) {
+        options.fetcher = this.capsuleContentFetcher;
+      }
+      this.capsuleContent = new CapsuleContentClient(options);
+    }
+    return this.capsuleContent;
+  }
+}
+
+function blueprintStoreFor(ctx: RuntimeContext): BlueprintStore {
+  return new KvBlueprintStore(requireUserKv(ctx));
+}
+
+function createSessionStoreFor(ctx: RuntimeContext): CreateSessionStore {
+  return new KvCreateSessionStore(requireUserKv(ctx));
+}

package/src/plugins/pod-creator/stage.ts

@@ -0,0 +1,201 @@
+import type {
+  BlueprintSection,
+  PodBlueprint,
+  ServicePodBlueprint,
+} from './blueprint-types';
+import {
+  DESIGN_POD_ROLES,
+  DESIGN_POD_STAGES,
+  type DesignPodStage,
+} from './design-pod-roles';
+
+/** The lifecycle stages in readiness order. */
+export const STAGE_ORDER: readonly DesignPodStage[] = DESIGN_POD_STAGES;
+
+/** Role ids required to complete each stage, grouped from the role catalogue. */
+function groupRolesByStage(): Record<DesignPodStage, string[]> {
+  const out: Record<DesignPodStage, string[]> = {
+    qualify: [],
+    architect: [],
+    build: [],
+    evaluate: [],
+    package: [],
+    gate: [],
+  };
+  for (const role of DESIGN_POD_ROLES) {
+    out[role.stage].push(role.id);
+  }
+  return out;
+}
+
+export const SPECIALISTS_FOR_STAGE: Record<DesignPodStage, readonly string[]> =
+  groupRolesByStage();
+
+/**
+ * A section counts toward readiness when it exists — and, for gate-bearing
+ * roles (the evaluate oracles and the launch-readiness gate), only when it
+ * carries an explicit `'pass'` verdict. This stops a gate role that submitted
+ * content without a verdict from silently satisfying the launch gate.
+ */
+function sectionSatisfies(section: BlueprintSection | undefined): boolean {
+  if (section === undefined) {
+    return false;
+  }
+  const isGateRole = section.stage === 'evaluate' || section.stage === 'gate';
+  return isGateRole ? section.verdict === 'pass' : section.verdict !== 'fail';
+}
+
+/**
+ * The current stage: the first stage in {@link STAGE_ORDER} whose required
+ * sections are not all satisfied. A failed gate verdict leaves its stage
+ * unsatisfied, so the stage re-opens until the specialist is re-run. When every
+ * stage is satisfied, returns `'gate'` (and {@link computeReadiness} reports
+ * `complete: true`).
+ */
+export function deriveStage(bp: PodBlueprint): DesignPodStage {
+  for (const stage of STAGE_ORDER) {
+    const allSatisfied = SPECIALISTS_FOR_STAGE[stage].every((roleId) =>
+      sectionSatisfies(bp.sections[roleId]),
+    );
+    if (!allSatisfied) {
+      return stage;
+    }
+  }
+  return 'gate';
+}
+
+/** Readiness summary derived from the blueprint's recorded sections. */
+export interface Readiness {
+  /** The stage the conductor should drive next. */
+  stage: DesignPodStage;
+  /** True once every required section is satisfied (gate passed). */
+  complete: boolean;
+  /** Stages whose required sections are all satisfied. */
+  completedStages: DesignPodStage[];
+  /** Human-readable blockers (missing sections, failed gates). */
+  blockers: string[];
+  /** Fraction of required sections satisfied, `0..1`. */
+  score: number;
+}
+
+export function computeReadiness(bp: PodBlueprint): Readiness {
+  const blockers: string[] = [];
+  const completedStages: DesignPodStage[] = [];
+  let satisfied = 0;
+  let required = 0;
+
+  for (const stage of STAGE_ORDER) {
+    let stageComplete = true;
+    for (const roleId of SPECIALISTS_FOR_STAGE[stage]) {
+      required += 1;
+      const section = bp.sections[roleId];
+      if (sectionSatisfies(section)) {
+        satisfied += 1;
+      } else {
+        stageComplete = false;
+        if (section === undefined) {
+          blockers.push(`${stage}: ${roleId} not recorded`);
+        } else if (section.verdict === 'fail') {
+          const detail = (section.blockers ?? []).join('; ') || 'no detail';
+          blockers.push(`${stage}: ${roleId} failed (${detail})`);
+        } else {
+          blockers.push(`${stage}: ${roleId} awaiting a pass verdict`);
+        }
+      }
+    }
+    if (stageComplete) {
+      completedStages.push(stage);
+    }
+  }
+
+  return {
+    stage: deriveStage(bp),
+    complete: required > 0 && satisfied === required,
+    completedStages,
+    blockers,
+    score: required === 0 ? 0 : satisfied / required,
+  };
+}
+
+/**
+ * Compact per-section view for blueprint reads. Sections carry arbitrary-size
+ * role-defined payloads, so blueprint reads return this summary by default and
+ * full content only for explicitly requested roles.
+ */
+export function summarizeSection(section: BlueprintSection): {
+  role: string;
+  stage: DesignPodStage;
+  verdict?: 'pass' | 'fail';
+  recordedAt: string;
+  contentBytes: number;
+} {
+  return {
+    role: section.role,
+    stage: section.stage,
+    ...(section.verdict !== undefined ? { verdict: section.verdict } : {}),
+    recordedAt: section.recordedAt,
+    contentBytes: JSON.stringify(section.content ?? null).length,
+  };
+}
+
+/**
+ * The blueprint read shared by the conductor's `get_blueprint` and the
+ * specialists' `read_blueprint`: the compact per-section summary, plus the
+ * full content of the requested roles when `roles` is given.
+ */
+export function sectionsView(
+  bp: PodBlueprint,
+  roles: readonly string[] | undefined,
+): {
+  sections: ReturnType<typeof summarizeSection>[];
+  content?: Record<string, unknown>;
+} {
+  const sections = Object.values(bp.sections);
+  return {
+    sections: sections.map(summarizeSection),
+    ...(roles !== undefined
+      ? {
+          content: Object.fromEntries(
+            sections
+              .filter((section) => roles.includes(section.role))
+              .map((section) => [section.role, section.content]),
+          ),
+        }
+      : {}),
+  };
+}
+
+/** Group the recorded sections by stage, preserving the stage ordering. */
+function groupSectionsByStage(
+  bp: PodBlueprint,
+): Record<DesignPodStage, BlueprintSection[]> {
+  const out: Record<DesignPodStage, BlueprintSection[]> = {
+    qualify: [],
+    architect: [],
+    build: [],
+    evaluate: [],
+    package: [],
+    gate: [],
+  };
+  // The stored blueprint is schema-checked on read, so every section's stage
+  // is one of the catalogue's.
+  for (const section of Object.values(bp.sections)) {
+    out[section.stage].push(section);
+  }
+  return out;
+}
+
+/** Assemble the final `service_pod_blueprint` from a completed blueprint. */
+export function assembleServicePodBlueprint(
+  bp: PodBlueprint,
+): ServicePodBlueprint {
+  const blueprint: ServicePodBlueprint = {
+    threadId: bp.threadId,
+    stages: groupSectionsByStage(bp),
+    assembledAt: new Date().toISOString(),
+  };
+  if (bp.brief !== undefined) {
+    blueprint.brief = bp.brief;
+  }
+  return blueprint;
+}