@opengeni/runtime 4.6.0 → 4.7.0-canary.37090756480001

package/src/agent-instructions/PROMPT_CHANGELOG.md

@@ -43,7 +43,7 @@ Composition order (each part separated by a blank line):
      waiting and `wait_for_input`, compaction, background commands.
    - Conditional modules, in this order: `renderer_markdown`, `sandbox`,
      `connected_machine`, `repositories`, `workspace_environment`, `rig`,
-     `artifacts`, `goals`, `subagents`, `knowledge`, `skills`, `admin`,
+     `artifacts`, `media`, `goals`, `subagents`, `knowledge`, `skills`, `admin`,
      `attachments` (last because it varies per turn).
 3. Attempt directives, unchanged text: Codemode, code search, Git credential
    bindings.
@@ -82,6 +82,28 @@ Headings that moved or were added (layout only, not diffed):
 
 ## Sentence edits (modular "all" vs legacy)
 
+Tool discovery and media. Deferred schemas must remain behind the existing
+search router, while modular agents need to distinguish missing disclosure
+from missing execution authority. Runtime mechanics explains ranked discovery
+and literal-prefix recovery; the new `media` capability module directs image
+and video requests to runtime/provider tools rather than integration setup.
+Disabled media removes that module. The legacy prompt remains unchanged.
+
+```diff
++ Deferred tool schemas are omitted from the first request; absence there does not prove a tool is unavailable.
++ When deferred tools are attached, use `tool_search` for one focused capability at a time; broad searches with small limits can omit a relevant tool.
++ If a search misses, use `tool_list` and follow `nextCursor` until the relevant authorized names are covered, then load exact names with `tool_search`.
++ `namePrefix` is a literal tool-name prefix, not a capability keyword; an empty filtered page does not prove the capability is unavailable.
++ Discovery never grants authority, and remembered tool names must still resolve against the current authorized catalog.
++ Use an attached image-generation tool when the user requests generated images or edits.
++ If it is deferred, use a focused image-generation query with `tool_search`, or request the exact `generate_image` name before concluding no image tool exists.
++ `generate_image` is a runtime tool; integration catalogs and sandbox CLI lists do not enumerate it.
++ A hosted `image_generation` tool may instead be visible directly on supported provider routes.
++ The media capability permits discovery, but does not prove a provider adapter is attached; establish availability from the current authorized tool catalog.
++ Use the returned tool schema for references and output controls; do not invent model names or provider-specific options.
++ For video, discover `get_video_generation_capabilities` and `generate_video`, read current capabilities before selecting a model, and follow the available video-generation Skill.
+```
+
 Identity. The legacy text opened with two identity statements (the contract's
 generic line and the template's OpenGeni line). The default identity keeps the
 more specific one and adds the contract's collaboration and voice sentences,

package/src/agent-instructions/compose.ts

@@ -13,6 +13,7 @@ import { rigModule, workspaceEnvironmentModule } from "./modules/environment";
 import { goalsModule } from "./modules/goals";
 import { knowledgeModule } from "./modules/knowledge";
 import { connectedMachineModule } from "./modules/machines";
+import { mediaModule } from "./modules/media";
 import { rendererMarkdownModule } from "./modules/renderer-markdown";
 import { repositoriesModule } from "./modules/repositories";
 import { sandboxModule } from "./modules/sandbox";
@@ -33,6 +34,7 @@ export const AGENT_PROMPT_MODULES: readonly AgentPromptModule[] = [
   workspaceEnvironmentModule,
   rigModule,
   artifactsModule,
+  mediaModule,
   goalsModule,
   subagentsModule,
   knowledgeModule,

package/src/agent-instructions/modules/media.ts

@@ -0,0 +1,20 @@
+import { blocks, sentences, type AgentPromptModule } from "../types";
+
+/** Media authorization is separate from provider attachment and tool disclosure. */
+export const mediaModule: AgentPromptModule = {
+  id: "media",
+  applies: (context) => context.capabilities.media,
+  render: () =>
+    blocks(
+      "# Images and video",
+      sentences(
+        "Use an attached image-generation tool when the user requests generated images or edits.",
+        "If it is deferred, use a focused image-generation query with `tool_search`, or request the exact `generate_image` name before concluding no image tool exists.",
+        "`generate_image` is a runtime tool; integration catalogs and sandbox CLI lists do not enumerate it.",
+        "A hosted `image_generation` tool may instead be visible directly on supported provider routes.",
+        "The media capability permits discovery, but does not prove a provider adapter is attached; establish availability from the current authorized tool catalog.",
+        "Use the returned tool schema for references and output controls; do not invent model names or provider-specific options.",
+        "For video, discover `get_video_generation_capabilities` and `generate_video`, read current capabilities before selecting a model, and follow the available video-generation Skill.",
+      ),
+    ),
+};

package/src/agent-instructions/runtime-mechanics.ts

@@ -43,6 +43,14 @@ Command completion alone resumes you only while you have an explicit \`wait_for_
 export function renderRuntimeMechanics(context: AgentPromptContext): string {
   return blocks(
     "# Runtime mechanics",
+    "## Tool discovery",
+    sentences(
+      "Deferred tool schemas are omitted from the first request; absence there does not prove a tool is unavailable.",
+      "When deferred tools are attached, use `tool_search` for one focused capability at a time; broad searches with small limits can omit a relevant tool.",
+      "If a search misses, use `tool_list` and follow `nextCursor` until the relevant authorized names are covered, then load exact names with `tool_search`.",
+      "`namePrefix` is a literal tool-name prefix, not a capability keyword; an empty filtered page does not prove the capability is unavailable.",
+      "Discovery never grants authority, and remembered tool names must still resolve against the current authorized catalog.",
+    ),
     "## New messages while you work",
     newMessages(context),
     "## Waiting",

package/src/anthropic-messages.ts

@@ -1,5 +1,6 @@
 import { createHash, randomUUID } from "node:crypto";
 import { applyClaudeCodeIdentity } from "./claude-code-identity";
+import { AnthropicRequestError } from "./anthropic-request-error";
 import {
   protocol,
   Usage,
@@ -8,7 +9,8 @@ import {
   type ModelResponse,
   type ResponseStreamEvent,
 } from "@openai/agents";
-import type { ResolvedModelProvider } from "@opengeni/config";
+import { claudeNativeModelProfile, type ResolvedModelProvider } from "@opengeni/config";
+import { withClaudeModelRequest } from "./claude-subscription-usage";
 
 type Json = Record<string, any>;
 type Message = { role: "user" | "assistant" | "system"; content: Json[] };
@@ -17,6 +19,75 @@ export class AnthropicProtocolError extends Error {
   readonly code = "anthropic_protocol_error";
 }
 
+/** Closed provider rejections carry authored copy, never arbitrary response text. */
+export class AnthropicProviderRejection extends Error {
+  readonly name = "AnthropicProviderRejection";
+  constructor(
+    readonly code:
+      | "anthropic_model_access_suspended"
+      | "anthropic_permission_denied"
+      | "content_policy_violation",
+    readonly status: number,
+    readonly request_id?: string,
+    readonly suspendedUntil?: string,
+    readonly headers: Record<string, string> = {},
+  ) {
+    super(
+      code === "anthropic_model_access_suspended"
+        ? suspendedUntil
+          ? `Claude suspended access to this model for the connected account until ${suspendedUntil.replace("T", " ").replace(/(?:\.000)?Z$/, " UTC")}. Try again after that time.`
+          : "Claude suspended access to this model for the connected account. Signing in again will not lift this restriction."
+        : code === "content_policy_violation"
+          ? "Claude blocked this request through its safety systems. Automatic retries stopped."
+          : "Claude denied this request (HTTP 403). Check the connected account's permissions.",
+    );
+  }
+}
+
+function suspensionDeadline(error: Json): string | undefined {
+  if (typeof error.message !== "string") return undefined;
+  const raw =
+    /^model: "[A-Za-z0-9._:/-]{1,128}" is suspended for this organization until (\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z)$/.exec(
+      error.message,
+    )?.[1];
+  if (!raw) return undefined;
+  const date = new Date(raw);
+  if (!Number.isFinite(date.getTime())) return undefined;
+  const normalized = date.toISOString();
+  return normalized.replace(/\.000Z$/, "Z") === raw.replace(/\.000Z$/, "Z")
+    ? normalized
+    : undefined;
+}
+
+function providerRejection(
+  status: number,
+  detail: unknown,
+  responseHeaders: Headers,
+): AnthropicProviderRejection | undefined {
+  if (status !== 403) return undefined;
+  const requestId = responseHeaders.get("request-id") ?? undefined;
+  const headers = responseHeaders.has("retry-after")
+    ? { "retry-after": responseHeaders.get("retry-after")! }
+    : {};
+  const error =
+    detail && typeof detail === "object" && !Array.isArray(detail) ? (detail as Json) : {};
+  if (error.type === "permission_error" && error.details?.error_code === "model_access_suspended")
+    return new AnthropicProviderRejection(
+      "anthropic_model_access_suspended",
+      status,
+      requestId,
+      suspensionDeadline(error),
+      headers,
+    );
+  return new AnthropicProviderRejection(
+    "anthropic_permission_denied",
+    status,
+    requestId,
+    undefined,
+    headers,
+  );
+}
+
 function object(value: unknown): Json {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     throw new AnthropicProtocolError("Expected an object in the Claude protocol");
@@ -232,10 +303,51 @@ export function anthropicMessages(input: ModelRequest["input"]): Message[] {
   return messages;
 }
 
+/**
+ * Compaction retains user/system inputs but removes their intervening assistant
+ * replies. Anthropic's system beta requires a system message after a user and
+ * before an assistant (or at the end), not user -> system -> user. Coalesce each
+ * user phase and its system blocks at that boundary, retaining their own roles,
+ * exact content and relative order. A machine-only continuation after an
+ * assistant needs a request-local input anchor; it is not a new human message.
+ * Never move a system across an assistant.
+ */
+function placeConversationSystems(messages: Message[]): Message[] {
+  const result: Message[] = [];
+  let systems: Json[] = [];
+  const flush = () => {
+    if (!systems.length) return;
+    if (result.at(-1)?.role !== "user")
+      result.push({
+        role: "user",
+        content: [
+          {
+            type: "text",
+            text: "OpenGeni continuation (machine-origin input; no new human message).",
+          },
+        ],
+      });
+    result.push({ role: "system", content: systems });
+    systems = [];
+  };
+  for (const message of messages) {
+    if (message.role === "system") {
+      systems.push(...message.content);
+      continue;
+    }
+    if (message.role === "assistant") flush();
+    const previous = result.at(-1);
+    if (previous?.role === message.role) previous.content.push(...message.content);
+    else result.push(message);
+  }
+  flush();
+  return result;
+}
+
 export function buildAnthropicRequest(
   request: ModelRequest,
   model: string,
-  provider: Pick<ResolvedModelProvider, "anthropic">,
+  provider: Pick<ResolvedModelProvider, "anthropic"> & Partial<Pick<ResolvedModelProvider, "kind">>,
   stream: boolean,
 ): Json {
   if (request.previousResponseId || request.conversationId)
@@ -245,6 +357,13 @@ export function buildAnthropicRequest(
   if (request.prompt)
     throw new AnthropicProtocolError("OpenAI prompt templates cannot be used with Claude");
   const settings = request.modelSettings;
+  const profile = claudeNativeModelProfile(model);
+  const managed =
+    provider.kind === "anthropic-workspace" ||
+    provider.kind === "anthropic-organization" ||
+    provider.kind === "claude-subscription-workspace" ||
+    provider.kind === "claude-subscription-organization";
+  const outputLimit = profile?.maxOutputTokens ?? (managed ? 32_000 : undefined);
   const names = toolNames(request);
   const forcedName = (name: string): string => {
     const matches = [...names].filter(([, identity]) => identity.name === name);
@@ -254,16 +373,16 @@ export function buildAnthropicRequest(
       );
     return matches[0]![0];
   };
-  const messages = anthropicMessages(request.input);
+  let messages = anthropicMessages(request.input);
   if (!messages.length) throw new AnthropicProtocolError("Claude requires at least one message");
   const system = request.systemInstructions
     ? ([{ type: "text", text: request.systemInstructions }] as Json[])
     : [];
-  // Even with mid-conversation-system enabled, initial system/developer
-  // instructions belong in the top-level system field. Keep later system
-  // messages at their original history position.
+  // Initial system/developer instructions belong in the top-level field. Later
+  // systems keep their authority within the same assistant-delimited phase.
   while (messages[0]?.role === "system") system.push(...messages.shift()!.content);
   if (!messages.length) throw new AnthropicProtocolError("Claude requires a conversation message");
+  messages = placeConversationSystems(messages);
   const tools: Json[] = request.tools.map((tool) => {
     if (tool.type !== "function")
       throw new AnthropicProtocolError(`Claude does not support the ${tool.type} tool transport`);
@@ -308,7 +427,13 @@ export function buildAnthropicRequest(
   }
   const body: Json = {
     model,
-    max_tokens: settings.maxTokens ?? provider.anthropic?.maxOutputTokens ?? 32000,
+    max_tokens: Math.min(
+      settings.maxTokens ??
+        provider.anthropic?.maxOutputTokens ??
+        profile?.maxOutputTokens ??
+        32000,
+      outputLimit ?? Infinity,
+    ),
     messages,
     stream,
   };
@@ -326,13 +451,20 @@ export function buildAnthropicRequest(
       ...(body.tool_choice ?? { type: "auto" }),
       disable_parallel_tool_use: true,
     };
-  const effort = settings.reasoning?.effort;
+  const requestedEffort = settings.reasoning?.effort;
+  // Preserve actual native levels; do not silently turn Extra into High.
+  const effort = requestedEffort === "minimal" ? "low" : requestedEffort;
+  const supportsThinking = profile ? profile.efforts.length > 0 : !managed;
   // Anthropic forbids forced tool selection together with thinking.
   const forcedTool = body.tool_choice?.type === "any" || body.tool_choice?.type === "tool";
-  if (effort && effort !== "none" && !forcedTool) {
+  if (supportsThinking && effort && effort !== "none" && !forcedTool) {
+    if (profile && !profile.efforts.includes(effort))
+      throw new AnthropicProtocolError(
+        "The selected Claude model does not support this reasoning effort",
+      );
     body.thinking = { type: "adaptive" };
     body.output_config = {
-      effort: effort === "minimal" ? "low" : effort === "xhigh" ? "high" : effort,
+      effort,
     };
   } else if (settings.temperature !== undefined) body.temperature = settings.temperature;
   if (settings.topP !== undefined && !body.thinking) body.top_p = settings.topP;
@@ -375,11 +507,11 @@ export function anthropicResponse(
   requestId?: string,
   names = new Map<string, { name: string; namespace?: string }>(),
 ): ModelResponse {
-  if (
-    !["end_turn", "tool_use", "stop_sequence", "max_tokens", "refusal"].includes(
-      message.stop_reason,
-    )
-  )
+  // A refused response can be HTTP 200 with no content blocks. It must not
+  // become an empty successful response or admit a tool call from partial output.
+  if (message.stop_reason === "refusal")
+    throw new AnthropicProviderRejection("content_policy_violation", 200, requestId);
+  if (!["end_turn", "tool_use", "stop_sequence", "max_tokens"].includes(message.stop_reason))
     throw new AnthropicProtocolError(`Claude response did not finish: ${message.stop_reason}`);
   text(message.id, "message ID");
   if (!Array.isArray(message.content))
@@ -461,6 +593,7 @@ export class AnthropicMessagesModel implements Model {
   ) {}
 
   private async send(request: ModelRequest, stream: boolean): Promise<Response> {
+    request.signal?.throwIfAborted();
     const body = buildAnthropicRequest(request, this.model, this.provider, stream);
     const base = this.provider.baseUrl ?? "https://api.anthropic.com/v1";
     const url = new URL(`${base.replace(/\/$/, "")}/messages`);
@@ -470,6 +603,11 @@ export class AnthropicMessagesModel implements Model {
     headers.set("content-type", "application/json");
     headers.set("accept", stream ? "text/event-stream" : "application/json");
     headers.set("anthropic-version", "2023-06-01");
+    if ((claudeNativeModelProfile(this.model)?.contextWindowTokens ?? 0) > 200_000) {
+      const betas = new Set((headers.get("anthropic-beta") ?? "").split(",").filter(Boolean));
+      betas.add("context-1m-2025-08-07");
+      headers.set("anthropic-beta", [...betas].join(","));
+    }
     if (body.messages.some((message: Message) => message.role === "system")) {
       const betas = new Set((headers.get("anthropic-beta") ?? "").split(",").filter(Boolean));
       betas.add("mid-conversation-system-2026-04-07");
@@ -506,12 +644,18 @@ export class AnthropicMessagesModel implements Model {
         previousRequestId: this.previousRequestId,
       });
     }
-    const response = await this.fetch(url, {
-      method: "POST",
-      headers,
-      body: JSON.stringify(body),
-      ...(request.signal ? { signal: request.signal } : {}),
-    });
+    const response = await withClaudeModelRequest(this.model, () =>
+      this.fetch(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+        ...(request.signal ? { signal: request.signal } : {}),
+      }),
+    );
+    if (request.signal?.aborted) {
+      void response.body?.cancel().catch(() => undefined);
+      request.signal.throwIfAborted();
+    }
     if (!response.ok) {
       const detail = await readErrorDetail(
         response.body,
@@ -521,20 +665,33 @@ export class AnthropicMessagesModel implements Model {
       const contextExceeded =
         response.status === 400 &&
         /prompt is too long|context_length_exceeded|exceeds.*context window/i.test(detail);
+      let providerError: unknown;
+      try {
+        providerError = JSON.parse(detail).error;
+      } catch {
+        /* Diagnostics can be truncated. */
+      }
+      const rejection = providerRejection(response.status, providerError, response.headers);
+      if (rejection) throw rejection;
       // Classify the bounded provider detail without leaking echoed prompts or credentials.
       const message = contextExceeded
         ? "Claude context window exceeded"
         : response.status === 401
           ? "Claude credentials expired or were revoked. Replace the key or setup token in Models."
           : "Claude request failed (HTTP " + response.status + ")";
-      throw Object.assign(new Error(message), {
-        status: response.status,
-        request_id: response.headers.get("request-id"),
-        headers: response.headers.has("retry-after")
-          ? { "retry-after": response.headers.get("retry-after")! }
-          : {},
-        code: contextExceeded ? "context_length_exceeded" : "anthropic_http_error",
-      });
+      let source: unknown;
+      try {
+        source = JSON.parse(detail)?.error;
+      } catch {
+        // Malformed, truncated or non-JSON bodies retain structural status only.
+      }
+      throw new AnthropicRequestError(
+        message,
+        response.status,
+        contextExceeded ? "context_length_exceeded" : "anthropic_http_error",
+        source,
+        response.headers,
+      );
     }
     this.previousRequestId = response.headers.get("request-id") ?? undefined;
     return response;
@@ -558,6 +715,7 @@ export class AnthropicMessagesModel implements Model {
     for await (const event of anthropicSse(
       response.body,
       this.provider.anthropic?.streamIdleTimeoutMs ?? 600000,
+      request.signal,
     )) {
       request.signal?.throwIfAborted();
       if (event.type === "error") {
@@ -574,6 +732,8 @@ export class AnthropicMessagesModel implements Model {
           overloaded_error: 529,
         };
         const status = typeof kind === "string" ? (statuses[kind] ?? 502) : 502;
+        const rejection = providerRejection(status, event.error, response.headers);
+        if (rejection) throw rejection;
         throw Object.assign(new Error(`Claude stream failed (HTTP ${status})`), {
           status,
           code: status === 429 ? "rate_limit_exceeded" : "anthropic_stream_error",
@@ -581,6 +741,15 @@ export class AnthropicMessagesModel implements Model {
           headers: response.headers.has("retry-after")
             ? { "retry-after": response.headers.get("retry-after")! }
             : {},
+          // Keep the structural stream wrapper stable for provider rejection
+          // guards while the typed cause keeps provider text private.
+          cause: new AnthropicRequestError(
+            `Claude stream failed (HTTP ${status})`,
+            status,
+            status === 429 ? "rate_limit_exceeded" : "anthropic_stream_error",
+            event.error,
+            response.headers,
+          ),
         });
       }
       switch (event.type) {
@@ -641,6 +810,12 @@ export class AnthropicMessagesModel implements Model {
           if (!message) throw new AnthropicProtocolError("Claude message_delta without a message");
           Object.assign(message, event.delta);
           message.usage = { ...message.usage, ...event.usage };
+          if (message.stop_reason === "refusal")
+            throw new AnthropicProviderRejection(
+              "content_policy_violation",
+              200,
+              response.headers.get("request-id") ?? undefined,
+            );
           finalDelta = true;
           break;
         case "message_stop": {
@@ -670,23 +845,39 @@ export class AnthropicMessagesModel implements Model {
 export async function* anthropicSse(
   body: ReadableStream<Uint8Array>,
   idleTimeoutMs = 600000,
+  signal?: AbortSignal,
 ): AsyncGenerator<Json> {
+  if (signal?.aborted) void body.cancel().catch(() => undefined);
+  signal?.throwIfAborted();
   const reader = body.getReader();
   const decoder = new TextDecoder();
   let buffer = "";
   let data: string[] = [];
   try {
     while (true) {
+      signal?.throwIfAborted();
       let timer: ReturnType<typeof setTimeout> | undefined;
+      let onAbort: (() => void) | undefined;
+      const aborted = new Promise<never>((_, reject) => {
+        if (signal) {
+          onAbort = () => reject(signal.reason);
+          signal.addEventListener("abort", onAbort, { once: true });
+          if (signal.aborted) onAbort();
+        }
+      });
       const chunk = await Promise.race([
         reader.read(),
+        aborted,
         new Promise<never>((_, reject) => {
           timer = setTimeout(
             () => reject(new AnthropicProtocolError("Claude stream timed out waiting for data")),
             idleTimeoutMs,
           );
         }),
-      ]).finally(() => clearTimeout(timer));
+      ]).finally(() => {
+        clearTimeout(timer);
+        if (signal && onAbort) signal.removeEventListener("abort", onAbort);
+      });
       buffer += decoder.decode(chunk.value, { stream: !chunk.done });
       let newline: number;
       while ((newline = buffer.indexOf("\n")) >= 0) {
@@ -700,7 +891,8 @@ export async function* anthropicSse(
       if (chunk.done) break;
     }
   } finally {
-    await reader.cancel().catch(() => undefined);
+    // A terminal rejection must not wait on untrusted transport cleanup.
+    void reader.cancel().catch(() => undefined);
     reader.releaseLock();
   }
 }

package/src/anthropic-request-error.ts

@@ -0,0 +1,45 @@
+import { Buffer } from "node:buffer";
+
+function bounded(value: unknown, maxBytes: number): string | undefined {
+  if (typeof value !== "string" || !value) return undefined;
+  const bytes = Buffer.from(value);
+  if (bytes.length <= maxBytes) return value;
+  const marker = "… [truncated]";
+  let end = maxBytes - Buffer.byteLength(marker);
+  while (end > 0 && (bytes[end]! & 0xc0) === 0x80) end -= 1;
+  return bytes.subarray(0, end).toString("utf8") + marker;
+}
+
+/** Structural log message; only the durable failure payload reads provider detail. */
+export class AnthropicRequestError extends Error {
+  readonly request_id: string | null;
+  readonly headers: Record<string, string>;
+  #detail: string | undefined;
+
+  constructor(
+    message: string,
+    readonly status: number,
+    readonly code: string,
+    source: unknown,
+    headers: Headers,
+  ) {
+    super(message);
+    this.name = "AnthropicRequestError";
+    const error =
+      source && typeof source === "object" && !Array.isArray(source)
+        ? (source as Record<string, unknown>)
+        : undefined;
+    const type = bounded(error?.type, 256);
+    const detail = bounded(error?.message, 4096);
+    // Select only error.type/message, never the raw body, echoed request fields,
+    // cookies, or outgoing content. Keep diagnostics out of generic serialization.
+    this.#detail = bounded([type, detail].filter(Boolean).join(": "), 4096);
+    this.request_id = bounded(headers.get("request-id"), 256) ?? null;
+    const retryAfter = bounded(headers.get("retry-after"), 256);
+    this.headers = retryAfter ? { "retry-after": retryAfter } : {};
+  }
+
+  get detail(): string | undefined {
+    return this.#detail;
+  }
+}

package/src/bundled_default_skills/opengeni-client/SKILL.md

@@ -63,13 +63,15 @@ Embedded products may narrow bundled guidance with `bundledSkillIds`.
   Continue useful discovery without requesting broad credentials or pretending
   missing access is configured. Read
   [Discovery and autonomy](references/discovery-and-autonomy.md) for that workflow.
-- Four choices belong to the user: who shares what (`chats`: private, shared
-  or isolated), when things run (schedule and time zone), where outputs land
-  (which screen, record, or channel), and whether the agent may write. If the
-  request or repository does not settle any of them, ask ONE bundled question
-  (the structured question UI when available) with a recommended answer for
-  each, before building. This is the expected step, not an option: asking once
-  is cheap, rebuilding is not. Never ask what the repository answers. See
+- Two choices belong to the user: who can see a chat (`chats`: private, shared
+  or isolated) and whether the agent may change data. If the request or
+  repository does not settle one, ask ONE short, plain-language question with a
+  recommended answer, before building. Never ask what the repository answers.
+- Do not ask about background work, schedules, session length or credential
+  lifetime up front. Long agent sessions just work. Only when the requested
+  feature itself is scheduled or runs in the background (for example "email me
+  a weekly report"), ask for the missing details (day, time, time zone, where
+  results appear) and say in one sentence why you need them. See
   [Discovery and autonomy](references/discovery-and-autonomy.md).
 - Use a reversible, clearly stated default only for choices outside those four,
   or when the user explicitly said not to ask. A busy user is not that signal.

package/src/bundled_default_skills/opengeni-client/references/agent-recipes.md

@@ -77,7 +77,7 @@ session a short-lived per-user bearer and rotate it on every message:
    never send credential updates itself.
 4. The MCP server validates the token and enforces the user's own permissions.
 
-Make the token outlive one turn (agents can work for many minutes). Header
+Make the token outlive long agent work by default (hours, refreshed on every message); this is a default, never a question for the user. Header
 rotation cannot change the server's URL or tools. Scheduled tasks cannot carry
 inline `mcpServers`; background agents use a workspace MCP connection or
 OpenAPI Integration instead.

package/src/bundled_default_skills/opengeni-client/references/api-workflows.md

@@ -203,6 +203,67 @@ Beyond `initialMessage`/`tools`/`resources`, the create body (`POST /v1/workspac
 - Session creation exposes a workspace-scoped `idempotencyKey` (distinct from the per-call `clientEventId`): forward a stable value so concurrent/retried creates of the same logical session collapse to a single session. Without it every create is independent, so a blind retry can double-create — keep sending a stable key when you retry.
 - Treat unknown event types as extensible timeline entries, not client crashes.
 
+### Read a settled result without caching progress or losing text
+
+`agent.message.completed` means one message ended, not that the turn completed.
+`phase: "commentary"` is progress; even `final_answer` text precedes canonical
+settlement. For a text-result cache, wait for the expected logical turn's
+`turn.completed` and use its original `payload.output`. Empty output or
+`emptyFinalReply` is not a successful report; a wait-ended turn may contain
+`reply` for human attention without a result. Handle failure, cancellation,
+approval and human-input states separately. Do not mark the whole session/goal
+complete merely because one turn settled.
+
+REST `listEvents` defaults to a bounded monitoring/summary projection. A compact
+latest result is also a projection and can truncate long text. For an exact
+saved result, use bounded `listEventPage` reads of original events, check
+`forensicExact`, and follow the returned cursor, not a guessed sequence:
+
+```js
+async function readOriginalResultPage(client, workspaceId, sessionId, after) {
+  const page = await client.listEventPage(workspaceId, sessionId, {
+    mode: "forensic", payloadMode: "full", direction: "after", after, limit: 50,
+    includeTypes: ["agent.message.completed", "turn.completed", "turn.failed",
+      "turn.cancelled", "session.requiresAction", "session.humanInput.requested"],
+  });
+  if (!page.forensicExact ||
+      (page.hasMore && (!Number.isSafeInteger(page.nextAfter) || page.nextAfter <= after))) {
+    throw new Error("An exact result page is not available.");
+  }
+  return page; // truncated/hasMore may mean more exact events, not truncated text
+}
+
+function settledTurnResult(event, expectedTurnId) {
+  if (event.turnId !== expectedTurnId ||
+      ["late_rejected", "duplicate"].includes(event.turnAssociation)) return null;
+  if (event.type === "turn.failed" || event.type === "turn.cancelled") {
+    return { state: event.type === "turn.failed" ? "failed" : "cancelled", text: null };
+  }
+  if (event.type !== "turn.completed") return null;
+  const payload = event.payload ?? {};
+  if (payload.emptyFinalReply === true || typeof payload.output !== "string" || !payload.output.trim()) {
+    return { state: "settled_without_result", text: null };
+  }
+  return { state: "completed", text: payload.output };
+}
+```
+
+Keep the newest candidate plus its original event ID/sequence while following
+`hasMore`; publish/cache only after reaching the current page boundary. Preserve
+the original full text rather than stripping a summary's truncation marker.
+If exact retrieval is unavailable, report that explicitly; do not cache a
+snippet as the final answer. Render only authorized result fields, never raw
+forensic payloads. The existing UI/facade projections are preferable when they
+already fit; this is a narrow backend text-result example, not a new timeline.
+
+Use a background job or nonblocking bounded status ticks when a turn's tools
+call back into the same host. Holding every scarce synchronous request worker
+in a blocking wait can starve those callbacks under concurrency; it is a
+deployment-dependent risk, not an inevitable failure. Bound each read/deadline,
+retain callback capacity, and resume from the saved cursor. For static pages,
+initialize enhancement scripts after their DOM targets exist (`defer`, modules
+or `DOMContentLoaded`); retain the native form/POST fallback.
+
 ## Files
 
 The usual flow is: