@ixo/oracle-runtime-workers 0.40.1 → 0.41.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ixo/oracle-runtime-workers",
-  "version": "0.40.1",
+  "version": "0.41.1",
   "description": "QiForge oracle runtime for Cloudflare Workers — Durable Object per user (SQLite in WASM over DO storage), Matrix E2EE gateway Durable Object, Hono HTTP/SSE shell.",
   "private": false,
   "publishConfig": {
@@ -67,10 +67,10 @@
     "protobufjs": "^7.6.5",
     "@ixo/topic-protocol": "1.0.0-rc.8",
     "survey-core": "2.3.11",
+    "@ixo/ucan": "2.3.0",
     "@ixo/common": "1.8.0",
     "@ixo/ixo-transaction": "0.2.0",
-    "@ixo/action-interactions": "0.1.1",
-    "@ixo/ucan": "2.3.0"
+    "@ixo/action-interactions": "0.1.1"
   },
   "devDependencies": {
     "@cloudflare/vitest-pool-workers": "^0.22.0",

package/src/index.ts

@@ -54,6 +54,8 @@ export {
 } from './owner-store/ixo-vfs-store';
 export { MatrixMediaOwnerStore } from './owner-store/matrix-media-store';
 export { MatrixGatewayDO } from './matrix/gateway-do';
+/** asks.world sign-ins, one per person; a host re-exports it under this name (`docs/asks.md`). */
+export { AsksConnectionDO } from './plugins/asks/connection-do';
 export {
   createUserOracleDO,
   type OracleWorkerHooks,

package/src/plugins/asks/asks.plugin.ts

@@ -0,0 +1,226 @@
+import {
+  defineDecision,
+  OraclePlugin,
+  type AgentMiddleware,
+  type AuthExcludedRoute,
+  type MergedConfig,
+  type PluginEnv,
+  type PluginManifest,
+  type PluginRoute,
+  type PluginTool,
+  type RuntimeContext,
+} from '../../plugin-api';
+import { createMiddleware } from 'langchain';
+import { z } from 'zod';
+import { channelOriginsOf } from './attach';
+import type { AsksWorkerEnv } from './connection';
+import { ASKS_OPERATING_GUIDE } from './guide';
+import { asksMcpUrlOf, deriveKeys, objectNameOf, type AsksKeys } from './oauth';
+import { asksRoutes, connectionOf } from './routes';
+import {
+  asksSkillDecisionOptions,
+  lastHumanText,
+  pickSkill,
+} from './skill-pick';
+import {
+  AsksSkills,
+  folderOf,
+  workersSkillCache,
+  type Skill,
+  type SkillFolder,
+} from './skills';
+import {
+  asksTools,
+  connectAsksMcp,
+  keepTurnFiles,
+  preloadText,
+  type McpConnect,
+} from './tools';
+
+const configSchema = z.object({
+  /** Seals the tokens and names each person's connection object (`openssl rand -base64 32`). */
+  ASKS_TOKEN_KEY: z
+    .string()
+    .min(32, 'ASKS_TOKEN_KEY must be at least 32 characters.'),
+  /** `https://wa.me/<number>?text=…`: the callback page's "Back to WhatsApp". */
+  ASKS_WHATSAPP_RETURN_URL: z.string().url().optional(),
+  /** Pilot: comma-separated user DIDs who get asks. Unset: everyone. */
+  ASKS_ALLOWED_DIDS: z.string().optional(),
+});
+
+const manifest: PluginManifest = {
+  title: 'asks.world',
+  summary:
+    'asks.world: find paid work and get paid, post asks real people answer, get an app or agent reviewed by verified pros, and see or cash out asks money.',
+  // The on-demand catalogue's line (runtime 0.39+, at most 60 characters).
+  brief: 'paid work, asks people answer, pro reviews, asks money',
+  whenToUse: [
+    'The person mentions asks.world or an ask, wants paid work or to apply to one, has an invitation to an ask, or wants to hand in an answer or a report.',
+    'The person wants to hire someone, have something checked or found out somewhere they cannot see, or get an app or agent reviewed by pros.',
+    'The person asks about their asks money, earnings or cash-out, their pro page, or whether anyone answered their ask.',
+  ],
+  whenNotToUse: [
+    'IXO wallet balances, chain transactions or other on-chain actions (asks money is separate).',
+    'General web research or tasks that need no person on asks.world.',
+  ],
+  tags: ['asks', 'work', 'jobs', 'payments', 'reviews'],
+  category: 'integration',
+  visibility: 'on-demand',
+  stability: 'beta',
+};
+
+export interface AsksPluginOptions {
+  /** The Worker env: the binding, vars and secret. Default: `env` from `cloudflare:workers`. */
+  env?: () => AsksWorkerEnv;
+  connect?: McpConnect;
+  fetch?: typeof fetch;
+}
+
+/** Loaded on first use, so the plain-Node test suites can import the plugin. */
+const workerEnv = async (): Promise<AsksWorkerEnv> => {
+  // The host's Env type is its own; the plugin reads only its optional keys.
+  const env: object = (await import('cloudflare:workers')).env;
+  return env;
+};
+
+/**
+ * asks.world through its hosted connector (`/v1/mcp` on the asks host for
+ * `NETWORK`), signed in once per person with OAuth (asks' Google login).
+ * See `docs/asks.md` and `guide.ts` for how the model is told to use it.
+ */
+export class AsksPlugin extends OraclePlugin {
+  static readonly NAME = 'asks';
+
+  readonly name = AsksPlugin.NAME;
+
+  readonly version = '1.0.0';
+
+  readonly manifest = manifest;
+
+  override readonly operatingGuide = ASKS_OPERATING_GUIDE;
+
+  override readonly configSchema = configSchema;
+
+  override readonly autoDetectHint =
+    'ASKS_TOKEN_KEY, ORACLE_PUBLIC_URL and NETWORK (mainnet, testnet or devnet)';
+
+  private keys: Promise<AsksKeys> | null = null;
+
+  private readonly skillSets = new Map<SkillFolder, AsksSkills>();
+
+  private readonly decision = defineDecision(asksSkillDecisionOptions);
+
+  constructor(private readonly options: AsksPluginOptions = {}) {
+    super();
+  }
+
+  override autoDetect(env: PluginEnv): boolean {
+    // The secret too: a deploy before it is set leaves asks off instead of failing the boot.
+    const set = ['ASKS_TOKEN_KEY', 'ORACLE_PUBLIC_URL'].every(
+      (key) => typeof env[key] === 'string' && env[key].length > 0,
+    );
+    if (!set) return false;
+    if (asksMcpUrlOf(env['NETWORK'])) return true;
+    // Never guess a network: the wrong one is the wrong money. No logger here.
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[asks] off: NETWORK is ${typeof env['NETWORK'] === 'string' ? `"${env['NETWORK']}"` : 'not set'}; asks needs mainnet, testnet or devnet`,
+    );
+    return false;
+  }
+
+  private allowed(config: MergedConfig, did: string): boolean {
+    const list = configSchema.parse(config).ASKS_ALLOWED_DIDS;
+    return !list?.trim() || list.split(/[\s,]+/).includes(did);
+  }
+
+  private skillsFor(rtCtx: RuntimeContext): Promise<Skill[]> {
+    const folder = folderOf(rtCtx.config.NETWORK);
+    let set = this.skillSets.get(folder);
+    if (!set) {
+      set = new AsksSkills({
+        folder,
+        fetch: (input, init) => (this.options.fetch ?? fetch)(input, init),
+        now: () => Date.now(),
+        cache: workersSkillCache(),
+        warn: (line) => rtCtx.logger.warn(line),
+      });
+      this.skillSets.set(folder, set);
+    }
+    return set.skills(rtCtx.background);
+  }
+
+  override async getRequestTools(rtCtx: RuntimeContext): Promise<PluginTool[]> {
+    if (!this.allowed(rtCtx.config, rtCtx.user.did)) return [];
+    const config = configSchema.parse(rtCtx.config);
+    const mcpUrl = asksMcpUrlOf(rtCtx.config.NETWORK);
+    if (!mcpUrl) return [];
+    const env = this.options.env ? this.options.env() : await workerEnv();
+    this.keys ??= deriveKeys(config.ASKS_TOKEN_KEY);
+    const objectName = await objectNameOf(await this.keys, rtCtx.user.did);
+    const conn = connectionOf(env, objectName);
+    if (!conn) {
+      rtCtx.logger.warn(
+        '[asks] the ASKS_CONNECTIONS binding is missing: no asks tools',
+      );
+      return [];
+    }
+    await keepTurnFiles(rtCtx).catch((error: unknown) =>
+      rtCtx.logger.warn(
+        `[asks] could not keep this turn's files: ${String(error)}`,
+      ),
+    );
+    return asksTools({
+      ctx: rtCtx,
+      conn,
+      mcpUrl,
+      channelOrigins: channelOriginsOf(env.CHANNEL_SERVICE_DID),
+      skills: await this.skillsFor(rtCtx),
+      connect: this.options.connect ?? connectAsksMcp,
+      fetch: (input, init) => (this.options.fetch ?? fetch)(input, init),
+      now: () => Date.now(),
+    });
+  }
+
+  /** With asks loaded for the turn: the skill the message needs, in the prompt before the first model call. */
+  override async getRequestMiddlewares(
+    rtCtx: RuntimeContext,
+  ): Promise<AgentMiddleware[]> {
+    if (
+      !rtCtx.loadedPlugins.has(this.name) ||
+      !this.allowed(rtCtx.config, rtCtx.user.did)
+    )
+      return [];
+    const skills = await this.skillsFor(rtCtx);
+    let picked: Promise<Skill | null> | null = null;
+    return [
+      createMiddleware({
+        name: 'AsksSkillPreload',
+        wrapModelCall: async (request, handler) => {
+          picked ??= pickSkill(
+            rtCtx.decisions,
+            this.decision,
+            lastHumanText(request.messages),
+            skills,
+            rtCtx.abortSignal,
+          );
+          const skill = await picked;
+          return skill
+            ? handler({
+                ...request,
+                systemMessage: request.systemMessage.concat(preloadText(skill)),
+              })
+            : handler(request);
+        },
+      }),
+    ];
+  }
+
+  override getRoutes(): PluginRoute[] {
+    return asksRoutes();
+  }
+
+  override getAuthExcludedRoutes(): AuthExcludedRoute[] {
+    return asksRoutes().map(({ path }) => ({ path, method: 'GET' as const }));
+  }
+}

