@opengeni/runtime 4.6.0 → 4.7.0-canary.37090756480001

package/src/bundled_default_skills/opengeni-client/references/compatibility-and-troubleshooting.md

@@ -47,6 +47,92 @@ module.exports = { createOpenGeniClient };
 
 Keep this initialization on the server: never send the API key to a browser.
 
+## Host errors and uncertain actions
+
+Keep SDK/provider details server-only and return friendly host-branded notices,
+not `error.message`, `error.body`, raw stack traces or a provider's product name.
+Put configuration, dynamic SDK import/initialization, identity resolution,
+upstream calls and local persistence inside the route's error boundary, not only
+the final call. Log a redacted diagnostic with a non-secret correlation ID on
+the server; never copy an SDK exception into the browser response or DOM.
+
+Branding applies to UI-owned labels/notices, not legitimate source quotations,
+code, or user/assistant transcript content; do not rewrite those to hide names.
+Check the installed SDK/React error-copy API separately: changing conversation
+labels does not itself prove that upstream error messages are remapped. Host
+safe-copy guidance alone does not change a package's default error behavior.
+
+When the installed SDK exports `formatErrorMessage(error, fallback?)` (root,
+`@opengeni/sdk/core` or `@opengeni/sdk/browser`), use it for custom-renderer error
+copy. Typed errors produce neutral, state-aware messages and retain a bounded
+support reference; an unrecognized error uses the supplied safe fallback, never
+its raw message. The original error's `message`, `body`, `details`, `status`,
+`code`, `retryable` and `outcomeUnknown` remain diagnostic/policy facts.
+
+The matching React package provides `OpenGeniProvider.formatError`, with the
+exported type `ErrorMessageFormatter`:
+`(error: unknown, defaultMessage: string) => string | undefined`. It receives
+the original error and neutral default before presentation. Return a host
+message; `undefined` or an empty string keeps the default. A minimal branding
+callback preserves its state guidance and support reference. A throwing callback
+or invalid runtime return also keeps the neutral default; presentation must not
+interrupt delivery-state settlement:
+
+```js
+function formatAssistantError(_error, defaultMessage) {
+  return `ACME Assistant: ${defaultMessage}`;
+}
+```
+
+Pass this as `formatError={formatAssistantError}` on the existing provider.
+Keep heading/placeholder/label overrides separately. Explicit host-authored
+error props and custom command messages still need safe host copy; this callback
+does not rewrite user, assistant, tool, worker or Skill content. Do not regex
+scrub those strings or stringify diagnostic errors. Check the installed exports
+and provider prop before using these additive APIs; source guidance is not
+proof that an older installed/published package contains them.
+
+Formatting is presentation only: it does not authorize calls, change retry
+policy or reconcile an uncertain mutation. Preserve the default's sign-in,
+permission, setup/allowance, HTTPS-upload and unknown-outcome instructions when
+customizing it. Keep diagnostics server-only/redacted and retain only the
+bounded support reference needed by the UI, not a raw diagnostic body.
+
+For an approval route, distinguish an accepted decision from completed tool
+execution. If the call returns a decision event and local mapping/receipt save
+then fails, the decision may already be durable. `outcomeUnknown: true` also
+means acceptance may have occurred. Neither case justifies "the article is
+unchanged", a fresh approval ID or a blind replay. Keep the original session,
+approval ID and persisted `clientEventId`; reread ordered events and the
+authorized provider record to reconcile. Only retry the exact original request
+under the installed endpoint's supported idempotency contract after reconciliation.
+For stale/no-pending approval conflicts, refresh current state instead of
+recreating a pending card or exposing the raw upstream error.
+
+```js
+function assistantFailureNotice(error, { decisionAccepted = false } = {}) {
+  if (decisionAccepted || error?.outcomeUnknown === true) {
+    return {
+      state: "reconciling",
+      message: "The action may have been accepted. Check its status before trying again.",
+    };
+  }
+  if (error?.status === 409) {
+    return { state: "refresh", message: "This request has changed. Refresh before deciding." };
+  }
+  return { state: "failed", message: "The assistant is unavailable. Please try again later." };
+}
+```
+
+This helper is for the host's approval-action error boundary, not a replacement
+for authentication/authorization responses. Set `decisionAccepted = true`
+immediately after `await sendApprovalDecision(...)`, before any local save.
+Disable repeat actions while `state === "reconciling"`; render only this safe
+notice and use the existing host status/error conventions. Apply the same
+safe-copy boundary to polling, configuration and generic SDK failures. Test
+stale approval, an unknown mutation outcome, accepted-decision/local-save failure,
+SDK initialization failure and late errors after an identity switch.
+
 ## Decide what is being replaced
 
 | Customer dependency | Evidence needed |

