@ixo/oracle-runtime-workers 0.39.0 → 0.40.1

package/src/core/middlewares/tool-repetition-guard.ts

@@ -20,6 +20,28 @@ export interface RepetitionCaps {
 
 export const DEFAULT_REPETITION_CAPS: RepetitionCaps = { reads: 5, writes: 1 };
 
+/**
+ * Tools that only find other tools; a model alternating between them never trips the identical-call cap.
+ * `load_capability` is not one: it is how a gated tool becomes callable.
+ */
+export const DISCOVERY_TOOL_NAMES: ReadonlySet<string> = new Set([
+  'list_capabilities',
+  'list_skills',
+  'search_skills',
+]);
+
+function discoveryCallsInTurn(messages: readonly BaseMessage[]): number {
+  let count = 0;
+  for (let i = turnStart(messages); i < messages.length; i++) {
+    const msg = messages[i];
+    if (msg instanceof ToolMessage && DISCOVERY_TOOL_NAMES.has(msg.name ?? ''))
+      count += 1;
+  }
+  return count;
+}
+/** Discovery calls a turn may make, whatever their arguments. */
+export const MAX_DISCOVERY_CALLS = 6;
+
 /**
  * Parse `TURN_MAX_IDENTICAL_READS` / `TURN_MAX_IDENTICAL_WRITES`; anything
  * that is not a positive number keeps its default (as `turnLimitsFromEnv`).
@@ -99,6 +121,18 @@ export const createToolRepetitionGuardMiddleware = (
 
   return createMiddleware({
     name: 'ToolRepetitionGuardMiddleware',
+    // A model can keep calling a refused tool forever; once the turn spent its searches, it no longer sees them.
+    wrapModelCall: (request, handler) => {
+      if (
+        discoveryCallsInTurn(request.state.messages ?? []) < MAX_DISCOVERY_CALLS
+      )
+        return handler(request);
+      const tools = request.tools.filter(
+        (t) =>
+          !(typeof t.name === 'string' && DISCOVERY_TOOL_NAMES.has(t.name)),
+      );
+      return handler({ ...request, tools });
+    },
     wrapToolCall: async (toolCallRequest, handler) => {
       const { toolCall, state } = toolCallRequest;
       const toolName = toolCall.name ?? toolCallRequest.tool?.name;
@@ -109,6 +143,26 @@ export const createToolRepetitionGuardMiddleware = (
       const opening = turnStart(messages);
       const start = Math.max(opening, messages.length - lookback, 0);
       const argsById = toolCallArgsById(messages, start);
+
+      if (DISCOVERY_TOOL_NAMES.has(toolName)) {
+        const discovered = discoveryCallsInTurn(messages);
+        if (discovered >= MAX_DISCOVERY_CALLS) {
+          logger.warn(
+            `Repetition guard: ${toolName} refused after ${discovered} discovery calls this turn`,
+          );
+          return new ToolMessage({
+            content: [
+              `You have already searched capabilities and skills ${discovered} times in this turn, so \`${toolName}\` was NOT run.`,
+              '',
+              'Stop searching. Act with the tools you already have: read their descriptions and call the one that fits the request,',
+              'or tell the user what you could not find and ask them what they want.',
+            ].join('\n'),
+            tool_call_id: toolCall.id ?? '',
+            name: toolName,
+            status: 'error',
+          });
+        }
+      }
       // The turn's calls a mid-turn summary condensed away (oldest first):
       // only while the lookback still reaches the summary.
       const openingMessage = messages[opening];
@@ -121,7 +175,13 @@ export const createToolRepetitionGuardMiddleware = (
           call.name === toolName && canonicalArgsKey(call.args) === argsKey,
       );
 
-      const failedInTurn = (priorError: string): ToolMessage => {
+      const failedInTurn = (failure: string): ToolMessage => {
+        // A refusal of this guard is not quoted inside the next one, or each repeat nests every earlier one.
+        const priorError = /was NOT (called|run) again|was NOT run\b/.test(
+          failure,
+        )
+          ? `This guard already refused it: \`${toolName}\` reached its limit in this turn.`
+          : failure;
         logger.warn(
           `Repetition guard: short-circuiting duplicate failed call to ${toolName}`,
           { toolName, priorError },

package/src/do/contracts.ts

@@ -1,3 +1,11 @@
+import type {
+  CheckClaimDispatch,
+  CheckDispatch,
+} from '@ixo/action-interactions';
+import type {
+  InteractionCommand,
+  InteractionOutcome,
+} from '../action-interactions/store';
 import type {
   ChannelAttachment,
   ChannelControlInput,
@@ -63,6 +71,7 @@ import type { DomainContextProvenance } from '../core/domain-context';
 
 /** Bindings every oracle Worker must declare (see the example `wrangler.jsonc`). */
 export interface OracleWorkerEnv {
+  ACTION_INTERACTIONS_ENABLED?: string;
   TOPIC_DELIVERABLES_ENABLED?: string;
   ACTION_PROPOSALS_RPC_TESTNET?: string;
   ACTION_PROPOSALS_RPC_DEVNET?: string;
@@ -782,6 +791,29 @@ export interface StorageStatus {
  * piped straight to the client.
  */
 export interface UserOracleObject extends Rpc.DurableObjectBranded {
+  readActionInteractionTask(
+    identity: TurnIdentity,
+    sessionId: string,
+    taskId: string,
+  ): Promise<InteractionOutcome<string>>;
+  checkDispatch(
+    identity: TurnIdentity,
+    input: CheckDispatch,
+  ): Promise<InteractionOutcome<string>>;
+  checkClaimDispatch(
+    identity: TurnIdentity,
+    input: CheckClaimDispatch,
+  ): Promise<InteractionOutcome<string>>;
+  actionInteraction(
+    identity: TurnIdentity,
+    command: InteractionCommand,
+  ): Promise<InteractionOutcome<string>>;
+  readActionInteraction(
+    identity: TurnIdentity,
+    sessionId: string,
+    id?: string,
+    references?: boolean,
+  ): Promise<InteractionOutcome<string>>;
   recordHubActionOutcome(outcome: ActionOutcomeV1): Promise<void>;
   topicDeliverable(
     identity: TurnIdentity,

package/src/do/user-oracle-do.ts

@@ -1,3 +1,14 @@
+import { taskCardSummary } from '../plugins/tasks/tasks-tools';
+import {
+  ActionInteractionError,
+  type CheckClaimDispatch,
+  type CheckDispatch,
+} from '@ixo/action-interactions';
+import {
+  ActionInteractionStore,
+  interactionOutcome,
+  type InteractionCommand,
+} from '../action-interactions/store';
 import {
   CHANNEL_DELIVERY_NOTICE_KWARG,
   channelDeliveryNote,
@@ -735,6 +746,11 @@ const META_LEGACY_CLEARED = 'meta:legacyCleared';
  */
 const META_LEGACY_UNUSABLE = 'meta:legacyUnusable';
 const META_USER_DID = 'meta:userDid';
+/**
+ * Set when an evicted object keeps an alarm only for action-card draft
+ * retention; a boot clears it. The alarm then prunes on the bare object.
+ */
+const META_RETENTION_WAKE = 'meta:interactionRetentionWake';
 
 /** KV key of a session's context-guard counters (`GET /debug/context?session=`). */
 const contextStatsKey = (sessionId: string): string => `ctxstats:${sessionId}`;
@@ -1690,6 +1706,7 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
         throw new Error(`Object bound to ${stored}, not ${userDid}`);
       if (!stored) await this.ctx.storage.put(META_USER_DID, userDid);
       this.userDid = userDid;
+      await this.ctx.storage.delete(META_RETENTION_WAKE);
 
       const env = this.env;
       // The gateway lazily starts on first use; make sure it is up before the
@@ -2769,6 +2786,21 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       // exists once the object booted).
       const keepAliveAt = this.runs?.keepAliveDeadline(wakeAt) ?? null;
       const recoveryAt = this.runs?.nextRecoveryAt() ?? null;
+      // An evicted object (no working copy, no housekeeping deadline) with
+      // no socket is only woken for action-card draft retention: prune on
+      // the bare object instead of importing the owner copy, and re-arm.
+      if (
+        !this.db &&
+        nextPingAt === null &&
+        keepAliveAt === null &&
+        recoveryAt === null &&
+        (await this.ctx.storage.get<boolean>(META_RETENTION_WAKE)) === true
+      ) {
+        const next = await this.bareInteractionRetention();
+        if (next !== null) await this.requestAlarm(next);
+        else await this.ctx.storage.delete(META_RETENTION_WAKE);
+        return;
+      }
       if (this.runs && recoveryAt !== null && recoveryAt <= wakeAt + 1000) {
         // A store error here must not reject the alarm: the tick below (or
         // the re-arm) still has to run.
@@ -2984,6 +3016,22 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
         }
       }
 
+      // Action-card drafts past retention: one bounded batch per tick, so a
+      // user who stopped preparing cards still loses expired draft values.
+      // Its follow-up is no reason to keep an idle copy either.
+      if (this.userDid) {
+        try {
+          await new ActionInteractionStore(this.ctx.storage, {
+            oracleDid: this.env.ORACLE_DID,
+            userDid: this.userDid,
+          }).prune();
+        } catch (err) {
+          console.warn(
+            `[action-interactions] retention tick failed for ${this.userDid}: ${err instanceof Error ? err.message : String(err)}`,
+          );
+        }
+      }
+
       // Idle housekeeping: a user silent for five days loses the cached
       // pages — their file is safe upstream, and we stop paying to store a
       // copy. Never evict while tasks are scheduled: their runs ARE
@@ -3015,12 +3063,22 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
         });
         if (outcome === 'evicted') {
           await this.ctx.storage.delete(META_HOUSEKEEPING_AT);
+          // Action-card drafts outlive the working copy: their retention
+          // still needs a wake (handled on the bare object, see alarm()).
+          const retentionAt = await this.interactionRetentionAt();
           // An attached (idle) socket still needs its heartbeat rounds.
-          if (nextPingAt !== null) await this.requestAlarm(nextPingAt);
+          if (nextPingAt !== null)
+            await this.requestAlarm(
+              Math.min(nextPingAt, retentionAt ?? Infinity),
+            );
           // A request that waited on the wipe has booted the object afresh
           // and armed its own deadlines (a task Start's run): keep them.
-          else if (this.initPromise === null)
-            await this.ctx.storage.deleteAlarm();
+          else if (this.initPromise === null) {
+            if (retentionAt !== null) {
+              await this.ctx.storage.put(META_RETENTION_WAKE, true);
+              await this.requestAlarm(retentionAt);
+            } else await this.ctx.storage.deleteAlarm();
+          }
           return;
         }
         if (outcome === 'not-current') {
@@ -3196,6 +3254,162 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
 
     // ── RPC surface (contracts.ts UserOracleObject) ───────────────────────
 
+    private async interactionStore(
+      identity: TurnIdentity,
+      sessionId: string,
+      options: { recordAccess?: boolean } = {},
+    ) {
+      await this.ready(identity, options);
+      if (
+        this.userDid !== identity.userDid ||
+        !(await this.sessions?.getSession(sessionId))
+      )
+        throw new ActionInteractionError(404, 'not_found', 'Session not found');
+      return new ActionInteractionStore(this.ctx.storage, {
+        oracleDid: this.env.ORACLE_DID,
+        userDid: identity.userDid,
+      });
+    }
+
+    async readActionInteractionTask(
+      identity: TurnIdentity,
+      sessionId: string,
+      taskId: string,
+    ) {
+      return interactionOutcome(async () => {
+        // The task scheduler needs a booted object, but an open task card polls every 15 s:
+        // the poll is not activity, so it never keeps an idle object from being evicted.
+        await this.interactionStore(identity, sessionId, {
+          recordAccess: false,
+        });
+        const task = await this.taskScheduler?.surface.get(taskId);
+        if (!task)
+          throw new ActionInteractionError(404, 'not_found', 'Task not found');
+        return JSON.stringify({ task: taskCardSummary(task) });
+      });
+    }
+
+    /**
+     * The draft store without a boot: the object is addressed by the
+     * caller's DID, and the stored binding is checked against it.
+     */
+    private async bareInteractionStore(identity: TurnIdentity) {
+      const bound =
+        this.userDid ?? (await this.ctx.storage.get<string>(META_USER_DID));
+      if (bound && bound !== identity.userDid)
+        throw new ActionInteractionError(404, 'not_found', 'Owner not found');
+      return new ActionInteractionStore(this.ctx.storage, {
+        oracleDid: this.env.ORACLE_DID,
+        userDid: identity.userDid,
+      });
+    }
+
+    async checkDispatch(identity: TurnIdentity, input: CheckDispatch) {
+      return interactionOutcome(async () => {
+        // Runs before every bid, claim-block and approval effect: no boot, as in checkClaimDispatch.
+        const store = await this.bareInteractionStore(identity);
+        return JSON.stringify(await store.checkDispatch(input));
+      });
+    }
+
+    async checkClaimDispatch(
+      identity: TurnIdentity,
+      input: CheckClaimDispatch,
+    ) {
+      return interactionOutcome(async () => {
+        // Every Portal claim calls this, Companion user or not, so it must
+        // not boot the object (gateway, signer, SQLite, owner-copy import):
+        // it only reads and writes a few keys. The object is addressed by
+        // the caller's DID; the stored binding is checked without a boot.
+        const store = await this.bareInteractionStore(identity);
+        return JSON.stringify(await store.checkClaimDispatch(input));
+      });
+    }
+
+    /** When stored action-card drafts next need retention, if any are kept. */
+    private async interactionRetentionAt(): Promise<number | null> {
+      const userDid =
+        this.userDid ?? (await this.ctx.storage.get<string>(META_USER_DID));
+      if (!userDid) return null;
+      return new ActionInteractionStore(this.ctx.storage, {
+        oracleDid: this.env.ORACLE_DID,
+        userDid,
+      })
+        .nextRetentionAt()
+        .catch(() => null);
+    }
+
+    /** One retention pass on an un-booted object; returns the next due time. */
+    private async bareInteractionRetention(): Promise<number | null> {
+      const userDid = await this.ctx.storage.get<string>(META_USER_DID);
+      if (!userDid) return null;
+      const store = new ActionInteractionStore(this.ctx.storage, {
+        oracleDid: this.env.ORACLE_DID,
+        userDid,
+      });
+      try {
+        await store.prune();
+      } catch (err) {
+        console.warn(
+          `[action-interactions] retention on an evicted object failed for ${userDid}: ${err instanceof Error ? err.message : String(err)}`,
+        );
+        return Date.now() + 60 * 60 * 1000;
+      }
+      const next = await store.nextRetentionAt().catch(() => null);
+      // A backlog larger than one pass resumes a minute later.
+      return next === null ? null : Math.max(next, Date.now() + 60_000);
+    }
+
+    /** Drafts of a deleted chat, in bounded batches. */
+    private async forgetInteractions(userDid: string, sessionId: string) {
+      const store = new ActionInteractionStore(this.ctx.storage, {
+        oracleDid: this.env.ORACLE_DID,
+        userDid,
+      });
+      while ((await store.forgetSession(sessionId)) > 0);
+    }
+
+    async actionInteraction(
+      identity: TurnIdentity,
+      command: InteractionCommand,
+    ) {
+      return interactionOutcome(async () => {
+        const store = await this.interactionStore(
+          identity,
+          command.input.sessionId,
+        );
+        if (
+          command.kind === 'prepare' &&
+          command.input.owner.kind === 'task' &&
+          !(await this.taskScheduler?.surface.get(command.input.owner.taskId))
+        )
+          throw new ActionInteractionError(404, 'not_found', 'Task not found');
+        return JSON.stringify(await store.command(command));
+      });
+    }
+
+    async readActionInteraction(
+      identity: TurnIdentity,
+      sessionId: string,
+      id?: string,
+      references = false,
+    ) {
+      return interactionOutcome(async () => {
+        // Card polls never boot the object or count as activity: they read a
+        // few keys, so an open card neither imports an evicted owner copy nor
+        // keeps an idle object alive. A deleted chat's drafts are deleted
+        // with it, so no session lookup is needed to hide them.
+        const store = await this.bareInteractionStore(identity);
+        return JSON.stringify(
+          await (id
+            ? store.read(id, sessionId)
+            : references
+              ? store.listReferences(sessionId)
+              : store.list(sessionId)),
+        );
+      });
+    }
+
     async createSession(
       identity: TurnIdentity,
       o: { roomId?: string; sessionId?: string; markerTxnId?: string } = {},
@@ -4112,6 +4326,15 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
           });
         await this.ctx.storage.delete(contextStatsKey(sessionId));
         await this.feedbackMarkers!.forgetSession(sessionId);
+        // The chat's action-card drafts go with it; a dispatched claim keeps
+        // only the tombstones that stop a duplicate.
+        await this.forgetInteractions(identity.userDid, sessionId).catch(
+          (err: unknown) => {
+            console.warn(
+              `[action-interactions] could not delete the drafts of ${sessionId}; retention removes them later: ${err instanceof Error ? err.message : String(err)}`,
+            );
+          },
+        );
         this.markDirty();
       }
       // A channel binding that pointed at the session opens a new one on

package/src/plugins/portal/portal.plugin.ts

@@ -33,8 +33,9 @@ import {
 const manifest: PluginManifest = {
   title: 'Portal',
   summary:
-    "Browser-side actions on the user's Portal UI — opens URLs, manipulates the DOM, runs FE-defined browser tools.",
+    "The user's Portal UI: action cards (bids, claims, questions, approvals), forms, Topics, domains, pages, navigation.",
   whenToUse: [
+    'User asks to prepare or submit a bid or claim: call `list_action_cards`, then `prepare_action_card`.',
     'User asks for an action the Portal FE exposes as a browser tool (declared in `state.browserTools`).',
     "A task needs a browser-side capability the server can't do alone — open a URL in the user's tab, click a Portal button, fill a form.",
   ],

package/src/plugins/tasks/tasks-tools.ts

@@ -95,6 +95,25 @@ function summarizeRecord(record: OracleTaskRecord): Record<string, unknown> {
   };
 }
 
+/** Current owner summary shared by get_task and private card readback. */
+export function taskCardSummary(
+  record: OracleTaskRecord,
+): Record<string, unknown> {
+  return {
+    ok: true,
+    ...summarizeRecord(record),
+    ...(record.executionProfile
+      ? { note: RESTRICTED_TASK_NOTE }
+      : { intent: record.intent }),
+    lastRunAt: record.lastRunAt ?? null,
+    lastResult:
+      record.executionProfile && record.lastResult
+        ? { ok: record.lastResult.ok, at: record.lastResult.at }
+        : (record.lastResult ?? null),
+    consecutiveFailures: record.consecutiveFailures,
+  };
+}
+
 function failure(err: unknown): { ok: false; error: string } {
   return {
     ok: false,
@@ -242,26 +261,7 @@ function getTask(): PluginTool {
       try {
         const record = await tasks.get(taskId);
         if (!record) return { ok: false, error: 'Task not found.' };
-        if (record.executionProfile) {
-          return {
-            ok: true,
-            ...summarizeRecord(record),
-            lastRunAt: record.lastRunAt ?? null,
-            lastResult: record.lastResult
-              ? { ok: record.lastResult.ok, at: record.lastResult.at }
-              : null,
-            consecutiveFailures: record.consecutiveFailures,
-            note: RESTRICTED_TASK_NOTE,
-          };
-        }
-        return {
-          ok: true,
-          ...summarizeRecord(record),
-          intent: record.intent,
-          lastRunAt: record.lastRunAt ?? null,
-          lastResult: record.lastResult ?? null,
-          consecutiveFailures: record.consecutiveFailures,
-        };
+        return taskCardSummary(record);
       } catch (err) {
         return failure(err);
       }