package/src/plugins/asks/attach.ts

@@ -0,0 +1,342 @@
+/**
+ * A file the person sent in the chat, streamed from the channel gateway's
+ * media link to the upload address submit_work handed out for an answer
+ * draft (asks `workers/src/draftUploads.ts`, #656: a signed R2 PUT per file).
+ * The bytes never pass through the model, and neither the media link, the
+ * upload address nor the signed URL is ever shown to it.
+ */
+import { sha256 } from '@noble/hashes/sha256';
+import { bytesToHex } from '@noble/hashes/utils';
+
+/** What asks' draft uploads take: PNG, JPG, WebP or PDF, 5 MB each (10 files, 25 MB a draft). */
+export const UPLOAD_TYPES: Readonly<Record<string, string>> = {
+  'image/png': 'png',
+  'image/jpeg': 'jpg',
+  'image/webp': 'webp',
+  'application/pdf': 'pdf',
+};
+export const MAX_UPLOAD_BYTES = 5_000_000;
+
+/** A channel file as the plugin keeps it (the turn's `session.channel.attachments`). */
+export interface KeptFile {
+  url: string;
+  sha256: string;
+  mimetype: string;
+  size: number;
+  filename: string;
+  bindingId: string;
+}
+
+/** The https origins of the gateways named in `CHANNEL_SERVICE_DID` (`did:web:<host>`, comma separated). */
+export function channelOriginsOf(value: unknown): string[] {
+  if (typeof value !== 'string') return [];
+  return value.split(/[\s,]+/).flatMap((did) => {
+    const host = /^did:web:([^:]+)/.exec(did)?.[1];
+    if (!host) return [];
+    try {
+      return [new URL(`https://${decodeURIComponent(host)}`).origin];
+    } catch {
+      return [];
+    }
+  });
+}
+
+/** A file id the way asks names one: letters, digits, `_` and `-`, starting with a letter or digit. */
+export function fileIdOf(name: string): string {
+  const id = name
+    .replace(/\.[^.]*$/, '')
+    .replace(/[^A-Za-z0-9_-]+/g, '-')
+    .replace(/^[-_]+|-+$/g, '')
+    .slice(0, 64);
+  return id || 'file';
+}
+
+/** asks' refusal words, with any link taken out. */
+const scrub = (words: string): string =>
+  words.replace(/https?:\/\/\S+/g, 'the upload address').slice(0, 300);
+
+/* ── asks' upload address (asks #656): sign, PUT to R2, check ───────────────
+ * The only code that talks to it. `<address>` is
+ * `https://{test.}api.asks.world/draft-uploads/du_…/`:
+ *   POST   <address><name>  {type, bytes} → 201 {url, method: "PUT", headers}
+ *   PUT    <url>            the bytes, with exactly the signed headers (R2, 10 minutes)
+ *   GET    <address>        the server's check → {files, refused, missing}
+ *   DELETE <address><name>
+ */
+
+/** A signed PUT asks handed out: always to R2, never anywhere else. */
+export interface SignedPut {
+  url: string;
+  headers: Record<string, string>;
+}
+
+type Refusal = { ok: false; unreachable: boolean; words: string };
+
+const isR2 = (url: string): boolean => {
+  try {
+    const one = new URL(url);
+    return (
+      one.protocol === 'https:' &&
+      !one.username &&
+      one.hostname.endsWith('.r2.cloudflarestorage.com')
+    );
+  } catch {
+    return false;
+  }
+};
+
+async function refusalOf(response: Response): Promise<Refusal> {
+  const answer = (await response.json().catch(() => ({}))) as {
+    words?: unknown;
+    code?: unknown;
+  };
+  return {
+    ok: false,
+    unreachable: response.status >= 500,
+    words:
+      typeof answer.words === 'string'
+        ? answer.words
+        : `asks.world refused it (${String(answer.code ?? response.status)}).`,
+  };
+}
+
+/** Ask asks for a signed PUT for one file of `bytes` bytes. */
+export async function signDraftUpload(
+  fetcher: typeof fetch,
+  address: string,
+  name: string,
+  type: string,
+  bytes: number,
+): Promise<{ ok: true; put: SignedPut } | Refusal> {
+  const response = await fetcher(`${address}${encodeURIComponent(name)}`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ type, bytes }),
+  }).catch(() => null);
+  if (!response)
+    return {
+      ok: false,
+      unreachable: true,
+      words: 'asks.world could not be reached.',
+    };
+  if (!response.ok) return refusalOf(response);
+  const body = (await response.json().catch(() => ({}))) as {
+    url?: unknown;
+    method?: unknown;
+    headers?: unknown;
+  };
+  const headers = body.headers as Record<string, unknown> | undefined;
+  if (
+    typeof body.url !== 'string' ||
+    !isR2(body.url) ||
+    (body.method ?? 'PUT') !== 'PUT' ||
+    !headers ||
+    typeof headers !== 'object' ||
+    !Object.values(headers).every((one) => typeof one === 'string')
+  )
+    return {
+      ok: false,
+      unreachable: false,
+      words: 'asks.world gave an upload link this chat does not use.',
+    };
+  return {
+    ok: true,
+    put: { url: body.url, headers: headers as Record<string, string> },
+  };
+}
+
+/** Stream the bytes to the signed URL, with exactly its headers. */
+export async function putSigned(
+  fetcher: typeof fetch,
+  put: SignedPut,
+  body: ReadableStream<Uint8Array>,
+  bytes: number,
+): Promise<{ ok: true } | Refusal> {
+  // Workers send a stream with a Content-Length only through a FixedLengthStream.
+  const Fixed = (
+    globalThis as {
+      FixedLengthStream?: new (
+        length: number,
+      ) => TransformStream<Uint8Array, Uint8Array>;
+    }
+  ).FixedLengthStream;
+  const response = await fetcher(put.url, {
+    method: 'PUT',
+    headers: put.headers,
+    body: Fixed ? body.pipeThrough(new Fixed(bytes)) : body,
+  }).catch(() => null);
+  if (!response)
+    return {
+      ok: false,
+      unreachable: true,
+      words: 'The upload did not finish.',
+    };
+  // R2's own error is XML, nothing to show.
+  return response.ok
+    ? { ok: true }
+    : {
+        ok: false,
+        unreachable: false,
+        words: `The upload was refused (${response.status}).`,
+      };
+}
+
+export async function removeDraftUpload(
+  fetcher: typeof fetch,
+  address: string,
+  name: string,
+): Promise<void> {
+  await fetcher(`${address}${encodeURIComponent(name)}`, {
+    method: 'DELETE',
+  }).catch(() => undefined);
+}
+
+/** asks' own check of what landed: the names it refused and the file ids still missing. */
+export async function checkDraftUploads(
+  fetcher: typeof fetch,
+  address: string,
+): Promise<
+  | { ok: true; kept: string[]; refused: string[]; missing: string[] }
+  | { ok: false }
+> {
+  const response = await fetcher(address, {
+    headers: { accept: 'application/json' },
+  }).catch(() => null);
+  if (!response?.ok) return { ok: false };
+  const body = (await response.json().catch(() => null)) as {
+    files?: unknown;
+    refused?: unknown;
+    missing?: unknown;
+  } | null;
+  if (!body) return { ok: false };
+  // Names and ids only, and only ones shaped like a file name: nothing else reaches the model.
+  const names = (list: unknown, pick: (one: unknown) => unknown): string[] =>
+    (Array.isArray(list) ? list : [])
+      .map(pick)
+      .filter(
+        (one): one is string =>
+          typeof one === 'string' &&
+          /^[A-Za-z0-9][A-Za-z0-9_.-]{0,80}$/.test(one),
+      )
+      .slice(0, 12);
+  const named = (one: unknown) => (one as { name?: unknown } | null)?.name;
+  return {
+    ok: true,
+    kept: names(body.files, named),
+    refused: names(body.refused, named),
+    missing: names(body.missing, (one) => one),
+  };
+}
+
+export async function sendFile(input: {
+  file: KeptFile;
+  /** The file id the answer expects; else one made from the file's name. */
+  name?: string;
+  address: string;
+  origins: readonly string[];
+  fetch: typeof fetch;
+}): Promise<{ ok: true; as: string } | { ok: false; why: string }> {
+  const { file, address } = input;
+  const ext = UPLOAD_TYPES[file.mimetype.toLowerCase()];
+  if (!ext)
+    return {
+      ok: false,
+      why: `Asks takes PNG, JPG, WebP or PDF files; this one is ${file.mimetype}.`,
+    };
+  if (file.size > MAX_UPLOAD_BYTES)
+    return {
+      ok: false,
+      why: 'Asks takes files up to 5 MB; this one is bigger.',
+    };
+  let source: URL;
+  try {
+    source = new URL(file.url);
+  } catch {
+    return { ok: false, why: "The chat's copy of that file can't be read." };
+  }
+  if (
+    !input.origins.includes(source.origin) ||
+    !source.pathname.startsWith(`/media/${file.bindingId}/`)
+  ) {
+    return {
+      ok: false,
+      why: "That file isn't one the chat gateway keeps, so it was not sent.",
+    };
+  }
+
+  const fetched = await input
+    .fetch(source.toString(), { redirect: 'manual' })
+    .catch(() => null);
+  if (!fetched?.ok || !fetched.body) {
+    return {
+      ok: false,
+      why: "The chat's copy of that file can't be read any more (links last 30 days).",
+    };
+  }
+  // asks signs for an exact size: the gateway's own length must agree with it.
+  const length = fetched.headers.get('content-length');
+  if (length !== null && Number(length) !== file.size) {
+    await fetched.body.cancel().catch(() => undefined);
+    return {
+      ok: false,
+      why: 'The file changed on its way from the chat, so it was not attached.',
+    };
+  }
+  const hash = sha256.create();
+  let bytes = 0;
+  const meter = new TransformStream<Uint8Array, Uint8Array>({
+    transform(chunk, controller) {
+      bytes += chunk.byteLength;
+      if (bytes > file.size) {
+        controller.error(new Error('larger than the gateway said'));
+        return;
+      }
+      hash.update(chunk);
+      controller.enqueue(chunk);
+    },
+  });
+
+  const as = `${input.name ?? fileIdOf(file.filename)}.${ext}`;
+  const signed = await signDraftUpload(
+    input.fetch,
+    address,
+    as,
+    file.mimetype.toLowerCase(),
+    file.size,
+  );
+  if (!signed.ok) {
+    await fetched.body.cancel().catch(() => undefined);
+    return {
+      ok: false,
+      why: signed.unreachable
+        ? 'asks.world could not be reached, so the file was not attached. Try again in a minute.'
+        : scrub(signed.words),
+    };
+  }
+  const put = await putSigned(
+    input.fetch,
+    signed.put,
+    fetched.body.pipeThrough(meter),
+    file.size,
+  );
+  if (!put.ok && put.unreachable) {
+    return bytes > file.size
+      ? {
+          ok: false,
+          why: 'The file changed on its way from the chat, so it was not attached.',
+        }
+      : {
+          ok: false,
+          why: 'asks.world could not be reached, so the file was not attached. Try again in a minute.',
+        };
+  }
+  if (!put.ok) return { ok: false, why: scrub(put.words) };
+  if (bytes !== file.size || bytesToHex(hash.digest()) !== file.sha256) {
+    await removeDraftUpload(input.fetch, address, as);
+    return {
+      ok: false,
+      why: 'The file changed on its way from the chat, so it was taken off again.',
+    };
+  }
+  return { ok: true, as };
+}