package/src/bundled_default_skills/opengeni-client/references/data-tools-and-credentials.md

@@ -160,6 +160,88 @@ or rotation through the authorized owner.
 
 Tool selection is not data authorization. The customer API must validate the presented credential on every operation and derive or verify the allowed tenant, user, report, and row scope. Do not trust model-supplied tenant IDs. Prefer endpoints whose server derives scope from token claims; when an ID is accepted, verify it belongs to those claims.
 
+An agent bridge needs an independently scoped provider credential, not an
+ordinary host login JWT with fewer tools listed. A token signed with the host's
+normal login secret and user ID may still authorize its account/password APIs;
+an OpenAPI/MCP allowlist does not restrict that bearer outside the tool surface.
+Prefer a separate signing key/token namespace plus a distinct issuer/audience,
+short expiry and explicit operation/record scope. Verify those claims on the
+bridge, and make ordinary host endpoints reject this credential entirely. Adding
+an audience claim is ineffective if the ordinary host verifier never checks it.
+Reuse authorized business logic, not the ordinary login credential or middleware.
+
+Before launch, test the actual middleware in both directions: the provider token
+can perform only its allowed read/title-only operation on an owned record; it
+cannot call the ordinary account/password/admin APIs, another user's record or
+an extra body field; an ordinary login token is not a bridge credential. Check
+expiry, issuer/audience and operation scope with negative tests. These are host
+authorization tests, not proof supplied by OpenGeni's tool selection or approval.
+
+### Reauthorize current host policy, not only signed claims
+
+After verifying the provider token's signature, issuer/audience and expiry,
+reload the current host user and its membership/record-owner policy for each
+call. A disabled owner or downgraded role must lose authority even while an old
+JWT remains cryptographically valid. For writes, recheck at the transaction
+boundary; a prior read is not a permission lease. The host-owned adapter below
+uses illustrative policy fields, not an OpenGeni token/SDK schema:
+
+```js
+function requireLiveToolAuthority(claims, user, grant, operation) {
+  if (typeof claims?.subjectId !== "string" || !claims.subjectId ||
+      typeof claims.tenantId !== "string" || !claims.tenantId ||
+      user?.enabled !== true || user.id !== claims.subjectId ||
+      grant?.active !== true || grant.subjectId !== user.id ||
+      grant.tenantId !== claims.tenantId ||
+      !Array.isArray(grant.operations) || !grant.operations.includes(operation) ||
+      !Array.isArray(claims.operations) || !claims.operations.includes(operation)) {
+    throw new Error("Tool request is not authorized.");
+  }
+  return { subjectId: user.id, tenantId: grant.tenantId };
+}
+
+// Website-share credentials are not team-report credentials.
+function websiteShareMayReadReport(share, report) {
+  return share?.kind === "website-share" &&
+    typeof share.websiteId === "string" && share.websiteId.length > 0 &&
+    report?.scope?.kind === "website" &&
+    report.scope.websiteId === share.websiteId;
+}
+
+// Host parses dates into validated UTC milliseconds; this example is half-open.
+function requireAuthorizedWindow(requested, allowed) {
+  if (![requested.start, requested.end, allowed.start, allowed.end].every(Number.isSafeInteger) ||
+      requested.start >= requested.end || allowed.start >= allowed.end ||
+      requested.start < allowed.start || requested.end > allowed.end) {
+    throw new Error("Requested date window is not authorized.");
+  }
+  return requested;
+}
+```
+
+Load `user` and `grant` from fresh trusted host records, never from browser/model
+fields or the token's old role alone. The token is only a ceiling. After this
+check, still authorize each requested record and field against that context.
+A one-user workspace still requires enabled-owner and record-ownership checks.
+
+### Scope report reads and publication
+
+Authorize the stored report's actual scope on list, summary, detail and export
+routes. A website-share credential must not expose a team report merely because
+that team contains the shared website. Filter summaries before returning them;
+transcript access is a separate check. Signed-in team sharing remains valid under
+its own current membership policy; the website-share helper is not that policy.
+The host derives this persisted scope from authorized records, not an unchecked
+editor-submitted authorization/provenance field.
+
+Enforce the advertised analytics window in the server/provider query, including
+time zone and the provider's boundary conventions, not only in prompts or UI.
+Bind reopening/export headers and session lookup to the currently selected
+report's immutable ID and authorized session, not the first mounted report.
+Persist generated-report provenance on the trusted backend from verified
+session/job receipts. An ordinary editor's submitted body or `generated` flag
+cannot establish that provenance or impersonate a different session/author.
+
 Separate operations by risk. Read-only analytics, data export, saved-report mutation, and administrative actions should not share an unnecessarily broad token or approval policy. Keep destructive or consequential writes absent or approval-gated unless the customer explicitly wants autonomous writes.
 
 For analytics, return structured, bounded data with clear units, time zones, filters, pagination, and aggregation semantics. Provide server-side aggregates where practical. The agent may combine tool calls or use CodeMode to transform authorized results without placing every intermediate row in conversational context. Code execution happens in the selected OpenGeni sandbox or Connected Machine; provider credentials remain in the broker. Confirm that the installed tool surface is available to CodeMode before relying on that optimization.

package/src/bundled_default_skills/opengeni-client/references/discovery-and-autonomy.md

@@ -37,11 +37,13 @@ platform work separate from an ordinary customer's integration responsibilities.
 
 ## Ask the exact amount
 
-The four user-owned choices (who shares what, when things run and in which time
-zone, where outputs land, whether the agent may write) are never defaulted
-silently: if the request or repository does not settle one, send the single
-bundled question before building the parts that depend on it, and continue only
-independent discovery while waiting. Skip this only when the user explicitly
+The user-owned choices (who shares what, whether the agent may change data,
+and, only for background or scheduled work, when it runs and where its results
+should appear) are never defaulted silently: if the request or repository does
+not settle a relevant one, send a single short question in plain product terms
+before building the parts that depend on it, and continue only independent
+discovery while waiting. A chat assistant's replies appear in the chat; that is
+not a question to ask. Skip this only when the user explicitly
 said not to ask; then state the defaults you chose in the handoff. For other
 choices, first use facts already available from the product, repository, live
 service, or prior direction, and use a reversible recommendation instead of a
@@ -64,26 +66,31 @@ user accept it or adjust individual choices. Do not build a new questionnaire or
 ask every integration the same questions. A suggested answer is not consent to
 send data, share private content, or perform an external action.
 
