@gea-ai/agent-sdk 0.1.260911-alpha.2 → 0.1.260914-alpha.0

package/README.md

@@ -2,6 +2,525 @@
 
 The TypeScript SDK for building GEA Agent applications.
 
+`@gea-ai/agent-sdk` is the code-first authoring SDK for GEA Agent
+applications. It defines main Agents, package-local executable Tools, Skill
+references, Agent-owned Durable Objects, and secret-free Connector definitions
+and requirements.
+
+The SDK retains executable handlers for Worker runtime use.
+`createAgentPackageSnapshot()` produces deterministic JSON-compatible metadata
+for validation, Studio display, and exact-version execution. Snapshots never
+contain handler functions, credentials, Connector Connections, tenant identity,
+provider configuration, or environment values.
+
+## Tenant application authentication
+
+Agent HTTP accepts Project API keys and GEA user OAuth tokens by default. Push the
+Worker and associate the Agent with its app in **Studio → Applications**. Publish
+the entry in Preview or Production from the Agent page. Subsequent pushes advance
+Preview; one explicit Production publish updates all published entries in that
+Worker. Unpublished sibling Agents remain unavailable to application users.
+
+Every tenant uses the same two Worker URLs:
+
+- Preview: `https://preview--worker--<workerId>.<apex>/gea/agents/<agentKey>/run`
+- Production: `https://worker--<workerId>.<apex>/gea/agents/<agentKey>/run`
+
+For store distribution, a Global Admin reviews application information, then
+installs the approved application into a consumer tenant from **Published applications**.
+Installation enables Production and the approved scopes, including `agents:invoke`;
+it does not require or create a Workspace. Preview additionally requires publisher
+approval for external test tenants and explicit environment enablement. The
+application starts standard OAuth; GEA confirms the actual user and consumer tenant
+and resolves the installation internally. Do not send an installation ID.
+
+```ts
+import { StudioAgentClient } from "@gea-ai/agent-sdk/studio-server";
+
+const agent = new StudioAgentClient({
+  api: copiedEnvironmentUrl, // The copied /run URL is accepted directly.
+  token: currentUserAccessToken,
+});
+const response = await agent.run({ message: "Hello" });
+```
+
+The token identifies the user, app and tenant; the URL selects the environment
+and Agent. Users need current consumer tenant membership and application authorization.
+Their configuration, Connections, Chats, files and traces belong to that environment
+installation. Existing Chat/Run calls retain their pinned execution version;
+historical Workspace-bound records still require access to that Workspace.
+
+`projectKeyAuth()` and Project API Keys retain Studio development access. `token`
+accepts either credential, subject to the Agent's declared auth; a Project Key does
+not represent a tenant user or grant cross-tenant installation access. There is no
+third marketplace URL. Standalone Worker OAuth publication remains future work.
+
+## Agent Authoring Shapes
+
+A single-main application starts with root `agent.ts` and `AGENTS.md`:
+
+```ts
+import { defineAgent } from "@gea-ai/agent-sdk";
+
+export default defineAgent({
+  model: "gea-model-1",
+  name: "research-agent",
+  slug: "research-agent",
+});
+```
+
+An Agent may instead declare capability thresholds for the SDK's first-party
+Creative Reasoning router:
+
+```ts
+export default defineAgent({
+  model: "auto",
+  modelRequirements: {
+    agentic: 0.8,
+    copywriting: 0.6,
+    multimodal: 0.4,
+    speed: 0.7,
+  },
+  name: "research-agent",
+  slug: "research-agent",
+});
+```
+
+Each requirement is an optional minimum score from `0` to `1`; omitted
+dimensions do not constrain selection. `modelRequirements` is required for
+`model: "auto"` and rejected for a concrete model. The SDK filters its curated
+Creative Reasoning capability table and selects the eligible model with the
+lowest configured cost rank. It writes only the selected concrete CR gateway
+model ID into the package snapshot, so runtime model selection does not change
+when a later SDK updates the table.
+
+This table is maintained in the SDK; it does not query CR model discovery,
+verify API-key access, or read the deployment's model catalog or prices.
+Capability scores and cost ranks are provisional routing parameters rather
+than official platform measurements or actual catalog prices. The following
+candidate IDs and upstream mappings were supplied by the platform owner on
+2026-09-05; authenticated access still needs verification for each deployment.
+The mapping is developer information and is not a product display label.
+
+| CR gateway model ID      | Upstream mapping  | Cost rank | Agentic | Copywriting | Multimodal | Speed |
+| ------------------------ | ----------------- | --------- | ------- | ----------- | ---------- | ----- |
+| `deepseek-v4-flash`      | DeepSeek V4 Flash | 1         | 0.5     | 0.5         | 0          | 1     |
+| `crr-q-flash-20260826`   | Qwen3.8 Flash     | 2         | 0.55    | 0.6         | 0          | 1     |
+| `crr-o-mini-20260710`    | gpt-5.6-luna      | 3         | 0.55    | 0.45        | 0.55       | 1     |
+| `deepseek-v4-pro`        | DeepSeek V4 Pro   | 4         | 0.8     | 0.75        | 0          | 0.65  |
+| `crr-q-pro-20260804`     | Qwen3.8 Max       | 5         | 0.85    | 0.8         | 0          | 0.6   |
+| `crr-o-20260710`         | gpt-5.6-terra     | 6         | 0.8     | 0.7         | 0.75       | 0.7   |
+| `creative-reasoning-1.5` | Claude Sonnet 5   | 7         | 0.8     | 0.9         | 0.7        | 0.65  |
+| `crr-o-pro-20260710`     | gpt-5.6-sol       | 8         | 0.95    | 0.82        | 0.85       | 0.45  |
+| `crr-a-pro-20260724`     | Claude Opus 5     | 9         | 1       | 1           | 0.85       | 0.35  |
+
+Qwen and DeepSeek currently have a zero multimodal routing score until their
+gateway support is verified; any positive multimodal requirement excludes
+them. Existing GPT and Claude routing thresholds are retained. With this
+candidate set, `multimodal: 0.9` or `{ multimodal: 0.8, speed: 0.9 }` has no
+eligible model and fails during Agent definition. Removing an auto candidate
+does not invalidate an explicit model declaration or an existing snapshot.
+
+For hosted execution, register these nine IDs in
+`LLM_MODEL_CATALOG_JSON.models`, using `creative-reasoning/<gateway-model-id>`
+targets and actual target-keyed prices. Keep the existing `gea-fast` and
+`gea-pro` aliases and set `selectableModels: ["gea-fast", "gea-pro"]` so normal
+product selectors show only those aliases. Studio developers can inspect the
+immutable version's model but cannot override it in Playground.
+
+`defineAgent({ model: "auto", ... })` provides contextual field completion for
+all four requirements. Standalone input annotations require a model type:
+`DefineAgentInput<"auto">` requires the capability fields, while
+`DefineAgentInput<"crr-a-pro-20260724">` forbids them. There is no implicit
+`string` model parameter, because it would also accept `"auto"` without its
+requirements. Direct `defineAgent(...)` calls infer the model type.
+
+A concrete first-party model may use any unqualified public ID, such as
+`crr-a-pro-20260724`, `creative-reasoning-1.5`, or
+`creative-reasoning-1.5-flash`. An explicit Creative Reasoning provider ID such
+as `creative-reasoning/kimi-k3` is also supported. The snapshot preserves the
+declared concrete ID.
+
+Tools, Connectors, Hooks, referenced Skills, and local Skills are discovered
+from conventional sibling directories. The required `slug` is the Agent's
+stable identity inside this Worker application. It becomes the manifest and
+runtime `agentKey`; `name` remains display metadata.
+
+A root Agent may stay in place when the application adds more main Agents under
+`agents/<slug>/agent.ts`. This preserves the original Agent's identity and
+root `benchmarks/`. A directory Agent's declared slug must match its directory
+name. Applications without a root Agent may use `agents/default/` as the
+default source alias; that Agent still declares a real non-reserved slug. If
+there is no root or `agents/default/`, the lexically first directory Agent owns
+the default route. `default`, `run`, and `sessions` are reserved protocol
+segments and cannot be Agent slugs.
+
+```text
+agents/default/agent.ts
+agents/default/AGENTS.md
+agents/support/agent.ts
+agents/support/AGENTS.md
+```
+
+Add root `worker.ts` only when the same Worker also serves UI, business APIs,
+assets, or application Durable Objects. The CLI generates Agent assembly and
+prepends it to the application handler. Developers do not list Tools, Skills,
+or Connectors again in `worker.ts`.
+
+Generated code uses `createAgentApplicationFetch()`, which owns:
+
+```text
+/gea/agents/run
+/gea/agents/<agentKey>/run
+/gea/agents[/<agentKey>]/sessions/<sessionId>/v1/<operation>
+```
+
+Hosted Agent HTTP handlers accept Project API keys and platform user tokens by
+default, equivalent to this explicit configuration:
+
+```ts
+import {
+  defineAgent,
+  projectKeyAuth,
+  platformUserAuth,
+} from "@gea-ai/agent-sdk";
+
+export default defineAgent({
+  name: "support",
+  slug: "support",
+  model: "gea-model-1",
+  http: { auth: [projectKeyAuth(), platformUserAuth()] },
+});
+```
+
+Set `auth: projectKeyAuth()` or `auth: platformUserAuth()` to accept only that
+credential type. Explicit configuration replaces the default; it never appends
+the other built-in method. Key calls retain Project ownership, while user tokens
+require application installation admission and keep the consumer's installation
+ownership. The two identities and permissions are never combined. These rules
+apply to Agent routes; ordinary routes in `worker.ts` retain their own authentication.
+
+```ts
+// Inside defineAgent(...):
+http: {
+  auth: false;
+} // Explicit public access to this Agent's HTTP API.
+```
+
+An application can replace the default with its own Session authenticator:
+
+```ts
+http: {
+  auth: async (request, { environment }) => {
+    const session = await getSession(request, environment); // Your verified session.
+    return session
+      ? { principalType: "user", principalId: session.userId }
+      : null;
+  },
+}
+```
+
+An authenticator returns a verified platform authorization, an external user,
+a `Response`, or `null`. An array runs in order: `null` means this method does
+not apply, while an identity or any `Response` stops the chain. An empty array
+or a chain that returns only `null` rejects with 401. Exceptions stop the chain
+and become an HTTP 500 at the Agent boundary. Built-in methods recognize their
+credential prefix before validation; malformed, revoked or denied credentials
+and service failures never fall through to another identity. Custom methods
+should likewise return an error `Response` for invalid credentials, reserving
+`null` for a method that does not apply. A single custom authenticator returning
+`null` still rejects with 401. Project Keys stay on the backend; they never
+represent the creator's GEA user.
+`authenticateProjectKey(request, environment.PROJECT)` also works in ordinary
+Worker routes with a declared Project binding and a Project attachment.
+
+`OPTIONS /gea/agents/<agentKey>/run` returns only the Agent key, canonical run
+path and HTTP protocol version. It runs before authentication and does not
+execute a model, create a Session or access platform bindings. Hosted push checks
+this response in the final bundle locally, then the server checks the uploaded
+deployment in Worker Runtime before accepting it. Missing, moved or incompatible
+entries require an SDK update and rebuild. Ordinary Worker application paths
+remain developer-owned; this conformance check does not grant Agent access.
+
+Application pages and browser Sessions require the operator's isolated
+`WORKER_APP_BASE_URL`. GEA-domain and path ingress preserve API access but strip
+platform cookies and force CSP sandbox plus `nosniff`; Worker pages cannot run
+scripts there. Application-domain pages retain their own CSP. Local `gea agent dev` uses its
+existing trusted development identity. Raw AgentSession and Connector auth
+operations remain private regardless of `http.auth`. Rebuild and republish old
+Agent packages with the matching SDK/CLI to enable the new hosted handler.
+
+The public run request is intentionally small:
+
+```json
+{ "chatId": "optional-continuation-id", "message": "Hello" }
+```
+
+If `chatId` is absent, the hosted managed API creates a Chat and Run and returns
+their IDs in response headers. Local execution creates its local Session identity.
+Callers cannot supply model-loop messages, instructions, provider options, or
+platform-owned Run/message IDs. Each main Agent's exact `AGENTS.md` text is
+compiled into the Worker and is never accepted from the run request.
+
+`composeFetch()` delegates unclaimed requests to the optional application
+Worker. Worker Runtime remains route-agnostic.
+
+Every main Agent declares one concrete public GEA model ID or the SDK-owned
+`auto` selector above. GEA resolves the concrete snapshot model through the
+active Model Gateway catalog; source and artifacts contain no provider
+credential or target configuration.
+
+## Context strategies
+
+Agents use the existing tool-output offload and rolling summary by default.
+Configure that recipe with `defaultContext`, replace it with a custom strategy,
+or set `context: false` to disable automatic summaries, file writes and tool-result
+replacement. Disabling compression preserves already committed summaries and
+continues normal message persistence.
+
+```ts
+import { defineAgent } from "@gea-ai/agent-sdk";
+import { defaultContext } from "@gea-ai/agent-sdk/context";
+
+export default defineAgent({
+  name: "assistant",
+  slug: "assistant",
+  model: "gea-model-1",
+  context: defaultContext({
+    toolOutput: { offloadAtCharacters: 4_000, replaceAtCharacters: 8_000 },
+    preserveRecentGroups: 5,
+    summarization: {
+      triggerAtTotalTokens: 64_000,
+      // Optional: model, instructions, maxOutputTokens.
+    },
+  }),
+});
+```
+
+`toolOutput: false` and `summarization: false` independently disable the two
+parts of the default recipe. Thresholds use model-visible characters and the
+last provider-reported `usage.totalTokens`; the SDK does not estimate tokens.
+Recent groups keep tool calls and their results together. Without Computer
+storage, the default recipe skips offload but can still summarize.
+
+A custom strategy is an object with optional `prepareStep`, `onStepEnd` and
+`onEnd` callbacks, using the AI SDK 7 names. These callbacks replace the default
+recipe. `prepareStep` receives durable `messages`, `contextSize`, `stepNumber`
+and `runtimeContext`; returning `{ messages }` replaces the active projection
+for subsequent steps and Runs. Returning nothing keeps it. `onStepEnd` also
+receives that step's `usage` and `finishReason`; `onEnd` receives the main loop's
+`totalUsage` and `finishReason`.
+
+```ts
+const context = {
+  async prepareStep({ messages, runtimeContext }) {
+    const memory = await loadCommittedMemory(runtimeContext);
+    return { messages: applyMemoryToCoveredPrefix(messages, memory) };
+  },
+  async onStepEnd({ messages, runtimeContext }) {
+    runtimeContext.waitUntil(precomputeMemory(messages, runtimeContext));
+  },
+};
+```
+
+The functions in this short sketch are application-owned.
+
+`runtimeContext` provides trusted `identity`, `auth`, declared `env`, execution
+`environment`, typed `durableObjects`, `signal`, and the main public `modelId`.
+Call `model(modelId?)` to resolve a model through the existing Host, then use AI
+SDK `generateText` or `streamText` with that model and the cancellation signal.
+Register each auxiliary call's `{ model, usage, label?, status? }` through
+`recordUsage`. Status defaults to `completed`; use `failed` or `aborted` with
+`usage: null` when the provider did not return usage. Register a successful call
+before validating its text or committing memory, since those operations can fail
+after the model has consumed tokens. The SDK assigns the call id and tracks its
+Session write automatically.
+`writeToolOutput` is a writer returning `{ artifactUri }`, or `null` if storage
+is unavailable. Its input is `{ content, sha256, toolCallId, toolName }`.
+
+`runtimeContext.updateMessages(messages)` persists a replacement from an awaited
+foreground callback, including the final step or `onEnd`. Background work stores
+candidate memory in a DO; a later foreground callback applies it. The Worker
+waits for registered work before publishing its final success and usage, including
+when Computer is disabled. `metadata.modelCalls` records each main-model step and
+auxiliary call with a stable call id, Run id, model, source, optional label, status,
+completion time and usage. `metadata.totalUsage` is their known usage sum;
+`metadata.contextUsage` retains the auxiliary view. Hosted settlement prices each
+call using its own catalog target and writes a separate idempotent usage event.
+A completed model call stays completed even if the containing Run later fails.
+Unhandled callback or background errors fail the Run; completed model messages
+and registered usage survive that failure. Pass `signal` into external work so cancellation can finish promptly.
+
+AgentSession owns the active projection and separate transcript. Custom
+observations, reflection and coverage state belong in the application's chat DO.
+Commit memory and coverage together before removing the covered message prefix.
+Existing summary metadata is included when a custom callback reads messages, and
+is no longer separately injected after that callback replaces the projection.
+`stepNumber` is local to a Run, not a durable chat cursor.
+
+Context callbacks execute in the Agent bundle; snapshots contain only serializable
+descriptors and default recipe options. Ordinary imported modules are sufficient.
+Upgrade the SDK and rebuild/publish existing Agents to use the API. `waitUntil`
+covers the current invocation; it does not schedule future Runs or replay a model
+call after a crash.
+
+## CLI Workflow
+
+Local validation, development, and packing need no hosted Agent record:
+
+```bash
+gea agent validate --json '{"cwd":"."}'
+gea agent dev --json '{"cwd":"."}'
+gea agent eval --json '{"cwd":".","judgeModel":"gea-model-1"}'
+gea agent pack --json '{"cwd":"."}'
+```
+
+`gea agent dev` treats every unqualified model ID, plus explicit
+`creative-reasoning/<model>` IDs, as first-party Creative Reasoning models. It
+calls Creative Reasoning directly when `CREATIVE_REASONING_API_KEY` is present;
+when the key is absent it falls back to the hosted web model proxy and the
+current `gea login` Workspace. An explicit `{"modelSource":"hosted"}` keeps
+hosted routing. `{"modelSource":"local"}` forces local routing and therefore
+requires the Creative Reasoning key for first-party models; other qualified
+local providers continue to use their configured local catalog.
+`gea agent eval` applies the same decision to both Agent models and the active
+`judgeModel`, so a direct evaluation catalog contains every model the run uses.
+
+Native Anthropic calls, including `crr-a-*` and `creative-reasoning-1.5`, apply
+the SDK's shared rolling prompt-cache policy before provider serialization.
+System prompts, conversation prefixes, and eligible Tool definitions retain
+cache markers across model steps and turns. Markers belong only to outbound
+requests and never enter the stored AgentSession context. Hosted calls retain
+their existing proxy-owned cache policy.
+
+`gea agent eval` discovers Cases and inherited Judges from the Benchmark next
+to each main Agent's `tools/`: root `benchmarks/` for the root Agent, including
+after additional main Agents are added, and `agents/<slug>/benchmarks/` for
+directory Agents. It runs each Case through that main Agent's stable slug route
+and writes results under `.gea/evals`. Use `{"agentKey":"support"}` to select
+one main Agent. A Case's optional
+`expected` value enables the built-in Autoeval Judge. Author semantic rubrics
+as `*.judge.md`; author deterministic trajectory checks as `*.judge.ts` with
+the `./evals` SDK export. Autoeval may query bounded run evidence across
+multiple model steps and finishes by calling a structured result Tool; it does
+not require the model's text response to be JSON:
+
+```ts
+import { defineJudge } from "@gea-ai/agent-sdk/evals";
+
+export default defineJudge(({ messages }) => {
+  const usedSearch = messages.some((message) =>
+    message.parts.some((part) => part.type === "tool-search"),
+  );
+  return {
+    reason: usedSearch ? "Search was used." : "Search was not used.",
+    score: usedSearch ? 1 : 0,
+  };
+});
+```
+
+`gea agent dev` and `gea agent eval` generate `.gea/bindings.d.ts` from the
+owning main Agent's `tools/` and snapshot-known runtime Tool names. This
+registers the canonical root SDK types:
+
+```ts
+import agent from "./agent";
+import type {
+  AgentMessage,
+  AgentMessageFor,
+  InferAgentMessage,
+} from "@gea-ai/agent-sdk";
+
+type DefaultMessage = AgentMessage;
+type SupportMessage = AgentMessageFor<"support">;
+type ThisAgentMessage = InferAgentMessage<typeof agent>;
+```
+
+All three are ordinary AI SDK `UIMessage` types. Static custom `tool-*` parts
+preserve Tool names, Zod input types, and return types. Snapshot-known Computer
+and Connector Tools preserve their concrete `tool-*` names with generic input
+and output. MCP Tool parts use the qualified template
+`tool-<alias>__${string}` because their catalog is runtime-discovered; truly
+unqualified runtime Tools remain `dynamic-tool` parts. SDK-first Agent Workers
+currently emit no custom `data-*` parts, so Legacy chat data parts are not
+included. Code Judges consume the same types rather than defining an
+Eval-specific message model.
+`InferAgentMessage<typeof agent>` resolves to `never` when the generated
+registry is absent or its Agent slug does not match, rather than silently
+falling back to an unrelated Tool catalog.
+
+Studio also runs `defineApiConnector`, `defineMcpConnector`, and deployment-enabled
+built-in `geaConnect` providers through the managed Host. All use existing
+Project/Agent Connections, isolated by Preview/Production and application
+principal. No database migration or personal credential inheritance is involved.
+API keys default to `connection: { principalType: "agent" }`; OAuth and
+`geaConnect` default to `"user"`. All three helpers accept an explicit
+`connection: { principalType: "agent" | "user" }`. No-auth API/MCP endpoints
+need no Connection. Custom executable `defineConnector` ownership stays unchanged.
+
+Configure Agent-owned credentials in Project Connections or an Agent override.
+User-owned authorization links bind the application's supplied principal; missing
+user identity returns `principal_required`. OAuth client variables come from the
+selected environment. Register `${APP_BASE_URL}/api/agent-connectors/oauth/callback`
+for hosted OAuth, including the deployment Google OAuth client used by Google Drive.
+API keys are submitted on a public, state-bound setup page; OAuth uses PKCE;
+Feishu uses the host's isolated managed CLI. Credentials and refresh state remain
+encrypted in the original Connection scope and never enter Worker code.
+
+Rebuild old `geaConnect` snapshots to declare Studio ownership. Supported native
+providers are Google Drive, Feishu, Social Search, and WeChat Official Account,
+subject to deployment availability. Other platform resource references should
+use `defineApiConnector` or `defineMcpConnector` with an explicit endpoint.
+CLI upload preparation rejects old personal-authorization declarations and GEA
+user identity injection with the Connector alias, key, runtime, and reason.
+The server additionally checks native provider availability before publication.
+
+Configure a package-local API or MCP Connector without uploading its
+credential:
+
+```bash
+gea agent connect exa-market-intelligence
+```
+
+An MCP Connector declares only its stable server and authentication boundary:
+
+```ts
+import { defineMcpConnector, noAuth } from "@gea-ai/agent-sdk";
+
+export default defineMcpConnector({
+  auth: noAuth(),
+  key: "product-docs",
+  name: "Product Docs",
+  serverUrl: "https://mcp.example.com/mcp",
+}).require();
+```
+
+Its current Tools and schemas are discovered at the start of every run and
+exposed as `product-docs__<tool>`. They are not persisted in the Agent Package.
+
+API-key input is hidden. OAuth uses Authorization Code plus S256 PKCE through
+`http://127.0.0.1:8788/oauth/callback`. Credentials stay under `~/.gea`,
+scoped to canonical project path and Connector definition, and are reread for
+each local Tool call.
+
+Platform Connectors declared with `geaConnect(...)` are called through the
+Workspace selected by `gea login` and `gea workspace use`; their platform-owned
+credentials are never copied into the local project. This same local Connector
+Host behavior is used by both `gea agent dev` and `gea agent eval`.
+
+After `gea workspace use`, publish the complete Worker application:
+
+```bash
+gea agent push --json '{"cwd":".","slug":"product-worker"}'
+```
+
+The command uploads one generic Worker deployment and registers every main
+Agent in Studio by Worker plus Agent key. The new deployment becomes Preview.
+It never creates or updates Legacy `app_resource` or resource-package rows.
+Preview and Production promotion are Worker-wide.
+
+Use a Studio Agent ID to start its selected environment:
+
 ```bash
 npm install @gea-ai/agent-sdk
 ```