package/src/plugins/asks/connection-do.ts

@@ -0,0 +1,69 @@
+import { DurableObject } from 'cloudflare:workers';
+import { AsksConnection, type AsksWorkerEnv, type Surface } from './connection';
+import { asksMcpUrlOf } from './oauth';
+
+/**
+ * One per person, named HMAC(ASKS_TOKEN_KEY, user DID). Reached from the
+ * user's own object (the tools) and from the shell (the sign-in routes), so
+ * the tokens live here rather than in either of them. RPC methods only.
+ */
+export class AsksConnectionDO extends DurableObject<AsksWorkerEnv> {
+  private readonly connection: AsksConnection;
+
+  constructor(ctx: DurableObjectState, env: AsksWorkerEnv) {
+    super(ctx, env);
+    const { ORACLE_PUBLIC_URL, ASKS_TOKEN_KEY } = env;
+    const mcpUrl = asksMcpUrlOf(env.NETWORK);
+    if (!mcpUrl || !ORACLE_PUBLIC_URL || !ASKS_TOKEN_KEY) {
+      throw new Error(
+        'asks: NETWORK (mainnet, testnet or devnet), ORACLE_PUBLIC_URL and ASKS_TOKEN_KEY are required',
+      );
+    }
+    this.connection = new AsksConnection({
+      storage: ctx.storage,
+      config: {
+        mcpUrl,
+        publicUrl: ORACLE_PUBLIC_URL,
+        tokenKey: ASKS_TOKEN_KEY,
+      },
+      fetch: (input, init) => fetch(input, init),
+      now: () => Date.now(),
+    });
+  }
+
+  begin(did: string, surface: Surface) {
+    return this.connection.begin(did, surface);
+  }
+
+  authorizeUrl(state: string) {
+    return this.connection.authorizeUrl(state);
+  }
+
+  complete(state: string, code: string) {
+    return this.connection.complete(state, code);
+  }
+
+  status() {
+    return this.connection.status();
+  }
+
+  token() {
+    return this.connection.token();
+  }
+
+  refused(access: string) {
+    return this.connection.refused(access);
+  }
+
+  disconnect() {
+    return this.connection.disconnect();
+  }
+
+  keepUpload(draft: string, address: string, expiresAt: number) {
+    return this.connection.keepUpload(draft, address, expiresAt);
+  }
+
+  uploadOf(draft: string) {
+    return this.connection.uploadOf(draft);
+  }
+}