@ixo/oracle-runtime-workers 0.13.0 → 0.16.0

package/src/plugins/tasks/manifest.ts

@@ -56,7 +56,7 @@ export const tasksManifest: PluginManifest = {
     {
       user: '(replying to an approval request) Yes — go ahead.',
       thought:
-        'The user approved the pending run — record it; approval executes the run and delivers the result.',
+        'The user approved the pending run — record it; approval starts the run, and its result is posted to the room when it finishes.',
       tool: 'resolve_task_approval',
       args: {
         taskId: 'task_daily-linkedin-update_a1b2c3d4',

package/src/plugins/tasks/middleware.ts

@@ -8,9 +8,10 @@
  *   - There are no dedicated task rooms or room→session bindings — pending
  *     approvals live on the task records themselves (`pendingApprovalAt`), so
  *     the gate reads them straight off `OracleTasksSurface.list()`.
- *   - The gate never resolves an approval itself: on Workers, resolving an
- *     approval EXECUTES the run (a full agent turn), which does not belong
- *     inside a model-call wrapper. Plain yes/no replies are still classified
+ *   - The gate never resolves an approval itself: resolving an approval
+ *     starts the run (a full agent turn, on the user object's alarm), which
+ *     is the model's call to make through the tool, not a model-call
+ *     wrapper's. Plain yes/no replies are still classified
  *     deterministically (`classifyReplyFast`) — the classification shapes the
  *     hint, and the model records the decision through the
  *     `resolve_task_approval` tool.
@@ -22,6 +23,10 @@ import type { BaseMessage } from '@langchain/core/messages';
 import { createMiddleware, type AgentMiddleware } from 'langchain';
 import type { Logger, OracleTasksSurface } from '../../plugin-api/types';
 import { pendingApprovalOf } from '../../tasks/store';
+import {
+  stripTurnTimeNote,
+  TURN_TIME_NOTE_KWARG,
+} from '../../core/turn-time-note';
 
 const APPROVE = new Set([
   'yes',
@@ -114,7 +119,7 @@ export async function computeApprovalHint(
   if (only && decision === 'approved') {
     return (
       `\n\n[Task approval gate] The user's reply APPROVES the pending run of task ${only.id} ("${only.title}"). ` +
-      'Call `resolve_task_approval` with outcome "approved" NOW — approval executes the run and delivers its result — then confirm to the user.'
+      'Call `resolve_task_approval` with outcome "approved" NOW — approval starts the run, and its result is posted to the room when it finishes — then tell the user it is running.'
     );
   }
   if (only && decision === 'rejected') {
@@ -128,7 +133,7 @@ export async function computeApprovalHint(
     .join(', ');
   return (
     `\n\n[Task approval gate] ${pending.length} task run(s) are waiting for the user's approval: ${listing}. ` +
-    'If this reply decides one of them (possibly with tweaks), call `resolve_task_approval` with the outcome — "approved" executes the run (pass requested tweaks in `note`), "declined" drops it. ' +
+    'If this reply decides one of them (possibly with tweaks), call `resolve_task_approval` with the outcome — "approved" starts the run (pass requested tweaks in `note`), "declined" drops it. ' +
     'Otherwise answer normally and remind the user of the pending approval.'
   );
 }
@@ -144,12 +149,20 @@ export function userDidFromContext(context: unknown): string | undefined {
   return typeof did === 'string' && did.length > 0 ? did : undefined;
 }
 
-/** Text of the latest HumanMessage — string content or joined text parts. */
+/**
+ * Text of the latest HumanMessage — string content or joined text parts —
+ * as the user sent it: without the turn time note the runtime puts in front.
+ */
 export function lastHumanText(messages: BaseMessage[]): string | null {
   for (let i = messages.length - 1; i >= 0; i--) {
     const message = messages[i];
     if (!message || message.type !== 'human') continue;
-    return textOfContent(message.content);
+    return textOfContent(
+      stripTurnTimeNote(
+        message.content,
+        message.additional_kwargs?.[TURN_TIME_NOTE_KWARG],
+      ),
+    );
   }
   return null;
 }

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

@@ -38,7 +38,8 @@ const APPROVAL_FIELD_DESCRIPTION =
   'fires it does NOT execute — it posts an approval request into the ' +
   "user's oracle room and waits. The user approves or declines by replying " +
   'there; record the decision with `resolve_task_approval` — approval ' +
-  'executes the run and delivers its result, a decline drops it.';
+  'starts the run in the background (its result is posted to the room when ' +
+  'it finishes), a decline drops it.';
 
 const taskInputShape = {
   title: z.string().min(1).max(120),
@@ -72,6 +73,14 @@ function requireTasks(ctx: RuntimeContext): OracleTasksSurface | null {
   return ctx.tasks ?? null;
 }
 
+/**
+ * A host-created supplied-context task: its intent is the authorized source
+ * text and its result was produced from it alone. Neither enters an ordinary
+ * conversation, and the task is one immutable attempt (cancel only).
+ */
+const RESTRICTED_TASK_NOTE =
+  'Restricted supplied-context task: its source text and result are not available in this conversation, and it cannot be edited, paused or resumed — only cancelled.';
+
 function summarizeRecord(record: OracleTaskRecord): Record<string, unknown> {
   const pendingApprovalAt = pendingApprovalOf(record);
   return {
@@ -84,6 +93,10 @@ function summarizeRecord(record: OracleTaskRecord): Record<string, unknown> {
     ...(pendingApprovalAt !== undefined && {
       awaitingApprovalSince: pendingApprovalAt,
     }),
+    ...(record.executionProfile && {
+      restricted: true,
+      executionProfile: record.executionProfile,
+    }),
   };
 }
 
@@ -234,6 +247,18 @@ 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),
@@ -354,7 +379,7 @@ function resolveTaskApproval(): PluginTool {
           outcome: args.outcome,
           note:
             args.outcome === 'approved'
-              ? "Decision recorded and the run was executed — its result was delivered to the user's room. Confirm to the user."
+              ? "Approved — the run is starting now in the background; its result will be posted to the user's room when it finishes. Tell the user it is running; do not claim a result yet."
               : 'Decision recorded — the pending run was dropped and nothing was executed.',
         };
       } catch (err) {
@@ -364,7 +389,7 @@ function resolveTaskApproval(): PluginTool {
     {
       name: 'resolve_task_approval',
       description:
-        "Record the user's decision on a task run that is waiting for approval. 'approved' EXECUTES the run immediately (the result is delivered to the user's room); 'declined' drops it without running. Call this when the user answers a pending approval request — pass their requested tweaks in `note`.",
+        "Record the user's decision on a task run that is waiting for approval. 'approved' starts the run right away in the background (its result is posted to the user's room when it finishes); 'declined' drops it without running. Call this when the user answers a pending approval request — pass their requested tweaks in `note`.",
       schema: resolveApprovalInput,
     },
   );
@@ -381,6 +406,8 @@ function suggestSpecFix(): PluginTool {
       try {
         const record = await tasks.get(taskId);
         if (!record) return { ok: false, error: 'Task not found.' };
+        if (record.executionProfile)
+          return { ok: false, error: RESTRICTED_TASK_NOTE };
         const lastFailure =
           record.lastResult && !record.lastResult.ok
             ? record.lastResult

package/src/plugins/tasks/tasks.plugin.ts

@@ -22,9 +22,10 @@
  * `TaskSchedulerHost.maxTasksPerUser` / `.minCronIntervalSec`.
  *
  * Middlewares are built once at boot while the tasks surface is per-user, so
- * the plugin stashes each request's `ctx.tasks` keyed by the authenticated
- * user DID (`getRequestTools` runs on every agent build, before any model
- * call) and the middleware looks the surface up per turn.
+ * the plugin holds each request's `ctx.tasks` keyed by the authenticated
+ * user DID for the length of the turn (`getRequestTools` runs on every agent
+ * build, before any model call; `onTurnEnd` releases it) and the middleware
+ * looks the surface up per model call — see `TaskSurfaceRegistry`.
  */
 import { z } from 'zod';
 import { defineOraclePlugin } from '../../plugin-api/define-plugin';
@@ -41,12 +42,59 @@ export const tasksConfigSchema = z.object({
 
 export const TASKS_PLUGIN_NAME = 'tasks';
 
-export function createTasksPlugin(): OraclePlugin {
-  // ctx.tasks per user DID, refreshed on every agent build. One plugin
-  // instance can serve several users' Durable Objects in the same isolate,
-  // so the key is the authenticated DID from the request context.
-  const surfaces = new Map<string, OracleTasksSurface>();
+/**
+ * `ctx.tasks` per user DID, for the turns that are running. One plugin
+ * instance serves every user object in the isolate, and a surface keeps its
+ * user object's scheduler and store reachable, so an entry lives only while
+ * a turn of that user holds it: `hold` at the agent build, the returned
+ * release at the turn's end. Overlapping turns of one user (two sessions)
+ * share the entry; the last release drops it.
+ */
+export class TaskSurfaceRegistry {
+  private readonly entries = new Map<
+    string,
+    { surface: OracleTasksSurface; turns: number }
+  >();
+
+  /** Hold `surface` for `did` for one turn. The release runs once. */
+  hold(did: string, surface: OracleTasksSurface): () => void {
+    let entry = this.entries.get(did);
+    if (entry) {
+      entry.surface = surface;
+      entry.turns += 1;
+    } else {
+      entry = { surface, turns: 1 };
+      this.entries.set(did, entry);
+    }
+    const held = entry;
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      held.turns -= 1;
+      if (held.turns <= 0 && this.entries.get(did) === held)
+        this.entries.delete(did);
+    };
+  }
+
+  /** The user's turn runs without a scheduler: forget any surface. */
+  clear(did: string): void {
+    this.entries.delete(did);
+  }
+
+  surfaceFor(did: string): OracleTasksSurface | undefined {
+    return this.entries.get(did)?.surface;
+  }
+
+  /** Users with an entry (diagnostics, tests). */
+  get size(): number {
+    return this.entries.size;
+  }
+}
 
+export function createTasksPlugin(
+  surfaces: TaskSurfaceRegistry = new TaskSurfaceRegistry(),
+): OraclePlugin {
   return defineOraclePlugin({
     name: TASKS_PLUGIN_NAME,
     version: '1.0.0',
@@ -57,13 +105,18 @@ export function createTasksPlugin(): OraclePlugin {
     autoDetect: () => true,
     getTools: () => createTaskTools(),
     getRequestTools: (rtCtx) => {
-      if (rtCtx.tasks) surfaces.set(rtCtx.user.did, rtCtx.tasks);
-      else surfaces.delete(rtCtx.user.did);
+      if (!rtCtx.tasks) {
+        surfaces.clear(rtCtx.user.did);
+        return [];
+      }
+      // A host without per-turn cleanup keeps the entry until the user's
+      // next turn without a scheduler (the Workers host always has it).
+      rtCtx.onTurnEnd?.(surfaces.hold(rtCtx.user.did, rtCtx.tasks));
       return [];
     },
     getMiddlewares: (ctx) => [
       createTaskApprovalGateMiddleware({
-        surfaceFor: (userDid) => surfaces.get(userDid),
+        surfaceFor: (userDid) => surfaces.surfaceFor(userDid),
         logger: ctx.logger,
       }),
     ],

package/src/plugins/user-preferences/schema.ts

@@ -18,11 +18,22 @@ export const FORMALITY_LEVELS = [
   'academic',
 ] as const;
 
+/**
+ * Longest `tone` label. The tone is pasted into every system prompt, so new
+ * writes over this length are rejected by the tool schema, and a longer value
+ * already stored (an older write, or one from the Node runtime, which never
+ * capped it) is cut to this length when it is read.
+ */
+export const MAX_TONE_LENGTH = 120;
+
 export const UserPreferencesSchema = z.object({
   agentName: z.string().max(80).optional(),
   userName: z.string().max(80).optional(),
   language: z.string().max(20).optional(), // BCP-47-ish, free-form
-  tone: z.string().optional(), // e.g. "casual", "playful"
+  tone: z
+    .string()
+    .transform((t) => t.slice(0, MAX_TONE_LENGTH))
+    .optional(), // e.g. "casual", "playful"
   formality: z.enum(FORMALITY_LEVELS).optional(),
   customInstructions: z.string().max(2000).optional(),
   updatedAt: z.iso.datetime().optional(), // the store sets it on every write

package/src/plugins/user-preferences/user-preferences-store.ts

@@ -86,29 +86,51 @@ export class UserPreferencesStore implements UserPreferencesSurface {
    * user without preferences costs one state read per TTL, not per turn.
    */
   async get(roomId: string): Promise<UserPreferences | undefined> {
+    try {
+      return await this.load(roomId);
+    } catch (error) {
+      this.logger?.warn(
+        `[user-preferences] failed to load prefs for room ${roomId}: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+      return undefined;
+    }
+  }
+
+  /**
+   * The room's preferences: `undefined` when no event exists yet or the
+   * stored payload is unreadable (logged); THROWS when the gateway read
+   * itself fails, so a caller about to overwrite the event can tell "nothing
+   * stored" from "could not look".
+   */
+  private async load(
+    roomId: string,
+  ): Promise<StoredUserPreferences | undefined> {
     const hit = this.cache.get(roomId);
     if (hit && hit.expiresAt > this.now()) return hit.value;
 
+    const json = await this.access.getRoomStateEvent(
+      roomId,
+      ROOM_STATE_EVENT_TYPE,
+      USER_PREFS_STATE_KEY,
+    );
+    if (json === null) {
+      this.remember(roomId, undefined);
+      return undefined;
+    }
+
     let decoded: unknown;
     try {
-      const json = await this.access.getRoomStateEvent(
-        roomId,
-        ROOM_STATE_EVENT_TYPE,
-        USER_PREFS_STATE_KEY,
-      );
-      decoded =
-        json === null
-          ? null
-          : await decodeRoomStateContent(JSON.parse(json) as unknown);
+      decoded = await decodeRoomStateContent(JSON.parse(json) as unknown);
     } catch (error) {
       this.logger?.warn(
-        `[user-preferences] failed to load prefs for room ${roomId}: ${
+        `[user-preferences] unreadable prefs payload for room ${roomId}: ${
           error instanceof Error ? error.message : String(error)
         }`,
       );
       return undefined;
     }
-
     if (decoded === null) {
       this.remember(roomId, undefined);
       return undefined;
@@ -128,13 +150,16 @@ export class UserPreferencesStore implements UserPreferencesSurface {
    * Merge `partial` into the stored preferences (only the provided fields
    * change; `undefined` values are ignored rather than clearing a field) and
    * persist the result with a fresh `updatedAt`. Returns the merged record.
-   * An empty `partial` is a no-op that returns the current record.
+   * An empty `partial` is a no-op that returns the current record. Throws —
+   * without writing — when the current preferences cannot be read, so a
+   * transient gateway failure never replaces the stored fields with only the
+   * new ones. A payload that exists but cannot be decoded is replaced.
    */
   async set(
     roomId: string,
     partial: Partial<UserPreferences>,
   ): Promise<UserPreferences> {
-    const current = (await this.get(roomId)) ?? {};
+    const current = (await this.load(roomId)) ?? {};
     const provided = Object.fromEntries(
       Object.entries(partial).filter(([, value]) => value !== undefined),
     );

package/src/plugins/user-preferences/user-preferences-tool.ts

@@ -11,7 +11,7 @@ import type {
   PluginTool,
   RuntimeContext,
 } from '../../plugin-api/types';
-import { FORMALITY_LEVELS } from './schema';
+import { FORMALITY_LEVELS, MAX_TONE_LENGTH } from './schema';
 
 export const SET_USER_PREFERENCES_TOOL_NAME = 'set_user_preferences';
 
@@ -46,10 +46,11 @@ export const setUserPreferencesSchema = z.object({
     ),
   tone: z
     .string()
+    .max(MAX_TONE_LENGTH)
     .optional()
     .describe(
       "Short tone label your future self will see at the top of every prompt (e.g. 'playful and warm', " +
-        "'concise and dry', 'patient teacher'). Pick descriptive words, not vague ones.",
+        `'concise and dry', 'patient teacher'). Pick descriptive words, not vague ones. Max ${MAX_TONE_LENGTH} characters.`,
     ),
   formality: z
     .enum(FORMALITY_LEVELS)