@@ -29,6 +548,56 @@ The default AI SDK engine resolves Anthropic capabilities from the upstream mode
 
 Native Workers request the catalog target from the AI binding, so public aliases can use the same recognition. This requires updating Worker Runtime and rebuilding the Agent with the new SDK. Existing SDK bundles retain their descriptor format. The hosted AI SDK proxy resolves target identity on the server; the optional `agentCore` engine keeps its existing protocol.
 
+## Provider reasoning options
+
+`defineAgent` accepts AI SDK-shaped `providerOptions`. This release exposes the
+reasoning controls of the `openai` and `anthropic` protocols:
+
+```ts
+export default defineAgent({
+  name: "Research assistant",
+  slug: "research",
+  model: "creative-reasoning-1.5",
+  providerOptions: {
+    anthropic: {
+      effort: "low",
+      thinking: { type: "adaptive" },
+    },
+  },
+});
+```
+
+For an OpenAI-compatible model, use
+`providerOptions: { openai: { reasoningEffort: "low" } }`. The SDK maps this
+public namespace to the existing OpenAI-compatible adapter; no gateway-specific
+namespace, upstream URL or credential is needed. Both namespaces may be declared;
+only the selected model's protocol consumes its options.
+
+- `openai.reasoningEffort`: `none`, `minimal`, `low`, `medium`, `high`, or `xhigh`.
+- `anthropic.effort`: `low`, `medium`, `high`, `xhigh`, or `max`.
+- `anthropic.thinking`: `{ type: "adaptive", display?: "omitted" | "summarized" }`,
+  `{ type: "enabled", budgetTokens: 2048 }`, or `{ type: "disabled" }`.
+  Enabled thinking requires an explicit integer budget of at least 1,024 tokens.
+
+Supported values depend on the actual model. The provider validates model-specific
+support; GEA does not map effort levels to token budgets. Unknown namespaces,
+unknown fields and invalid shapes fail at declaration/publication. Omit the
+options to retain existing defaults. The public `AgentModelProviderOptions` type
+is exported by the SDK and contract package.
+
+These settings are frozen in each Agent's published snapshot and apply to its
+main loop in both the default AI SDK engine and `agentCore`, including model
+switches and continuation. Private/referenced Agents keep their own settings;
+self copies use the source definition. Explicit Core per-step generation settings
+override the baseline for that step. Context strategies' auxiliary model calls
+continue to own their call options.
+
+Adoption requires an updated SDK, a server/CLI using the updated snapshot contract,
+and rebuilding and publishing the immutable Agent bundle. This adds no per-request
+override to the public `/run` API or Studio composer. See the upstream
+[OpenAI](https://ai-sdk.dev/providers/ai-sdk-providers/openai) and
+[Anthropic](https://ai-sdk.dev/providers/ai-sdk-providers/anthropic) options.
+
 ## Background Agent tasks
 
 Declare private definitions in `subagents/<name>/agent.ts` with their own `AGENTS.md`, tools, skills and connectors. They run in independent Sessions and may declare further subagents. Only top-level definitions become public Worker entrypoints.
@@ -47,6 +616,55 @@ const sales = defineAgentReference({
 const legal = defineRemoteAgent({
   slug: "legal-advisor",
   description: "Legal review",
+
+```
+
+## Call a Studio Agent with AI SDK
+
+Use `StudioAgentChatTransport` from `@gea-ai/agent-sdk/studio-client` with
+`useChat` from `@ai-sdk/react` in the browser, and `StudioAgentClient` from
+`@gea-ai/agent-sdk/studio-server` on your backend. The browser authenticates to
+your application; only your backend sends the Project key to GEA. The transport
+reads response identity headers and reuses the server Chat on later turns.
+
+```tsx
+import { useChat } from "@ai-sdk/react";
+import { StudioAgentChatTransport } from "@gea-ai/agent-sdk/studio-client";
+import { useState } from "react";
+
+// Inside your component:
+const [transport] = useState(
+  () =>
+    new StudioAgentChatTransport({
+      api: "/api/agent", // Your authenticated application path, without /run.
+      headers: { "x-csrf-token": csrfToken }, // From your application session.
+      onRun: ({ chatId, runId, requestId }) => {
+        console.log({ chatId, runId, requestId });
+      },
+    }),
+);
+const { messages, sendMessage, resumeStream } = useChat({ transport });
+```
+
+The transport sends your application's session cookies by default. It accepts
+only same-origin paths and sends no business metadata. Set `headers` to your
+application's CSRF token or user access token as appropriate.
+
+Create a key in **Project → API Key** and copy the matching URL from the
+Agent detail overview. Production uses `worker--<workerId>.<apex>`; preview
+uses `preview--worker--<workerId>.<apex>`. Both use `/gea/agents/<agentKey>/run`.
+Remove the trailing `/run` for the SDK `api` option, which appends operation
+paths itself. The key must match the URL environment.
+
+On the backend, configure the GEA destination and key from server environment:
+
+```ts
+import { StudioAgentClient } from "@gea-ai/agent-sdk/studio-server";
+import { env } from "./env";
+
+const agent = new StudioAgentClient({
+  api: env.GEA_AGENT_API_URL, // Agent base URL without /run.
+  token: env.GEA_PROJECT_API_KEY,
 });
 // URL: a GEA Agent protocol endpoint. The key stays in runtime environment configuration.
 const external = defineRemoteAgent({
@@ -63,3 +681,10 @@ The tool returns `{ status: "working", taskId, agentId }`. `task_update({ messag
 URL targets implement GEA task create/status/cancel endpoints. New calls and continuations follow the deployment selected by the URL, retaining history while using its current model, instructions and tools. Accepted tasks finish on their selected version. URL credentials are explicitly configured; source credentials and principals are not forwarded. Pure local development uses URLs for cross-Worker calls because it has no hosted Project identity.
 
 This requires matching SDK, CLI, server and Worker Runtime support and rebuilding immutable bundles. Task Sessions opt into `durable-object-worker-namespace-v1`; existing ordinary Session storage is unchanged. Channel wakeups, approval relay, active-child steering and execution recovery after a host crash remain deferred.
+
+### Worker build plugins
+
+The Node-only `@gea-ai/agent-sdk/worker-build-plugins` entry exports the shared
+esbuild plugins used by CLI Worker bundles and the hosted Judge runtime template.
+Build tools that use this entry must install the optional `esbuild` peer. Agent
+runtime code should use the ordinary SDK or `evals` entry instead.

package/dist/agent-call.d.ts

@@ -607,7 +607,6 @@ export declare function createWorkerTaskTool(input: {
     }, NoInfer<import("@ai-sdk/provider-utils").Context>>;
 });
 export declare function readWorkerAgentResponse(response: Response): Promise<{
-    status: "completed";
+    status: "completed" | "suspended";
     text: string;
 }>;
-//# sourceMappingURL=agent-call.d.ts.map