@ixo/oracle-runtime-workers 0.13.0 → 0.16.0

package/src/do/sse-stream.ts

@@ -20,11 +20,14 @@
  * that reconnects can ask for `?after=<id>`.
  */
 import {
+  BYO_FALLBACK_KIND,
   classifyLlmError,
   isOperatorFault,
   redactOperatorFault,
 } from '../llm/provider-error';
+import { reportsUnknownOutcome } from '@ixo/common/ai/frontend-bridge';
 import { type AIMessageChunk, ToolMessage } from '@langchain/core/messages';
+import { harnessLimitOf, type HarnessLimitError } from '../core/turn-budget';
 import { RunBuffer, type RunFrame } from './run-buffer';
 
 /** Where the producer puts frames — a `RunBuffer`, or a test sink. */
@@ -303,6 +306,32 @@ export async function runTurnFrames(
     ...(input.runId ? { runId: input.runId } : {}),
   });
 
+  // The turn hit its budget (tokens, tool attempts, deadline): the abort
+  // was the harness's, not the user's, so the client gets a terminal
+  // `error` naming the limit before `done` — not a silent "aborted".
+  const limitFailure = (limit: HarnessLimitError) => {
+    flushOrphans();
+    write('reasoning', {
+      sessionId,
+      requestId,
+      reasoning: '',
+      isComplete: true,
+      timestamp: new Date().toISOString(),
+    });
+    write('error', {
+      error: limit.message,
+      kind: limit.kind,
+      limit: limit.limit,
+      source: 'platform',
+      retryable: false,
+      sessionId,
+      requestId,
+      timestamp: new Date().toISOString(),
+    });
+    doneFrame({ failed: true });
+    return { status: 'failed' as const, fullText: fullContent, error: limit };
+  };
+
   const flushOrphans = () => {
     for (const evt of actionCallMap.values()) {
       write('action_call', {
@@ -362,6 +391,15 @@ export async function runTurnFrames(
         metadata?: Record<string, unknown>;
         tags?: string[];
       };
+      if (evt.event === 'on_custom_event' && evt.name === BYO_FALLBACK_KIND) {
+        // A BYO model the provider refused mid-turn (byo-model-fallback.ts):
+        // the same `error`-channel notice the pre-turn fallbacks send, in
+        // stream order — ahead of the platform model's reply to that call.
+        const notice = evt.data;
+        if (notice && typeof notice === 'object')
+          write('error', { ...notice, sessionId, requestId });
+        continue;
+      }
       if (evt.event === 'on_chat_model_end') {
         if (isInternalModelEvent(evt)) continue;
         const output = (evt.data as { output?: AIMessageChunk })?.output;
@@ -441,7 +479,12 @@ export async function runTurnFrames(
         const action = actionCallMap.get(evt.run_id);
         if (action) {
           const parsed = safeParseToolContent(output?.content);
-          const failed = parsed?.success === false || Boolean(parsed?.error);
+          // An unknown outcome (FRONTEND_OUTCOME_UNKNOWN) is not a failure:
+          // the action may have run, so the client must not offer a retry.
+          // It ends as `done` with the unknown result as its output.
+          const failed =
+            !reportsUnknownOutcome(parsed) &&
+            (parsed?.success === false || Boolean(parsed?.error));
           write('action_call', {
             ...action,
             output: text,
@@ -579,19 +622,25 @@ export async function runTurnFrames(
       doneFrame();
       return { status: 'completed', fullText: fullContent };
     }
+    const reasonLimit = harnessLimitOf(abortController.signal.reason);
+    if (reasonLimit) return limitFailure(reasonLimit);
     // Aborted (POST /messages/abort, or superseded): close the stream
     // cleanly so the UI leaves its "thinking" state.
     flushOrphans();
     doneFrame({ aborted: true });
     return { status: 'aborted', fullText: fullContent };
   } catch (error) {
-    // The run's signal is the authority: LangGraph rethrows the signal's
-    // reason (whatever the aborter passed), not always an `AbortError`.
-    const aborted =
-      abortController.signal.aborted ||
-      (error instanceof Error &&
-        (error.name === 'AbortError' || /abort/i.test(error.message)));
-    if (aborted) {
+    // A limit reaches here wrapped by LangChain's middleware layers; the
+    // original carries the `limit` the client is told about.
+    const limit =
+      harnessLimitOf(error) ?? harnessLimitOf(abortController.signal.reason);
+    if (limit) return limitFailure(limit);
+    // The run's signal is the only authority: LangGraph rethrows the
+    // signal's reason (whatever the aborter passed), not always an
+    // `AbortError`, while an `AbortError` or "aborted" message with the
+    // signal untouched is a provider or tool timing out — a failure the
+    // client must see as one.
+    if (abortController.signal.aborted) {
       flushOrphans();
       doneFrame({ aborted: true });
       return { status: 'aborted', fullText: fullContent };
@@ -686,7 +735,9 @@ export function createSseSubscriberStream(
       for (const frame of input.replay) write(frame);
       if (closed) return;
       if (input.buffer && !input.buffer.isClosed) {
-        unsubscribe = input.buffer.subscribe(write);
+        // A buffer that closes without a `done` (it never should) still
+        // ends the response instead of leaving it on heartbeats.
+        unsubscribe = input.buffer.subscribe(write, finish);
       } else {
         if (input.trailer)
           write({

package/src/do/transcript.ts

@@ -13,6 +13,13 @@ import {
   isAttachmentViewMessage,
 } from '../attachments/retention';
 import { SUMMARY_PREFIX } from '../core/middlewares/summarization';
+import {
+  stripTurnTimeNote,
+  TURN_TIME_NOTE_KWARG,
+} from '../core/turn-time-note';
+import { ChannelOrigin } from '../channels/contract';
+import { CREATE_ARTIFACT_TOOL, createArtifactParts } from '../artifacts/tool';
+import { planText } from '../delivery/schema';
 import type {
   ThreadMessageAnchor,
   ThreadMessageRow,
@@ -45,6 +52,7 @@ export interface MessageDto {
   isReasoning?: boolean;
   attachment?: AttachmentMeta;
   attachments?: AttachmentMeta[];
+  metadata?: { 'org.ixo.qi.origin': ChannelOrigin };
 }
 
 export interface ListMessagesResponse {
@@ -108,6 +116,25 @@ export function contentToText(content: BaseMessage['content']): string {
   return String(content);
 }
 
+/**
+ * A stored message's content as a person (or a service acting for one)
+ * reads it: a user message loses the "current time" note the model was
+ * given with it, when it still starts with exactly the note recorded on it.
+ * Every other message is returned as stored.
+ */
+export function visibleContent(message: BaseMessage): BaseMessage['content'] {
+  if (message.type !== 'human') return message.content;
+  return stripTurnTimeNote(
+    message.content,
+    message.additional_kwargs?.[TURN_TIME_NOTE_KWARG],
+  );
+}
+
+/** `visibleContent` as text (titles, mirrors, indexing). */
+export function visibleText(message: BaseMessage): string {
+  return contentToText(visibleContent(message));
+}
+
 /**
  * The summarization middleware's bookkeeping message — never shown to users.
  * LangChain 1.4 writes it as a HUMAN message tagged
@@ -132,6 +159,9 @@ export async function transformTranscript(
   messages: BaseMessage[],
 ): Promise<ListMessagesResponse> {
   const acc: MessageDto[] = [];
+  // The first listed reply that made each tool call: a tool result folds
+  // into it (looked up, not searched, so long transcripts stay linear).
+  const callers = new Map<string, MessageDto>();
   for (const message of messages) {
     const toolMsg = message.type === 'tool' ? (message as ToolMessage) : null;
     const kw = (message.additional_kwargs ?? {}) as Record<string, unknown>;
@@ -152,7 +182,7 @@ export async function transformTranscript(
             (kw.attachment ? [kw.attachment as AttachmentMeta] : undefined))
           : undefined;
       const attachment = attachments?.[0];
-      const textContent = contentToText(message.content);
+      const textContent = visibleText(message);
       const toolCalls = (message as AIMessage).tool_calls;
       const dto: MessageDto = {
         type: message.type === 'ai' ? 'ai' : 'human',
@@ -175,7 +205,13 @@ export async function transformTranscript(
       if (reasoning) dto.reasoning = reasoning;
       if (attachment) dto.attachment = attachment;
       if (attachments?.length) dto.attachments = attachments;
+      if (message.type === 'human') {
+        const origin = ChannelOrigin.safeParse(kw['org.ixo.qi.origin']);
+        if (origin.success) dto.metadata = { 'org.ixo.qi.origin': origin.data };
+      }
       acc.push(dto);
+      for (const call of dto.toolCalls ?? [])
+        if (!callers.has(call.id)) callers.set(call.id, dto);
     }
 
     if (toolMsg) {
@@ -188,11 +224,18 @@ export async function transformTranscript(
         toolMsg.tool_call_id ??
         kwargs?.tool_call_id ??
         (await uuidFromString(JSON.stringify(kwargs?.args)));
-      const idx = acc.findIndex((m) =>
-        m.toolCalls?.some((t) => t.id === toolCallId),
-      );
-      const el = idx !== -1 ? acc[idx] : undefined;
+      const el = callers.get(toolCallId);
       if (el) {
+        // A chat reply that ended in `create_artifact` wrote no text of its
+        // own: list what the user received, the message, link and question.
+        const call = el.toolCalls?.find((t) => t.id === toolCallId);
+        if (call?.name === CREATE_ARTIFACT_TOOL && !el.content.trim())
+          el.content = planText({
+            parts: createArtifactParts(
+              call.args,
+              contentToText(toolMsg.content),
+            ),
+          });
         el.toolCalls = el.toolCalls?.map((t) =>
           t.id === toolCallId
             ? {

package/src/do/turn-body.ts

@@ -64,7 +64,34 @@ const reject = (message: string): ParsedTurnBody => ({
   message,
 });
 
-/** Parse and validate a raw request body. Never throws. */
+type ToolDeclaration = NonNullable<TurnBody['tools']>[number];
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/** A client-declared tool (or AG-UI action): name, description, schema. */
+function toolDeclaration(value: unknown): ToolDeclaration | null {
+  if (
+    !isRecord(value) ||
+    typeof value.name !== 'string' ||
+    typeof value.description !== 'string' ||
+    !isRecord(value.schema)
+  )
+    return null;
+  return {
+    name: value.name,
+    description: value.description,
+    schema: value.schema,
+  };
+}
+
+/**
+ * Parse and validate a raw request body. Never throws. Every field the
+ * runtime reads is checked for its type here, so a wrong one is a 400 and
+ * not a failed turn later; the accepted fields the runtime ignores
+ * (`homeServer`, `mcpInvocations`, `requestId`) are not passed on.
+ */
 export function parseTurnBody(raw: string): ParsedTurnBody {
   let parsed: unknown;
   try {
@@ -72,17 +99,23 @@ export function parseTurnBody(raw: string): ParsedTurnBody {
   } catch {
     return reject('Invalid JSON body');
   }
-  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+  if (!isRecord(parsed)) {
     return reject('Request body must be a JSON object');
   }
-  const record = parsed as Record<string, unknown>;
-  const unknownProp = Object.keys(record).find((k) => !TURN_BODY_KEYS.has(k));
+  const unknownProp = Object.keys(parsed).find((k) => !TURN_BODY_KEYS.has(k));
   if (unknownProp !== undefined) {
     return reject(`property ${unknownProp} should not exist`);
   }
+  // A field sent as `null` is a field not sent (clients serialise unset
+  // optionals either way).
+  const record = Object.fromEntries(
+    Object.entries(parsed).filter(([, value]) => value !== null),
+  );
   if (typeof record.message !== 'string' || record.message.length === 0) {
     return reject('message is required');
   }
+  const { stream, returnAllMessages, timezone, model, metadata, attachments } =
+    record;
   if (
     record.multitask !== undefined &&
     record.multitask !== 'interrupt' &&
@@ -90,5 +123,72 @@ export function parseTurnBody(raw: string): ParsedTurnBody {
   ) {
     return reject('multitask must be one of: interrupt, enqueue');
   }
-  return { ok: true, body: record as unknown as TurnBody };
+  for (const [name, value] of [
+    ['stream', stream],
+    ['returnAllMessages', returnAllMessages],
+  ] as const)
+    if (value !== undefined && typeof value !== 'boolean')
+      return reject(`${name} must be a boolean`);
+  for (const [name, value] of [
+    ['timezone', timezone],
+    ['model', model],
+    ['homeServer', record.homeServer],
+    ['requestId', record.requestId],
+  ] as const)
+    if (value !== undefined && typeof value !== 'string')
+      return reject(`${name} must be a string`);
+  if (metadata !== undefined && !isRecord(metadata))
+    return reject('metadata must be an object');
+  if (attachments !== undefined && !Array.isArray(attachments))
+    return reject('attachments must be an array');
+  let tools: ToolDeclaration[] | undefined;
+  if (record.tools !== undefined) {
+    if (!Array.isArray(record.tools)) return reject('tools must be an array');
+    tools = [];
+    for (const item of record.tools) {
+      const tool = toolDeclaration(item);
+      if (!tool)
+        return reject(
+          'each tool needs a string name, description and an object schema',
+        );
+      tools.push(tool);
+    }
+  }
+  let agActions: NonNullable<TurnBody['agActions']> | undefined;
+  if (record.agActions !== undefined) {
+    if (!Array.isArray(record.agActions))
+      return reject('agActions must be an array');
+    agActions = [];
+    for (const item of record.agActions) {
+      const action = toolDeclaration(item);
+      const hasRender = isRecord(item) ? item.hasRender : undefined;
+      if (
+        !action ||
+        (hasRender !== undefined && typeof hasRender !== 'boolean')
+      )
+        return reject(
+          'each agAction needs a string name, description and an object schema',
+        );
+      agActions.push(
+        hasRender === undefined ? action : { ...action, hasRender },
+      );
+    }
+  }
+  return {
+    ok: true,
+    body: {
+      message: record.message,
+      ...(typeof stream === 'boolean' ? { stream } : {}),
+      ...(record.multitask === 'interrupt' || record.multitask === 'enqueue'
+        ? { multitask: record.multitask }
+        : {}),
+      ...(typeof returnAllMessages === 'boolean' ? { returnAllMessages } : {}),
+      ...(typeof timezone === 'string' ? { timezone } : {}),
+      ...(typeof model === 'string' ? { model } : {}),
+      ...(isRecord(metadata) ? { metadata } : {}),
+      ...(tools ? { tools } : {}),
+      ...(agActions ? { agActions } : {}),
+      ...(Array.isArray(attachments) ? { attachments } : {}),
+    },
+  };
 }

package/src/do/ucan-service.ts

@@ -17,6 +17,11 @@ import {
   signerFromMnemonic,
   type SupportedDID,
 } from '@ixo/ucan';
+import {
+  abilityCovers,
+  delegationHasCapability,
+  resourceCovers,
+} from '../core/runtime-context';
 import type { RuntimeContext, UcanDelegation } from '../plugin-api/types';
 
 type MintResult = { invocation: string } | { error: string };
@@ -28,24 +33,18 @@ export interface UcanServiceOptions {
   oracleDid: string;
   signingMnemonic?: string;
   logger?: { warn(msg: string): void; debug?(msg: string): void };
+  /** Longest a did.json or UCAN store request may take (default 10 s). */
+  fetchTimeoutMs?: number;
 }
 
+const DEFAULT_FETCH_TIMEOUT_MS = 10_000;
+
 function toSupportedDid(did: string): SupportedDID {
   if (did.startsWith('did:ixo:') || did.startsWith('did:key:'))
     return did as SupportedDID;
   throw new Error(`Unsupported oracle DID method: ${did}`);
 }
 
-/** Does a granted ability (`*`, `ns/*`, or an exact ability) cover `required`? */
-export function abilityCovers(granted: string, required: string): boolean {
-  if (granted === '*' || granted === required) return true;
-  if (granted.endsWith('/*')) {
-    const ns = granted.slice(0, -2);
-    return required === ns || required.startsWith(`${ns}/`);
-  }
-  return false;
-}
-
 /** One capability of a delegation, as the wire carries it. */
 export interface DelegatedCapability {
   can: string;
@@ -61,14 +60,86 @@ export interface DelegatedCapability {
 export async function listDelegationCapabilities(
   delegationCar: string,
 ): Promise<DelegatedCapability[]> {
+  return (await readDelegation(delegationCar)).capabilities;
+}
+
+/** What a serialized delegation grants and the window in which it grants it. */
+export interface DelegationGrant {
+  capabilities: DelegatedCapability[];
+  /** Unix seconds: the earliest expiry along the proof chain; absent = none declared. */
+  expiration?: number;
+  /** Unix seconds: the latest `nbf` along the proof chain; absent = none declared. */
+  notBefore?: number;
+}
+
+/** A finite number read off a parsed UCAN field, else undefined. */
+function finiteField(node: object, field: 'expiration' | 'notBefore') {
+  const value: unknown = Reflect.get(node, field);
+  return typeof value === 'number' && Number.isFinite(value)
+    ? value
+    : undefined;
+}
+
+/**
+ * The validity window of a delegation and the proofs it carries, along the
+ * first proof at each level — the chain the UCAN validator's effective expiry
+ * follows. A proof carried only as a link (not embedded) has no fields to read.
+ */
+function chainWindow(node: unknown): {
+  expiration?: number;
+  notBefore?: number;
+} {
+  if (typeof node !== 'object' || node === null) return {};
+  const own = {
+    expiration: finiteField(node, 'expiration'),
+    notBefore: finiteField(node, 'notBefore'),
+  };
+  const proofs: unknown = Reflect.get(node, 'proofs');
+  const parent = Array.isArray(proofs) ? chainWindow(proofs[0]) : {};
+  const pick = (
+    a: number | undefined,
+    b: number | undefined,
+    f: (x: number, y: number) => number,
+  ) => (a === undefined ? b : b === undefined ? a : f(a, b));
+  const expiration = pick(own.expiration, parent.expiration, Math.min);
+  const notBefore = pick(own.notBefore, parent.notBefore, Math.max);
+  return {
+    ...(expiration !== undefined ? { expiration } : {}),
+    ...(notBefore !== undefined ? { notBefore } : {}),
+  };
+}
+
+/** Parse a serialized delegation into its grant (no signature checks). */
+export async function readDelegation(
+  delegationCar: string,
+): Promise<DelegationGrant> {
   const delegation = await parseDelegation(delegationCar);
-  return delegation.capabilities.map((c) => ({
-    can: c.can,
-    with: c.with,
-    ...(c.nb !== undefined && c.nb !== null
-      ? { nb: c.nb as Record<string, unknown> }
-      : {}),
-  }));
+  return {
+    capabilities: delegation.capabilities.map((c) => ({
+      can: c.can,
+      with: c.with,
+      ...(c.nb !== undefined && c.nb !== null
+        ? { nb: c.nb as Record<string, unknown> }
+        : {}),
+    })),
+    ...chainWindow(delegation),
+  };
+}
+
+/**
+ * The delegation a turn runs under: the one the request carried, else the
+ * user's stored one (a Matrix turn carries none), with the capabilities it
+ * grants (`withCapabilities`). Every capability check of the turn reads it:
+ * `requires`, admin-plane tools, the plugins' own mints. Without a UCAN
+ * service it carries no capabilities and grants nothing.
+ */
+export async function resolveTurnDelegation(
+  requestDelegation: string | undefined,
+  storedDelegation: string | undefined,
+  ucan: Pick<WorkersUcanService, 'withCapabilities'> | null,
+): Promise<UcanDelegation> {
+  const raw = requestDelegation ?? storedDelegation ?? '';
+  return ucan ? ucan.withCapabilities(raw) : { raw };
 }
 
 /** Upper bound on a delegated invocation's lifetime (mirrors the Node runtime). */
@@ -85,27 +156,107 @@ export class WorkersUcanService {
     string,
     { value: { token: string; with: string }; expiresAt: number }
   >();
-  private readonly capabilitiesCache = new Map<string, DelegatedCapability[]>();
+  /**
+   * Store look-ups in progress, keyed like `storeDelegationCache`: callers
+   * that miss the cache at the same moment share one fetch. Dropped when it
+   * settles, so a failed look-up is retried by the next call.
+   */
+  private readonly storeDelegationInFlight = new Map<
+    string,
+    Promise<ServiceDelegationResult>
+  >();
+  /** Parsed grants per raw delegation; the validity window is checked at use, never cached away. */
+  private readonly grantCache = new Map<string, DelegationGrant>();
 
   constructor(private readonly opts: UcanServiceOptions) {}
 
+  /**
+   * A raw delegation with the capabilities it grants, the shape
+   * `ctx.ucan.hasCapability` and plugin `requires` read. A token that cannot
+   * be parsed grants nothing, and neither does one outside its validity
+   * window right now: expired, or not yet valid (`nbf`). The window is
+   * compared with the clock on every call — the parse is cached, the
+   * verdict is not — and the result carries `expiration`, so a delegation
+   * that lapses during the turn stops granting at that moment too. The
+   * stored delegation a Matrix turn runs under was validated only when it
+   * was deposited; this is what ends it.
+   */
+  async withCapabilities(raw: string): Promise<UcanDelegation> {
+    if (!raw) return { raw };
+    let grant: DelegationGrant;
+    try {
+      grant = await this.delegationGrant(raw);
+    } catch (err) {
+      this.opts.logger?.warn(
+        `[UCAN] cannot read a delegation's capabilities: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      return { raw, capabilities: [] };
+    }
+    const nowSeconds = Date.now() / 1000;
+    const lapsed =
+      grant.expiration !== undefined && grant.expiration <= nowSeconds;
+    const early = grant.notBefore !== undefined && grant.notBefore > nowSeconds;
+    if (lapsed || early) {
+      this.opts.logger?.warn(
+        lapsed
+          ? `[UCAN] the delegation expired at ${new Date((grant.expiration ?? 0) * 1000).toISOString()}; it grants nothing`
+          : `[UCAN] the delegation is not valid before ${new Date((grant.notBefore ?? 0) * 1000).toISOString()}; it grants nothing yet`,
+      );
+      return {
+        raw,
+        capabilities: [],
+        ...(grant.expiration !== undefined
+          ? { expiration: grant.expiration }
+          : {}),
+      };
+    }
+    return {
+      raw,
+      capabilities: grant.capabilities.map((c) => ({
+        resource: c.with,
+        action: c.can,
+      })),
+      ...(grant.expiration !== undefined
+        ? { expiration: grant.expiration }
+        : {}),
+    };
+  }
+
   hasSigningKey(): boolean {
     return Boolean(this.opts.signingMnemonic);
   }
 
-  /** `listDelegationCapabilities`, memoised on the raw token. */
+  /**
+   * `listDelegationCapabilities`, memoised on the raw token. No validity
+   * window: the owner store picks the grant to mint from with it, and the
+   * mint refuses an expired delegation itself.
+   */
   async delegationCapabilities(
     delegationCar: string,
   ): Promise<DelegatedCapability[]> {
-    const cached = this.capabilitiesCache.get(delegationCar);
+    return (await this.delegationGrant(delegationCar)).capabilities;
+  }
+
+  /** `readDelegation`, memoised on the raw token. */
+  private async delegationGrant(
+    delegationCar: string,
+  ): Promise<DelegationGrant> {
+    const cached = this.grantCache.get(delegationCar);
     if (cached) return cached;
-    const capabilities = await listDelegationCapabilities(delegationCar);
-    if (this.capabilitiesCache.size >= DELEGATION_CAPABILITIES_CACHE_SIZE) {
-      const oldest = this.capabilitiesCache.keys().next().value;
-      if (oldest !== undefined) this.capabilitiesCache.delete(oldest);
+    const grant = await readDelegation(delegationCar);
+    if (this.grantCache.size >= DELEGATION_CAPABILITIES_CACHE_SIZE) {
+      const oldest = this.grantCache.keys().next().value;
+      if (oldest !== undefined) this.grantCache.delete(oldest);
     }
-    this.capabilitiesCache.set(delegationCar, capabilities);
-    return capabilities;
+    this.grantCache.set(delegationCar, grant);
+    return grant;
+  }
+
+  /** Bounds one outbound request (headers and body). */
+  private fetchSignal(): AbortSignal {
+    return AbortSignal.timeout(
+      this.opts.fetchTimeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS,
+    );
   }
 
   async resolveServiceDid(serviceUrl: string): Promise<string | null> {
@@ -113,7 +264,9 @@ export class WorkersUcanService {
       const origin = new URL(serviceUrl).origin;
       const cached = this.serviceDidCache.get(origin);
       if (cached && cached.expiresAt > Date.now()) return cached.did;
-      const res = await fetch(`${origin}/.well-known/did.json`);
+      const res = await fetch(`${origin}/.well-known/did.json`, {
+        signal: this.fetchSignal(),
+      });
       if (!res.ok) {
         this.opts.logger?.warn(`[UCAN] did.json ${origin}: HTTP ${res.status}`);
         return null;
@@ -265,7 +418,23 @@ export class WorkersUcanService {
     const cacheKey = `${userDid}:${opts.resource}:${opts.requiredAbility}`;
     const cached = this.storeDelegationCache.get(cacheKey);
     if (cached && cached.expiresAt > Date.now()) return cached.value;
+    const pending = this.storeDelegationInFlight.get(cacheKey);
+    if (pending) return pending;
+    const lookup = this.fetchServiceDelegation(userDid, opts, cacheKey).finally(
+      () => {
+        if (this.storeDelegationInFlight.get(cacheKey) === lookup)
+          this.storeDelegationInFlight.delete(cacheKey);
+      },
+    );
+    this.storeDelegationInFlight.set(cacheKey, lookup);
+    return lookup;
+  }
 
+  private async fetchServiceDelegation(
+    userDid: string,
+    opts: { storeUrl: string; resource: string; requiredAbility: string },
+    cacheKey: string,
+  ): Promise<ServiceDelegationResult> {
     const inv = await this.mintSelfSignedInvocation(
       opts.storeUrl,
       { can: 'store/get', with: 'ixo:ucan-store' },
@@ -288,6 +457,8 @@ export class WorkersUcanService {
             authorization: `Bearer ${inv.invocation}`,
             'x-auth-type': 'ucan',
           },
+          // Every caller waiting on this look-up waits on this request.
+          signal: this.fetchSignal(),
         },
       );
     } catch (error) {
@@ -313,9 +484,13 @@ export class WorkersUcanService {
     for (const row of body.delegations ?? []) {
       if (row.lifecycleState !== 'active') continue;
       if (row.expiresAt != null && row.expiresAt <= nowSeconds) continue;
+      // The stored grant must cover what was asked for: the same resource
+      // or a parent of it (never a sibling sharing a prefix, never a
+      // narrower grant standing in for the broader resource), with an
+      // ability that covers the required one.
       const match = (row.capabilities ?? []).find(
         (c) =>
-          (c.with === opts.resource || c.with.startsWith(opts.resource)) &&
+          resourceCovers(c.with, opts.resource) &&
           abilityCovers(c.can, opts.requiredAbility),
       );
       if (!match) continue;
@@ -341,13 +516,8 @@ export class WorkersUcanService {
     userDid: string,
     delegation: UcanDelegation | undefined,
   ): RuntimeContext['ucan'] {
-    const caps = delegation?.capabilities ?? [];
     const has = (resource: string, action: string) =>
-      caps.some(
-        (c) =>
-          (c.resource === resource || c.resource.startsWith(resource)) &&
-          abilityCovers(c.action, action),
-      );
+      delegationHasCapability(delegation, resource, action);
     return {
       hasCapability: has,
       requireCapability: (resource, action) => {