@gea-ai/agent-sdk 0.1.260920-alpha.2 → 0.1.260920-alpha.3

package/README.md

@@ -2,946 +2,8 @@
 
 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.
-
-## Tool outputs
-
-`defineTool` accepts `outputSchema` (Zod) and synchronous or asynchronous
-`toModelOutput({ toolCallId, input, output })`, following AI SDK's separation
-between the result used by the application and the result shown to the model.
-Both server and client tools retain output types in `InferAgentUITools`.
-Both the default Agent Core engine and `aiSdk()` support client Tools without
-`execute`. A client Tool waits for an `output-available` or `output-error` part
-on the original assistant message and Tool call ID. Submit all pending client
-results/approval decisions together through the existing continuation flow.
-Core pauses server handlers in the same batch until those interactions complete,
-following its existing whole-batch approval behavior.
-Tool results resume the same Run while its interaction remains pending.
-Waiting for client input releases execution: a new user message skips the old
-interaction and starts a new Run in the same Session, without an explicit cancel.
-Skipped calls become errors in the transcript/model context; late results are rejected.
-
-`outputSchema` is a declaration/type hint. It never parses, coerces or validates
-returned data, including client-supplied results. It is serialized in the Agent
-snapshot and sent as each function's `output_schema` for OpenAI Responses.
-Completions and Anthropic do not receive that field. This does not configure the
-Agent's final structured response. When a converter changes a JSON wire output,
-the author must keep the Responses output schema appropriate for that output.
-
-For multimodal results, enable the Agent's `artifacts` capability. Both implicit
-and explicit persistence use the same request-time Artifact resolution:
-
-- Implicit: return typed `file` parts from `toModelOutput` containing a URL,
-  base64 string or bytes. The SDK uploads them and persists Artifact IDs.
-- Explicit: save the file through `ctx.artifacts`, then return an existing ID
-  from `execute` and reference it in `toModelOutput`; no second upload occurs.
-
-For example, the implicit converter can map an ordinary business result:
-
-```ts
-toModelOutput: ({ output }) => ({
-  type: "content",
-  value: [
-    {
-      type: "file",
-      mediaType: "image/png",
-      filename: "plot.png",
-      data: { type: "url", url: new URL(output.url) },
-      // Or: data: { type: "data", data: output.base64 }
-    },
-  ],
-});
-```
-
-The explicit converter can reference a scoped Artifact:
-
-```ts
-const viewPlot = defineTool({
-  name: "viewPlot",
-  description: "Show a saved plot to the model.",
-  input: z.object({ artifactId: z.string().uuid() }),
-  outputSchema: z.object({ artifactId: z.string().uuid() }),
-  execute: async ({ artifactId }, ctx) => {
-    const { artifact } = await ctx.artifacts!.get({ id: artifactId });
-    return { artifactId: artifact.id };
-  },
-  toModelOutput: ({ output }) => ({
-    type: "content",
-    value: [{ type: "artifact", artifactId: output.artifactId }],
-  }),
-});
-```
-
-`AgentToolModelOutput` supports AI SDK text/JSON/error outputs and content with
-text, modern tagged `file` parts, or `{ type: "artifact", artifactId }` parts.
-Inline or URL file parts are uploaded through the existing Artifact upload
-capability; provider-specific file IDs must first be saved as GEA Artifacts.
-Model context retains immutable IDs and descriptive metadata. Authorized
-download URLs are resolved only when preparing a model request. Replaying saved
-tool results reuses their conversion instead of uploading the same media again.
-Tool calls already removed by context compaction are not reconstructed from UI
-history during approval or client-tool continuation. Large-result offloading
-replaces only text; the model-facing file references remain attached.
-Keep the original `execute` result JSON-serializable; the converter does not
-replace the UI result with its model-facing content.
-Model-facing `error-text` and `error-json` remain errors in both engines without
-changing the original successful UI result into an execution failure.
-
-Media placement is a model capability, not a protocol inference. Configure
-`targets["provider/model"].supportsMultimodalToolOutput` in Catalog v2: `true`
-keeps supported media inside tool results; `false` or omitted keeps text/Artifact
-IDs in the tool result and adds media in a user message after all results from
-that tool-call batch. This applies independently of API format. The chosen
-model must still support the supplied image/file media type in user messages;
-fallback cannot add vision to a text-only model. The Completions native adapter
-currently supports image blocks. Both the default
-Agent Core engine and `aiSdk()` use these rules. Rebuild the Agent bundle to
-adopt the new runtime behavior.
-
-## Calling the Agents HTTP API
-
-Call the public `/api/v1` API with ordinary HTTP and a fixed Agent ID. No Agent
-SDK dependency is required for API callers:
-
-```ts
-const baseUrl = "https://<tenant-host>/api/v1";
-const headers = {
-  authorization: `Bearer ${projectApiKey}`, // Or a user OAuth token.
-  "content-type": "application/json",
-};
-const created = await fetch(`${baseUrl}/sessions`, {
-  method: "POST",
-  headers,
-  credentials: "omit",
-  redirect: "error",
-  body: JSON.stringify({ agent_id: agentId, environment: "production" }),
-});
-if (!created.ok) throw new Error(`Session creation failed: ${created.status}`);
-const session = await created.json();
-const response = await fetch(`${baseUrl}/sessions/${session.id}/runs`, {
-  method: "POST",
-  headers,
-  credentials: "omit",
-  redirect: "error",
-  body: JSON.stringify({ input: "Hello", stream: true }),
-});
-if (!response.ok) throw new Error(`Run admission failed: ${response.status}`);
-// Consume response.body as the API's SSE stream.
-```
-
-Project Key access to deployed project Agents does not require OAuth or store
-publication. OAuth access remains subject to user and tenant authorization.
-For local development, use the CLI's separate API listener, omit authorization
-and omit `environment` so the local API selects it. Shared HTTP schemas live in
-`@gea-ai/contract/agent-http-api`; routes are documented by `/api/v1/openapi.json`.
-
-Read `GET /sessions/{id}` for `active_run`, capture that Run ID, then observe
-`GET /runs/{id}` or its stream. A later Run in the same Session does not change
-the captured invocation. Cancellation acknowledgement is separate from final
-cleanup. Aborting an HTTP request does not cancel a Run; a lost POST response
-does not establish whether it was accepted, so do not automatically replay it.
-
-The authoring SDK owns Agent execution. An Agents API client SDK is deferred.
-The Worker `AGENTS.fetch` binding is an authenticated HTTP transport using the
-same paths, payloads and responses. It does not introduce `agents.*`, `sessions.*`
-or `runs.*` client methods. See the
-[HTTP integration guide](https://musegea.com/developers/agent-api).
-
-## Custom Agent execution URL
-
-```ts
-export default defineAgent({
-  name: "Support",
-  slug: "support",
-  model: "your-model",
-  http: { runPath: "/gea/support-entry" },
-});
-```
-
-`http.runPath` selects the Agent's actual Worker execution route. Omission uses
-`/gea/agents/<key>/run`. The route belongs to the immutable snapshot and manifest;
-changing it does not change the Agent ID. Hosts invoke the recorded version's
-route, including retained child Runs. OPTIONS reports the declared route without
-creating a Session. Build/upload validation probes it and rejects mismatches and
-conflicting declarations. Private Session control endpoints keep their standard
-protocol paths.
-
-Agents API dispatches **to** this Worker route. The existing public authentication
-adapter is still present; removing its control-plane round trip is unfinished.
-This increment does not change `http.auth` behavior or add an API client SDK.
-
-## Existing Worker URL authentication
-
-The following Worker URL adapter remains available while the unified Agents API
-migration proceeds. `StudioAgentClient` is still used by existing Worker handlers;
-it is not the fixed-ID `/api/v1` interface above.
-
-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.
-
-Use direct HTTP against platform `/api/v1/sessions` and
-`/api/v1/sessions/{sessionId}/runs`, with a Bearer Project API Key or OAuth user
-token and the canonical Agent ID. Project Keys retain Project service scope;
-OAuth tokens resolve the current user and tenant installation. Neither changes
-the Agent's default host-context execution policy. The older `studio-server`
-client targets the retired Worker credential entry and should not be used for
-new integrations.
-
-## 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>
-```
-
-Agent execution requires trusted host invocation context by default. Public
-Agents API accepts Project API Keys and OAuth user tokens, checks their scope,
-and admits the Session/Run before calling this Worker's configured execution URL.
-The Worker does not authenticate those credentials again.
-
-```ts
-import { defineAgent } from "@gea-ai/agent-sdk";
-
-export default defineAgent({
-  name: "support",
-  slug: "support",
-  model: "gea-model-1",
-  http: { runPath: "/gea/support-entry" },
-});
-```
-
-Omit `auth` for normal hosted execution. Set `http: { auth: false }` only when
-this Agent's Worker HTTP entry should also admit anonymous requests. The host
-still registers their Session/Run with project-scoped anonymous ownership.
-Request headers and bodies cannot supply a trusted principal or parent Run.
-This setting does not disable public Agents API Key/OAuth checks or expose
-private Session controls. Ordinary business routes keep their own authentication.
-
-`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
-
-Tool-output offload and context summarization are independent features. Offload is
-on by default, including with a custom or disabled context strategy. Configure it
-on `defineAgent`, or set `toolOutputOffload: false` to keep future outputs inline.
-Use `context: false` to disable automatic summaries and context callbacks; set
-both switches to false to disable both features. Already committed summaries and
-offload references remain readable.
-
-```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",
-  toolOutputOffload: {
-    offloadAtCharacters: 4_000,
-    replaceAtCharacters: 8_000,
-    preserveRecentGroups: 5,
-  },
-  sessionTools: true,
-  context: defaultContext({
-    preserveRecentGroups: 5,
-    summarization: { triggerAtTotalTokens: 64_000 },
-  }),
-});
-```
-
-Offload thresholds use model-visible characters. Results at the first threshold
-are stored; those at the replacement threshold are immediately stubbed. Smaller
-stored results remain inline in recent message groups; `preserveRecentGroups: 0`
-replaces them immediately. The default summary strategy also releases recent-group
-protection under its token-pressure threshold. Summary thresholds use the last
-provider-reported `usage.totalTokens`, without token estimation.
-
-All newly offloaded results live in the AgentSession, independent of Computer.
-The SDK automatically supplies `readToolOutput` with a SHA-256 id and bounded
-character ranges. Its bounded output is not offloaded again. Offload happens
-before model-projection persistence, while the UI transcript retains full results.
-Existing file-backed references retain their original retrieval instructions.
-The reader remains available when a Session has stored offloads even if future
-offloading is disabled.
-
-The old `defaultContext({ toolOutput: ... })` option remains a deprecated fallback;
-an explicit `toolOutputOffload` setting takes precedence. Old snapshots without the
-new field retain their context-owned policy. Rebuilding an Agent with `context:
-false` now requires `toolOutputOffload: false` as well to disable both features.
-
-### Built-in model tools
-
-- `sessionTools: true` adds `sessionList`, `sessionRead`, and `sessionSend`.
-  It defaults to false. The old `chatList()` / `chatRead()` / `chatSend()` selections
-  remain deprecated compatibility inputs; an explicit `sessionTools` setting
-  replaces them. All three tools use Agents API in hosted and local execution:
-  `sessionList({agentId?, cursor?, limit?})` lists accessible Sessions;
-  `sessionRead({sessionId, cursor?, limit?})` reads saved messages;
-  `sessionSend({sessionId, message, mode?})` sends inbox input (default `follow_up`).
-  List/read return `{items, next_cursor}`; send returns `{id, session_id, duplicate}`,
-  acknowledging delivery rather than Run completion. A Session needs a prior Run
-  before messaging. Identity and environment come from the current Run; Key service
-  principals do not need a workspace user and OAuth retains tenant/user isolation.
-- Declaring private or referenced subagents adds `agent`, `runWait`, and
-  `runCancel` when the host admits those targets. The existing `agentTool()`
-  selection enables root self copies. Ordinary Agents do not gain Run tools just
-  because they run in an inbox. Implicit joins and descendant cleanup remain
-  runtime behavior and do not depend on model tool visibility.
-- Offload adds `readToolOutput` automatically; do not declare it in `tools/`.
-
-`gea agent validate` reports `builtinTools`, including each tool's source feature.
-Generated message types include these tools. Reserved generated names are checked
-during packaging. This inventory describes configured tools; host authorization
-and dynamic Connector discovery are still resolved at runtime. Internal managed
-operation IDs remain compatible with the existing host protocol; the model-facing
-names above are camelCase.
-
-A custom strategy is an object with optional `prepareStep`, `onStepEnd` and
-`onEnd` callbacks, using the AI SDK 7 names. These callbacks replace the summary strategy, independently of offload. `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`.
-Use `runtimeContext.ai.generateText()` or `runtimeContext.ai.streamText()` for
-auxiliary calls. They inherit the main model and cancellation signal, attach the
-current trace, and record the call's usage automatically before application text
-validation or memory writes. Do not also call `recordUsage` for these calls.
-
-For compatibility, `model(modelId?)` still resolves an AI SDK model. Calls made
-through that model continue to require explicit `recordUsage({ model, usage,
-label?, status? })`; unknown usage is `null`. 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
 ```
 
 [Developer documentation](https://musegea.com/developers/agent-development)
-
-## Model identity and output limits
-
-Set an optional per-model-call output budget on the Agent definition:
-
-```ts
-import { defineAgent } from "@gea-ai/agent-sdk";
-
-export default defineAgent({
-  name: "Research assistant",
-  slug: "research",
-  model: "creative-reasoning-1.5",
-  maxOutputTokens: 32_000,
-});
-```
-
-The default engine is Rust Agent Core. Select either engine explicitly when needed:
-
-```ts
-import { defineAgent, aiSdk } from "@gea-ai/agent-sdk";
-import { agentCore } from "@gea-ai/agent-sdk/agent-core";
-
-// Omit engine for Core defaults, or configure it explicitly.
-const agent = defineAgent({
-  name: "Assistant",
-  slug: "assistant",
-  model: "auto",
-  modelRequirements: { agentic: 1 },
-  engine: agentCore({ maxToolConcurrency: 4 }),
-});
-// Use engine: aiSdk() to retain the AI SDK execution contract.
-// The string forms "agent-core" and "ai-sdk" are also accepted.
-```
-
-Existing deployed bundles keep their engine. Adopting this default requires an SDK
-upgrade and rebuild. New CLI builds declare `ai-generation-v1`; update Worker
-Runtime before deploying them. Core remains the supported GEA executor subset,
-not the complete AI SDK callback/provider-tool API. No runtime engine fallback
-occurs after a model request or tool effect.
-
-Context strategies can call `runtimeContext.ai.generateText()` or
-`runtimeContext.ai.streamText()` with a Catalog model ID (omission uses the Agent
-model), AI SDK-shaped messages, instructions, output budget and an optional label.
-These methods accept the same `model: "auto"` + `modelRequirements`,
-`maxOutputTokens`, and `providerOptions` settings as `defineAgent`. Auto uses the
-same selection policy; the selected model must exist in the deployment Catalog.
-Only the model is inherited from the Agent. Auxiliary output budgets and provider
-options use explicit call settings or Catalog defaults.
-These methods inherit cancellation and trace context and automatically record
-auxiliary usage. Do not additionally call `recordUsage()` for the same call.
-`runtimeContext.model()` and manual accounting remain available for existing
-strategies. Ordinary Workers have the independent `env.AI` generation binding.
-
-`maxOutputTokens` must be a positive integer. It applies to each model call in the AI SDK engine and `agentCore`, subject to the provider's supported limits; it is not a total task budget. An Agent value overrides `LLM_MODEL_CATALOG_JSON.targets[provider/model].maxOutputTokens`, which in turn overrides the provider adapter's default. Each private or referenced Agent uses its own definition, while self copies use the source definition. Agent Core's explicit per-step `generation.max_output_tokens` may override the Agent or catalog baseline for that step.
-
-The explicit AI SDK engine resolves Anthropic capabilities from the upstream model identity. Gateway requests retain the configured routing ID; public model IDs and usage attribution are unchanged. Deployments should set the target's `maxOutputTokens` for gateway aliases whose provider identity is intentionally hidden, so their output budget does not depend on an adapter's unknown-model fallback. Explicit Agent and AI SDK call limits still apply.
-
-Native Workers request the catalog target and output-limit capability from the AI binding. This requires updating Worker Runtime and rebuilding the Agent with the new SDK. Existing SDK bundles retain their descriptor format because both fields are opt-in. The hosted AI SDK proxy resolves the same defaults on the server; the `agentCore` engine receives them through its existing model descriptor.
-
-## 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 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.
-
-## Agent delegation through Sessions and Runs
-
-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.
-
-References are explicit default exports from `subagents/<alias>.ts`:
-
-```ts
-import { defineAgentReference, defineRemoteAgent } from "@gea-ai/agent-sdk";
-
-// Same Worker, checked against the generated WorkerAgentRegistry.
-const sales = defineAgentReference({
-  slug: "sales",
-  description: "Sales analysis",
-});
-
-// Same Agents API: the host revalidates the calling Run's authority.
-const legal = defineRemoteAgent({
-  agentId: "bb141b12-6f63-43bd-8ab6-77930916d3ef",
-  description: "Legal review",
-});
-
-// Another service: use its API root and canonical Agent ID.
-const external = defineRemoteAgent({
-  agentId: "34910649-2df7-4978-8794-8d8fb72f16cd",
-  url: "https://legal.example.com/api/v1",
-  environment: "production",
-  description: "External legal review",
-  auth: { bearerTokenEnv: "LEGAL_AGENT_KEY" },
-});
-```
-
-Each reference file default-exports one reference. All targets use `agent({ target: "alias", message, sessionId? })` and return `{ status: "working", runId, sessionId }`. Callers only see their own declared aliases. Include `agentTool()` in the root's tools to allow self copies by omitting `target`; children cannot create unnamed copies.
-
-Use `runWait({ runIds, timeoutMs? })` to wait for specific Runs and `runCancel({ runId })` to request cancellation. The SDK owns waiting, batched parent wakeups and descendant cleanup. Cancellation acceptance is not completion. A logical Run keeps its ID through normal waits and resumptions; continuing an idle child with the same target and `sessionId` creates a new Run. There is no Task resource or progress-reporting tool.
-
-Remote references always use the canonical Agent ID, optionally with another service's API root. Their Session and Run IDs come from that API. Remote transport creates Sessions/Runs and reads status, messages and cancellation through ordinary HTTP; it never calls a Worker's `/gea/xxxx` execution URL directly. The API selects the versioned Worker route. A remote reference without `environment` inherits the invocation environment (`local` in CLI development).
-
-Same-service calls inherit live Project Key or OAuth authority through a short-lived, host-only signed context. Studio host calls use a Project service scope isolated by Worker, environment and principal. Explicit credentials override inherited authority. Calls to another API origin use only explicitly configured credentials; they never forward the parent's bearer. Knowing an Agent ID does not grant access. Same-service parent links are registered by the host; cross-service relationships live in the parent Session and point to the actual remote IDs.
-
-Remote observation survives parent waiting using the existing Session pending-dispatch mechanism. A transport error does not invent a terminal outcome, and accepted Run creation is never automatically replayed. Host shutdown stops observation without cancelling remote execution. General crash recovery and approval continuation remain separate lifecycle work.
-
-Upgrade SDK, CLI, server and Worker Runtime together and rebuild immutable bundles. The physical `AGENT_TASK_SESSIONS` namespace remains to preserve existing child Session history; it no longer represents Tasks.
-
-## Fetch-style Agents binding
-
-Generated Agent Workers include an `AGENTS` binding. Other Workers can declare `{ name: "AGENTS", type: "agents" }` in their bindings. It exposes the same HTTP paths and payloads, without a separate API client SDK:
-
-```ts
-const response = await env.AGENTS.fetch("/api/v1/agents?limit=20");
-const agents = await response.json();
-```
-
-Within a trusted Agent invocation, the host supplies signed invocation authority. An ordinary hosted Worker invocation without a source Run must provide its Project API Key or OAuth token in `Authorization`. Local development uses the local API's existing authority. The binding does not expose host signing secrets or permit arbitrary destinations. Default host authority covers Agents, Sessions and Runs; File, Connector and Computer operations require explicit credentials with their existing grants.
-
-## 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,
-});
-```
-
-### 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.
-
-## Calling the Agents HTTP API
-
-Applications call `/api/v1` using `fetch`, `curl` or another HTTP client. Payloads
-use JSON and streams use AI SDK UI-message SSE. The Agent SDK owns Agent execution;
-calling the HTTP API does not require an SDK client.
-
-Hosted requests use a Project API Key or a Project user OAuth token. An independently running
-`gea agent dev --model-source local --api-port 8788` exposes token-free local access:
-
-```sh
-curl --fail-with-body http://127.0.0.1:8788/api/v1/agents
-
-curl --fail-with-body http://127.0.0.1:8788/api/v1/files \
-  -F "file=@notes.txt;type=text/plain"
-```
-
-Prepare `notes.txt` before uploading; no Agent or Session is needed.
-Send `{ type: "file", file_id: file.id }` in a Run input to use the
-uploaded or generated file: Artifact.id is the same File ID. `artifact_id` remains
-a compatibility alias. `/files` lists and manages both uploads and outputs. Exact IDs retain their content
-across later saves and restart. `listArtifacts` lists only the current Session's outputs;
-public `/artifacts` queries all Sessions for the application user.
-Connections are managed through `/agents/{id}/connections`; follow the returned
-`actions`, since environment credentials and externally supplied resolvers are
-read-only through the local API.
-
-See the [HTTP integration guide](https://musegea.com/developers/agent-api) and the
-running server's `/api/v1/openapi.json` for routes and payloads.
-
-API callers use ordinary HTTP. Subagents reuse Agent/Session/Run resources,
-with parent/child coordination owned by logical Runs in the SDK Session inbox.
-Internal Task logic has been removed. Worker fetch bindings and remote references
-use the same API, which invokes each Agent at its versioned custom or standard
-Worker route. See the [HTTP integration guide](https://musegea.com/developers/agent-api)
-for authentication and Session/Run operations.