-Use product language for the relevant unresolved choices:
-
-- **Learning across chats:** no new lasting learning, remember for each person,
-  or shared team knowledge. Explain briefly that chat history/retention is separate
-  and disabling learning does not delete history or existing authorized Knowledge.
-- **Who can open chats:** only their owner (`chats: "private"`), the team
-  (`"shared"`), or a workspace per user (`"isolated"`). Choose the
-  workspace mapping from the actual sharing boundary; private chats alone do not
-  require a workspace per person.
-- **How the agent gets data:** current-page snapshots, read-only tools to fetch
-  more reports, or controlled queries for deeper analysis. State the meaningful
-  limitation of the recommendation. Confirm broader access or writes separately
-  only when they are part of the requested product.
-- **When things run:** on demand, or on a schedule (time and time zone).
-- **Where results land:** the chat, a product record or screen, or a channel;
-  delivery goes through product tools, or signed workspace webhooks where the
-  deployment offers them.
-
-For example, if all three choices are unresolved for a simple dashboard, propose
-“Private chats, no learning between chats, and current-page data only” with a short
+Write every question the way the end user talks about their own product. Never
+use internal terms such as "on-demand", "learning across chats", "shape",
+"capabilities" or "visibility". Only ask about what applies:
+
+- **Who can see a chat:** only the person who started it (`chats: "private"`),
+  their whole team (`"shared"`), or each user gets a fully separate space
+  (`"isolated"`). Choose the workspace mapping from the actual sharing boundary;
+  private chats alone do not require a workspace per person.
+- **What the agent may do:** only look things up (read-only), or also make
+  changes. Name the actual things ("read your analytics", "can't change
+  websites or users"). Confirm writes separately, only when they are part of
+  the requested product.
+- **What data it uses:** only what's on the current page, or it can look up
+  more on its own. State the meaningful limitation of the recommendation.
+- **Only when the requested feature is itself scheduled or runs in the
+  background** (for example "email me a weekly report"): the missing details
+  (when it runs, "every Monday at 9:00, Oslo time", and where results should
+  appear) with one sentence on why. Never ask about this up front, and never
+  for a chat assistant: long sessions work without any user decision.
+- **Memory:** don't ask by default. Use no lasting memory between chats unless
+  the product clearly needs the assistant to remember things ("remember my
+  preferences"). If it does, ask in those words. Chat history is kept either way.
+
+For example, for a simple dashboard assistant, propose
+“Only you can see your chats; it uses what's on the current page and can't change anything” with a short
 explanation that the agent cannot fetch another report on its own. Do not reuse
 that default for a team assistant whose requirements already imply shared work.
 Continue independent discovery while awaiting an answer; ask again only when new

package/src/bundled_default_skills/opengeni-client/references/external-users-and-connect.md

@@ -82,6 +82,14 @@ invalid Unicode are rejected. A native-looking ID does not impersonate a native
 user. Workspace mapping identity passed to `ensureWorkspace` is a separate
 concept from this acting-user identity.
 
+Use an immutable database/auth subject ID, never an editable username, email or
+display name. Renaming must keep the same external ID and private history;
+reassigning a username must not reassign the previous actor's identity. History
+collision on username reuse is conditional on the host allowing reuse, not a
+guarantee about every host. Derive the ID anew from current authentication rather
+than a mounted component's old user object; apply the
+[identity/session epoch fence](product-shapes-and-ui.md#bind-asynchronous-ui-work-to-the-current-identity-and-session).
+
 User mode lazily establishes an external identity but does not grant access to a
 shared workspace. An explicitly authorized service onboarding operation may use:
 
@@ -102,6 +110,15 @@ needs `capabilities:manage`; do not add it unless installation is a product
 feature the user may perform. User requests intersect actual membership with
 the initiating key's permissions. Service administration remains separate.
 
+Check the host user's current enabled state, tenant membership and role on every
+session read/control route and every provider call. A still-valid token or an
+old `sessions:control` onboarding grant is not proof of current host authority.
+Block newly disallowed requests immediately and reconcile OpenGeni grants using
+the authorized membership lifecycle below; do not silently re-onboard or widen
+them on a user request. Permission-changing revocation can cancel running work.
+Per-user workspaces and deliberate team/site sharing are valid product choices,
+but neither replaces these current host-policy checks.
+
 ### Read the member inventory: SDK versus REST
 
 ```ts

package/src/bundled_default_skills/opengeni-client/references/product-shapes-and-ui.md

@@ -12,6 +12,25 @@
 
 Default to the full conversation component. Deviate only when the product needs a materially different interaction model, a non-React frontend, or compute surfaces, and record why. Styling differences alone are not a reason: theme with `--og-*` tokens and density props. Do not mount the workbench for an ordinary analytics chat, and do not rebuild session streaming, replay, queueing, approval, or timeline projection that a package already supplies.
 
+## Stock and host-branded appearance
+
+For a custom-branded embed, visibly match the host's fonts, colors, spacing,
+radius and current theme using the shipped stylesheet, scoped `--og-*` tokens
+and supported theme/density/label hooks. Keep UI-owned copy free of OpenGeni
+branding; source quotations and user/assistant content are not UI labels. Verify
+the installed error-copy API separately, not just the heading/placeholder.
+
+Stock mode uses the shipped components and `compiled.css` without extra host
+cosmetic CSS. The quality target is simple, polished and smooth at desktop
+around 1440px and mobile around 390px in supported light/dark themes. Host
+placement/available height remains host-owned. A stock defect belongs in the
+package's React/CSS, not a host styling workaround or a replacement chat UI.
+Do not present this expectation as proof that a particular build passed.
+
+Preserve first-try evaluation evidence when later repairs improve the result.
+In coordinated trials, the coordinator captures the actual browser matrix;
+do not make screenshot submission a prerequisite for the coding-agent handoff.
+
 ## When deviating in React
 
 Inspect the installed OpenGeni React package before creating replacement components. Its subpaths are composable, and the styled surfaces use scoped compiled CSS plus runtime theme and density tokens. Prefer, in order: `SessionConversation` customized through `composerProps` and `renderMessageText`; `MessageTimeline`, `ChatComposer`, and the session hooks composed into product layout; then a fully custom SDK-driven UI. Do not force a packaged component when the product needs a materially different interaction model.
@@ -145,6 +164,70 @@ For live sessions, preserve event sequence, reconnect, replay, and duplicate sup
 
 Uploads may send bytes directly to a short-lived signed storage URL returned by the trusted flow. That URL is narrow transfer authority, not the OpenGeni API key. Verify storage CORS for every intended browser origin.
 
+### Bind asynchronous UI work to the current identity and session
+
+In a custom polling/static UI, backend authorization does not stop an already
+authorized response for account A arriving after account B signs in. On logout,
+login, tenant switch or session switch, invalidate the UI epoch, abort outstanding
+requests, stop polling, and clear private messages, approval cards, session IDs,
+cursors and local caches. Do not reuse A's session ID for B. Abort alone is not
+enough: a completed request or a transport that ignores abort can still resolve.
+Guard both success and failure rendering by the captured identity/session epoch.
+
+These framework-neutral helpers belong in the host's existing frontend module:
+
+```js
+function createIdentityBoundView(clearPrivateState) {
+  let epoch = 0;
+  let identityKey = null;
+  const requests = new Set();
+  return {
+    reset(nextIdentityKey) {
+      epoch += 1; // also fences A -> B -> A and a new session for the same user
+      identityKey = nextIdentityKey;
+      for (const controller of requests) controller.abort();
+      requests.clear();
+      clearPrivateState(); // include polling timers, cached IDs and decisions
+    },
+    begin() {
+      if (identityKey === null) throw new Error("No authenticated view");
+      const capturedEpoch = epoch;
+      const controller = new AbortController();
+      requests.add(controller);
+      return {
+        signal: controller.signal,
+        isCurrent: () => capturedEpoch === epoch && !controller.signal.aborted,
+        finish: () => requests.delete(controller),
+      };
+    },
+  };
+}
+
+async function readForCurrentView(view, load, render, showFailure) {
+  const request = view.begin();
+  try {
+    const result = await load(request.signal);
+    if (request.isCurrent()) render(result);
+  } catch {
+    if (request.isCurrent()) showFailure("The assistant could not refresh.");
+  } finally {
+    request.finish();
+  }
+}
+```
+
+Call `view.reset(null)` before clearing host authentication; after authenticated
+mapping, reset with a key for the tenant/user/session tuple before loading its
+view. `load(signal)` calls the host's authenticated same-origin route and passes
+the signal to `fetch`. The epoch is a presentation fence, not authorization:
+the backend must still check every request's user and session ownership. Do not
+run these browser helpers with an organization key or put that key in storage.
+
+For reopened reports, key the selected report and its authorized session together.
+Refresh request headers/mappings when that selection changes; do not keep the
+first report's session in a mounted closure. A new actor object in the same
+component still requires reset/invalidation, not only a logout-time unmount.
+
 ## Decide what the user sees
 
 OpenGeni's durable event stream can support different product projections:
@@ -159,6 +242,79 @@ The customer frontend chooses which event types and fields to render. Hiding an
 
 Each `session.requiresAction` event replaces the pending approval set. Read only `payload.approvals[].id`, `.name`, and `.arguments` (SDK type `SessionApprovalRequest`); other fields differ between a turn's first pause and later ones and exist for compatibility. Send `sendApprovalDecision({ approvalId: approval.id, decision })`: `id` is the pending tool call id, not the event id. `approvalsFromRequiresAction` / `projectPendingApprovals` from `@opengeni/react` already normalize older events.
 
+For a custom non-React projection, fold ordered, deduplicated events rather than
+appending every historical approval as a new pending card. Keep the original
+approval ID and the durable decision event ID. A decision is terminal for that
+approval; a replay/reload must not restore its Approve button. Turn settlement
+clears that turn's undecided approvals, not approvals owned by a different turn.
+The following minimal projection uses current stable fields; use the packaged
+normalizer for older events, not generated IDs or guessed compatibility fields:
+
+```js
+function projectApprovalState(events) {
+  let pending = new Map();
+  let owningTurnId = null;
+  const decisions = new Map();
+  const settledTurns = new Set();
+  for (const event of events) {
+    const payload = event.payload ?? {};
+    if (event.type === "session.requiresAction") {
+      owningTurnId = event.turnId ?? null;
+      pending = new Map();
+      if (owningTurnId !== null && settledTurns.has(owningTurnId)) continue;
+      for (const approval of Array.isArray(payload.approvals) ? payload.approvals : []) {
+        if (!approval || typeof approval.id !== "string" || !approval.id ||
+            typeof approval.name !== "string" || !approval.name || decisions.has(approval.id)) continue;
+        pending.set(approval.id, approval);
+      }
+    } else if (event.type === "user.approvalDecision") {
+      if (typeof payload.approvalId !== "string" || !payload.approvalId ||
+          !["approve", "reject"].includes(payload.decision) || decisions.has(payload.approvalId)) continue;
+      decisions.set(payload.approvalId, {
+        approvalId: payload.approvalId,
+        decision: payload.decision,
+        decisionEventId: event.id,
+      });
+      pending.delete(payload.approvalId);
+    } else if (["turn.completed", "turn.failed", "turn.cancelled"].includes(event.type)) {
+      if (event.turnId != null) settledTurns.add(event.turnId);
+      if (owningTurnId === null || event.turnId == null || event.turnId === owningTurnId) {
+        pending.clear();
+        owningTurnId = null;
+      }
+    }
+  }
+  return { pending: [...pending.values()], decisions: [...decisions.values()] };
+}
+
+// Example for a known title-only operation, not a generic approval formatter.
+function exactTitleProposal(approval) {
+  try {
+    const args = typeof approval.arguments === "string"
+      ? JSON.parse(approval.arguments) : approval.arguments;
+    const body = args?.body;
+    if (!body || Array.isArray(body) || Object.keys(body).some((key) => key !== "title")) return null;
+    return typeof body.title === "string" && body.title.trim() ? body.title : null;
+  } catch {
+    return null;
+  }
+}
+```
+
+Render arguments using the selected operation's schema: for this example the
+title is `arguments.body.title`, not `arguments.title`. Use escaped text, retain
+the exact string (do not silently trim/change it), and also display the target
+record and operation. Enable Approve only for a currently pending, authorized
+request whose exact proposal and target can be shown. Missing/malformed proposal
+means disabled Approve, not a placeholder beside an enabled button; Reject or
+refresh can remain available. The provider still enforces record ownership,
+allowed fields and any expected-version/CAS precondition on the actual write.
+
+Persist a stable `clientEventId` before `sendApprovalDecision`, retain the
+returned decision event, and reconcile after an uncertain response or a local
+save failure. Accepted approval means a decision was accepted, not that its
+provider write completed. See [Failure and reconciliation](compatibility-and-troubleshooting.md#host-errors-and-uncertain-actions).
+
 Even a final-answer-only UI should surface states the user must act on: failure, cancellation, credit or policy denial, approval requests, human-input requests, reconnect status, and a way to retry safely. Avoid presenting tool failures as ordinary assistant prose when product state can represent them more clearly.
 
 ## Opening host-owned workbench tabs

package/src/bundled_schedule_skills/opengeni-schedules/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: opengeni-schedules
+description: Create a schedule, recurring task, reminder, or monitor in OpenGeni. Read this before turning a user's request into scheduled work, including Create with OpenGeni from Schedules. Discover the required resources and integrations, then create the task with the user's cadence and time zone.
+---
+
+# Create a schedule
+
+Turn the user's description into scheduled work in the current workspace.
+Research what is available before asking questions. Ask only for essential
+details you cannot discover or reasonably decide from the request.
+
+## Discover what the task needs
+
+- Use `scheduled_tasks_list` to avoid duplicating an existing schedule. Follow
+  pagination when needed and use `scheduled_tasks_get` for a relevant task's
+  details. A list summary is not its complete configuration.
+- If the work needs a repository, use `github_repositories_list` to find the
+  authorized repository and select the required resources.
+- If it needs sandbox credentials, use `variable_set_list` to find the suitable
+  Variable Set. Attach its identifier; do not copy secret values into prompts.
+- If it needs an integration such as Slack or Sentry, use
+  `capability_catalog_search` and the available tool discovery to find the
+  capability and exact operations. Follow returned connection/setup and approval
+  requirements. Do not claim that discovery means the integration is ready.
+
+Select only the resources, Variable Set, and tools the task needs. Missing
+optional dependencies are not a reason to ask for unnecessary setup. If a
+required capability or authority is unavailable, explain the remaining setup
+briefly instead of inventing a tool or borrowing another person's connection.
+
+## Create and verify
+
+Use `scheduled_tasks_create` with:
+
+- A short, descriptive name.
+- A self-contained `agentConfig.prompt` that each run can start from: the work,
+  relevant sources and destinations, what to report, and when to stay quiet.
+  Preserve the user's requested brevity and notification conditions.
+- The requested cadence and time zone. Use the time zone supplied in the
+  request unless the user explicitly chooses another. Inspect the current tool
+  schema for supported schedule shapes rather than guessing cron fields.
+- The required repository resources, Variable Set, and tool selections.
+  Scheduled runs inherit the creating session's tool and permission ceiling;
+  this Skill does not grant authority or change approvals.
+
+Honor an explicit run destination. A task prompt must not depend on unrecorded
+details from the setup conversation. Do not trigger an extra run or send a test
+message unless the user asks for one.
+
+Check the creation receipt and follow its `scheduled_tasks_get` next action to
+verify the saved task before claiming success. If it reports a committed
+task with a synchronization failure, report that state and recover the existing
+task rather than creating a duplicate. On success, briefly tell the user the
+schedule's name and first expected run in their time zone. If the exact first
+firing cannot be verified from the saved schedule, say so rather than inventing
+a timestamp.

package/src/claude-subscription-usage.ts

@@ -1,11 +1,26 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 
-type Observer = (providerId: string, response: Response) => void;
-type Prepare = (providerId: string, headers: Headers) => Promise<Headers>;
+type Observer = (
+  providerId: string,
+  response: Response,
+  upstreamModelId?: string,
+  requestToken?: string | null,
+) => void;
+type PreparedUsageRequest = { headers: Headers; observe: Observer };
+type Prepare = (providerId: string, headers: Headers) => Promise<Headers | PreparedUsageRequest>;
 const observers = new AsyncLocalStorage<{
   observe: Observer;
   prepare?: Prepare;
 }>();
+const modelRequests = new AsyncLocalStorage<string>();
+
+/** The native adapter knows the exact model without reading or cloning the wire body. */
+export function withClaudeModelRequest<T>(
+  upstreamModelId: string,
+  run: () => Promise<T>,
+): Promise<T> {
+  return modelRequests.run(upstreamModelId, run);
+}
 
 /** Like Codex usage headers: free observations within this turn's provider context. */
 export function withClaudeUsageObserver<T>(
@@ -20,15 +35,46 @@ export async function prepareClaudeSubscriptionRequest(
   input: Parameters<typeof fetch>[0],
   init?: RequestInit,
 ) {
-  const prepare = observers.getStore()?.prepare;
-  if (!prepare) return init;
-  const headers = new Headers(input instanceof Request ? input.headers : undefined);
-  new Headers(init?.headers).forEach((value, key) => headers.set(key, value));
-  return { ...init, headers: await prepare(providerId, headers) };
+  const context = observers.getStore();
+  const upstreamModelId = modelRequests.getStore();
+  let observe = context?.observe;
+  if (context?.prepare) {
+    const headers = new Headers(input instanceof Request ? input.headers : undefined);
+    new Headers(init?.headers).forEach((value, key) => headers.set(key, value));
+    const prepared = await context.prepare(providerId, headers);
+    init = { ...init, headers: prepared instanceof Headers ? prepared : prepared.headers };
+    if (!(prepared instanceof Headers)) observe = prepared.observe;
+  }
+  return {
+    init,
+    observe(response: Response, requestToken?: string | null) {
+      try {
+        observe?.(providerId, response, upstreamModelId, requestToken);
+      } catch {
+        // Telemetry must neither consume nor change the model response.
+      }
+    },
+  };
+}
+export function captureClaudeRequestToken(input: Parameters<typeof fetch>[0], init?: RequestInit) {
+  if (!observers.getStore()) return undefined;
+  const headers = new Headers(
+    init?.headers !== undefined
+      ? init.headers
+      : input instanceof Request
+        ? input.headers
+        : undefined,
+  );
+  return headers.get("authorization")?.match(/^Bearer (.+)$/i)?.[1] ?? null;
 }
-export function observeClaudeUsageResponse(providerId: string, response: Response): void {
+
+export function observeClaudeUsageResponse(
+  providerId: string,
+  response: Response,
+  requestToken?: string | null,
+): void {
   try {
-    observers.getStore()?.observe(providerId, response);
+    observers.getStore()?.observe(providerId, response, modelRequests.getStore(), requestToken);
   } catch {
     // Usage telemetry must never change or consume a model response.
   }