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

package/README.md

@@ -1,1259 +1,9 @@
 # `@gea-ai/agent-sdk`
 
-`@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.
-
-## 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 require a Project API Key by default. This applies
-to the Agent routes, while ordinary routes in `worker.ts` remain public.
-
-```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;
-  },
-}
-```
-
-The callback returns an external user, a `Response`, or `null` (401). It may
-also return the result of `projectKeyAuth()` to explicitly compose key auth.
-There is no implicit fallback after a custom authenticator rejects. 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.
-
-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.
-
-The optional Rust/WASM engine uses the same context strategies and host tools:
-
-```ts
-import { agentCore } from "@gea-ai/agent-sdk/agent-core";
-
-export default defineAgent({
-  name: "assistant",
-  slug: "assistant",
-  model: "gea-model-1",
-  engine: agentCore({
-    maxToolConcurrency: 4,
-    maxSteps: 20,
-    maxRetries: 2,
-    timeout: {
-      totalMs: 120_000,
-      stepMs: 60_000,
-      chunkMs: 15_000,
-      toolMs: 30_000,
-    },
-    onError: ({ error }) => console.error(error.code, error.details),
-    guardrail: ({ call }) =>
-      call.name === "deleteAsset" ? "user-approval" : "not-applicable",
-  }),
-});
-```
-
-`gea agent` bundles Core's WASM bytes with the Agent. The factory is an authoring
-entry for that bundler; installed projects do not need Rust. The default engine
-remains AI SDK. Core supports local TS tools, pre-execution guardrail and approval,
-context strategies and the existing managed Session/Artifact lifecycle. An approval
-pause skips custom `onEnd` until continuation completes. Guardrail is checked again
-before dispatch and may deny or require approval; it cannot override a Tool denial.
-Core initiates preparation, step-end and run-end callbacks into TS, and waits for
-context settlement before returning its outcome. A failed final context commit
-cannot report success; cancellation still waits for cleanup.
-Declared Tools keep their typed `tool-<name>` UI parts and dynamic Tools keep
-`dynamic-tool`, so existing Tool renderers and code Judges can use either engine.
-Provider-hosted/custom and client-executed tools are outside the current Core subset.
-The Worker Runtime must support WebAssembly JSPI. This optional engine supports
-a subset of AI SDK model and output features.
-Rust owns error classification, model request retries and timeout decisions. The
-TS `onError` callback observes terminal failures once; recoverable Tool errors,
-retry attempts and caller cancellation do not invoke it. `maxRetries` defaults to
-2 and `timeout` also accepts a number for the total active execution budget.
-Established streams and Tools are never replayed automatically. `maxSteps` stops
-after a complete step. Cleanup remains awaited, so a timeout does not forcibly
-terminate uncooperative host code or reverse an effect.
-
-Dynamic step settings are supplied by TS callbacks and applied by Rust:
-
-```ts
-engine: agentCore({
-  models: ["gea-model-2"],
-  prepareStep: ({ stepNumber }) =>
-    stepNumber === 0
-      ? { activeTools: ["lookup"], toolChoice: { type: "tool", toolName: "lookup" } }
-      : { model: "gea-model-2", activeTools: [], generation: { max_output_tokens: 2048 } },
-  stopWhen: ({ steps }) =>
-    steps.reduce((sum, step) => sum + (step.usage?.totalTokens ?? 0), 0) >= 10_000,
-}),
-```
-
-Declare additional model IDs in `models` so the CLI can prepare their local routes.
-`stepNumber` is zero-based. `prepareStep` receives current messages, available tools
-and completed step summaries; it can also set `toolOrder`, `bodyOptions` or `stop`.
-Model/tool/generation overrides apply only to that step. `generation` uses Core's
-neutral snake_case keys; `bodyOptions` uses the selected protocol's raw option keys.
-Omitted/undefined values leave provider defaults intact. `stopWhen` runs after a
-completed tool step is committed; a final text response ends naturally. The
-example's token threshold is checked between steps and may be exceeded by the
-last completed call. Approval preserves selected tools/model and prior step
-usage, then evaluates the predicate after continuation without another model call.
-Both callbacks receive `signal`. Existing `context` strategies remain responsible
-for replacing the durable message projection.
-
-Final structured output accepts a convertible TS schema:
-
-```ts
-engine: agentCore({
-  output: z.object({ answer: z.number().int(), explanation: z.string() }),
-}),
-```
-
-Zod 4 and libraries implementing Standard JSON Schema v1 are supported. TS converts
-only the schema; Rust sends the protocol request, parses final JSON and validates
-it. Consume the successful result from `message.metadata.output`. Intermediate
-text is still a preview. Tool steps and approvals work normally, and output errors
-retain model-call usage. TS-only refinements/transforms and lossy conversions are
-unsupported; there is no partial-object stream or automatic repair.
-
-This engine does not yet provide the complete AI SDK Agent/`streamText` contract.
-The Worker engine uses built-in Rust HTTP/SSE protocols for the main model.
-The host supplies raw fetch, credentials and scoped effects. Default compression
-and custom context strategies remain TS hooks; `runtimeContext.model()` resolves
-an ordinary AI SDK model lazily, and strategies can call `streamText` directly.
-Their model features are independent of Core protocol coverage. The optional
-Core-backed AI SDK model facade is an outward adapter. Hosted development requires
-the matching raw proxy server for the main Core model.
-
-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:
+The TypeScript SDK for building GEA Agent applications.
 
 ```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":"."}'
+npm install @gea-ai/agent-sdk
 ```
 
-`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
-gea agent run --json '{"agentId":"<studio-agent-id>","prompt":"Inspect the project"}'
-```
-
-The server pins the exact Studio Agent version, Agent key, Worker ID, and Worker
-deployment to the Run. Recovery never follows a later environment target or
-falls back to Legacy.
-
-Custom Tools may omit `execute` to delegate execution to the calling application.
-These Tools are recorded as `execution: "client"` in the package snapshot and
-pause with an `input-available` Tool part. The application returns the result
-through AI SDK `addToolOutput`. Studio Tool approvals and client outputs use the
-existing `/run` endpoint with the server's assistant message ID.
-This capability requires updated SDK, Web/ORPC and Agent deployments.
-
-Package Tools may declare a static or input-dependent approval policy. A
-`user-approval` decision pauses before execution and can be resumed from any
-supported Chat client. For example:
-
-```ts
-import { defineTool } from "@gea-ai/agent-sdk";
-import { z } from "zod";
-
-export default defineTool({
-  approval: ({ amount }) => (amount > 100 ? "user-approval" : "not-applicable"),
-  description: "Transfer credits after any required user approval.",
-  execute: async ({ amount }) => ({ transferred: amount }),
-  input: z.object({ amount: z.number().positive() }),
-  name: "transfer_credits",
-});
-```
-
-```text
-coding-agent/
-  agent.ts
-  AGENTS.md
-  connectors/github.ts
-  hooks/before-turn.ts
-  durable-objects/agent-counter.ts
-  skills/project-conventions/SKILL.md
-  tools/agent.ts
-  tools/search-github.ts
-  tools/chat-list.ts
-  tools/chat-read.ts
-  tools/chat-send.ts
-  tools/computer.ts
-  tools/web-search.ts
-```
-
-```ts
-// agent.ts
-import { DurableObject } from "cloudflare:workers";
-import { defineAgent } from "@gea-ai/agent-sdk";
-import { AgentCounter } from "./durable-objects/agent-counter";
-
-export { AgentCounter };
-
-export default defineAgent({
-  computer: {
-    enabled: true,
-    filesystem: { durability: "durable", scope: "user" },
-  },
-  durableObjects: { COUNTER: AgentCounter },
-  model: "gea-model-1",
-  name: "coding-agent",
-  slug: "coding-agent",
-});
-```
-
-```ts
-// hooks/before-turn.ts
-import { defineHook } from "@gea-ai/agent-sdk";
-
-export default defineHook({
-  event: "beforeTurn",
-  run: ({ identity, now }) => ({
-    prepend: [
-      `Current time: ${now.toISOString()}`,
-      `Act only for workspace ${identity.workspace.id}.`,
-    ].join("\n"),
-  }),
-});
-```
-
-Durable Object implementations declared by `defineAgent()` must be named
-exports from `agent.ts` in a headless project, or from `worker.ts` when an
-explicit application Worker exists. Keep the same exported class name,
-binding, and object ID to retain state across releases. Install
-`@cloudflare/workers-types` for Cloudflare-compatible authoring types.
-
-Public methods on the class are native typed RPC methods. The generated
-`.gea/bindings.d.ts` connects the binding to the exported class, so separate
-Tool files get method, input, and result autocomplete without internal URLs or
-a second contract definition:
-
-```ts
-// durable-objects/agent-counter.ts
-import { DurableObject } from "cloudflare:workers";
-
-export class AgentCounter extends DurableObject {
-  async increment({ by }: { by: number }) {
-    const value = ((await this.ctx.storage.get<number>("value")) ?? 0) + by;
-    await this.ctx.storage.put("value", value);
-    return { value };
-  }
-}
-```
-
-```ts
-// tools/increment-counter.ts
-import { defineTool } from "@gea-ai/agent-sdk";
-import { z } from "zod";
-
-export default defineTool({
-  description: "Increment the workspace counter.",
-  execute: async ({ by }, context) => {
-    const counter = context.durableObjects.COUNTER.getByName(
-      `workspace:${context.identity.workspace.id}`,
-    );
-    return await counter.increment({ by });
-  },
-  input: z.object({ by: z.number().int() }),
-  name: "increment_counter",
-});
-```
-
-RPC arguments and results use structured clone. `fetch`, alarms, and WebSocket
-lifecycle handlers remain lifecycle methods rather than model-facing RPC.
-Browser code should still call an authenticated Worker API and must not receive
-a Durable Object namespace or choose an identity-derived object key.
-
-`AGENTS.md` is required and automatically becomes the only instruction
-entrypoint. Every discovered `tools/**/*.ts`, `connectors/**/*.ts`,
-`hooks/**/*.ts`, and direct `skills/*.ts` file must default-export its SDK
-definition. Local Skills are discovered from `skills/<name>/SKILL.md`. Tests,
-specs, and `_`-prefixed files are ignored.
-
-SDK-first Agents do not inherit legacy runtime reminders. Use the optional
-`beforeTurn` hook for dynamic hidden context derived from the current message,
-stable identity, declared environment, or current time. The runtime prepends
-the returned text to the active user message, stores that transformed message
-in AgentSession model context before calling the model, and reuses it for Tool
-steps, approval continuation, and same-Run recovery. It does not change the
-public Chat message. Keep stable instructions in `AGENTS.md` so prompt caching
-can reuse the system prefix.
-
-When the exact Package Version contains Skills, the runtime adds one stable
-`loadSkill` Tool, including when Computer is disabled. Call
-`loadSkill({ skill: "report" })` to read `SKILL.md`, or
-`loadSkill({ skill: "report", path: "references/format.md" })` to read another
-UTF-8 text file relative to that Skill's root. Absolute paths and traversal are
-rejected. Each read returns `{ skill, path, content }`, with a relative `path`,
-and is limited to 512 KiB. When the existing Computer initialization has prepared
-the mount, the result also includes `executionDirectory`, the selected Skill's
-read-only root in that Computer. Binary files are not a text-reading surface.
-
-Both entry instructions and supporting files come directly from the exact
-immutable Worker bundle; reading them never opens Computer. The Tool description
-lists all available Skill slugs and descriptions and explains the optional
-`executionDirectory`. The directory comes from the initialized session's actual
-roots; the description contains no physical path assumptions. Script execution
-uses the Agent's provided execution Tools. Skill loading does not grant execution,
-install interpreters, or add system instructions.
-
-The CLI uses the same SDK Tool builder as the Worker to emit
-`definition/skill-tools/<agentKey>.json` in each expanded dev artifact and Agent
-archive. Inspect `.gea/agent-dev/definition/skill-tools/<agentKey>.json` after
-`gea agent dev` to see the final `description` and `inputSchema`. The preview
-contains the complete static Skill catalog, not file contents or an additional
-runtime configuration. Use matching updated CLI and Agent SDK versions to build
-these artifacts; existing published Workers keep their bundled behavior.
-
-`createAgentSkillTool({ files, snapshot, mountedRoot? })` accepts only bundled
-files, the snapshot, and an optional already prepared mount root. It never creates
-a Computer or mounts files. Provider session initialization prepares Skills before
-the model runs and passes this root to the Tool builder. Legacy Computer
-configuration retains lazy mounting and omits `executionDirectory` when the Tool
-is constructed before mounting. Existing Computer capability validation still
-applies. `readFile` remains available for Computer filesystem access, while
-`loadSkill` is the portable Skill text reader.
-
-The generated Agent Worker constructs the complete model-facing Tool set inside
-V8 from the bundled package snapshot and Tool runtime. Web initializes only
-runtime capabilities, Connector state, and dynamic Connector input schemas;
-the run body contains no serialized AI SDK Tools. Privileged Connector,
-conversation, and search execution remains behind the private Tools binding.
-
-```ts
-// tools/web-search.ts
-import { webSearch } from "@gea-ai/agent-sdk";
-
-export default webSearch();
-```
-
-Conversation capabilities are selected the same way and remain independent:
-
-```ts
-// tools/chat-list.ts
-import { chatList } from "@gea-ai/agent-sdk";
-
-export default chatList();
-```
-
-Use `agentTool()` to let the model create an isolated child Agent conversation.
-The model-visible Tool is named `agent`; omitting its optional `agentSlug`
-starts the current Agent in a fresh context. The returned `chatId` is then
-handled by the ordinary Conversation Tools: `chatList()` discovers child
-conversations, `chatRead()` reads their bounded transcript, and `chatSend()`
-continues an idle conversation. There is no separate `subagent_*` Tool family.
-
-```ts
-// tools/agent.ts
-import { agentTool } from "@gea-ai/agent-sdk";
-
-export default agentTool();
-```
-
-Select `chatRead()` and `chatSend()` in their corresponding files only when the
-Agent should be able to inspect or continue conversations.
-
-One Tool module may group reusable selections without changing the serialized
-Agent Package contract:
-
-```ts
-// tools/research.ts
-import { chatRead, defineToolSet, webSearch } from "@gea-ai/agent-sdk";
-
-export default defineToolSet([chatRead(), webSearch()]);
-```
-
-Tool Sets may contain other Tool Sets. Their entries are flattened from left to
-right, and the CLI preserves that order after deterministic file discovery.
-
-Computer setup has two independent parts. First enable the runtime in
-`agent.ts`:
-
-```ts
-// agent.ts
-import { defineAgent } from "@gea-ai/agent-sdk";
-
-export default defineAgent({
-  computer: {
-    enabled: true,
-    filesystem: { durability: "durable", scope: "chat" },
-  },
-  model: "gea-model-1",
-  name: "research-agent",
-  slug: "research-agent",
-});
-```
-
-New Agent code can choose its Computer provider directly:
-
-```ts
-import {
-  defaultComputer,
-  localComputer,
-  remoteComputer,
-  secret,
-} from "@gea-ai/agent-sdk/computer";
-import { justbash } from "@gea-ai/agent-sdk/computer/just-bash";
-import { e2b } from "@gea-ai/computer-e2b";
-
-const computer = defaultComputer({
-  filesystem: {
-    scope: ({ principal }) => {
-      if (!principal) throw new Error("A business principal is required");
-      return `${principal.principalType}:${principal.principalId}`;
-    },
-    files: { "README.md": "Workspace initialized by this Agent." },
-  },
-  async onSession({ use, ctx }) {
-    const session = await use();
-    await session.writeTextFile({
-      path: `${session.roots.tmp}/principal.json`,
-      content: JSON.stringify(ctx.principal),
-    });
-  },
-});
-
-// Other choices for defineAgent({ computer: ... }):
-const virtual = justbash({ filesystem: { durability: "ephemeral" } });
-const external = e2b({
-  apiKey: secret("E2B_API_KEY"),
-  filesystem: { durability: "ephemeral" },
-});
-const remote = remoteComputer({
-  url: "https://computer.example.com",
-  token: secret("COMPUTER_TOKEN"),
-});
-const local = localComputer({
-  mode: "sandbox",
-  filesystem: { source: "local-project" },
-});
-```
-
-Each factory returns one Computer with a matching filesystem. The code selects
-the provider and any remote endpoint. The existing COMPUTER Native binding connects
-directly to E2B or the developer service; just-bash is bundled into the Worker.
-Provider secret references are resolved only for Native Runtime. Do not separately declare those keys in the Agent's
-`environment` unless the Agent itself intentionally needs them.
-
-Computer file I/O follows Eve / AI SDK: `readFile/writeFile` stream bytes,
-`readBinaryFile/writeBinaryFile` handle Uint8Array, and text variants decode or
-encode strings. Options contain `abortSignal`. Reads return `null` for absent
-files; permission/I/O failures reject. Buffered reads are limited to 16 MiB;
-use streams for larger files. `stat`, `mkdir`, `rename`, `remove`, and `listFiles`
-operate on that same filesystem. Relative paths use `computer.roots.workspace`.
-Remote services use the Remote Computer HTTP v1 protocol for files and sessions.
-
-`computer.commands.run()` accepts a shell `command`, literal `args`, `env`,
-`cwd`, `timeoutMs` and initial text `stdin`. Simple foreground calls return
-`{ stdout, stderr, exitCode }`. Providers advertising `processes` also support
-background handles, incremental output and interactive stdin:
-
-```ts
-const process = await computer.commands.run({
-  command: "python",
-  args: ["-u", "script.py"],
-  env: { MODE: "test" },
-  timeoutMs: 30_000,
-  stdin: true,
-  background: true,
-});
-const finished = process.wait({ onStdout: (text) => console.log(text) });
-await process.sendStdin("input\n", { end: true });
-const result = await finished;
-// To interrupt a running command: await process.kill().
-```
-
-`wait()` starts output consumption and closes the handle when finished; repeated
-calls share its result and its first callbacks. Use `background: true` to supply
-interactive stdin, and `end: true` to close it. The command/owner signal or timeout
-also interrupts the process. Commands are limited to 120 seconds and collected
-output to 2 MiB (a provider may impose lower limits); stdin writes are at most
-64 KiB. Callbacks receive decoded stdout/stderr chunks, not a terminal/PTY.
-E2B and local allow eight retained handles; wait for finished handles to release
-capacity. Hosted default uses the existing daemon's configured process limits.
-
-Hosted default, E2B and authorized local execution implement `processes`.
-just-bash and default dev support foreground options only and explicitly reject
-background/interactive/streaming requests. A remote service must implement the
-optional process-control protocol before advertising the `processes` capability.
-Every process belongs to the current invocation: Worker stop terminates unfinished
-processes before releasing the session or settling its filesystem. Background
-processes cannot outlive a completed Agent run. Normal foreground completion also
-cleans up redirected descendants. Local foreground/background commands share UTF-8
-decoding and process cleanup; the foreground API still uses one request.
-Execution user, PTY, listening
-ports, pause/resume and snapshots are not added by this API.
-
-`defaultComputer()` retains durable/chat defaults and supports a synchronous
-scope callback with `chatId`, `principal`, and `metadata`. Business code supplies
-`principal`; Computer never reads a GEA `userId`. `files` is a map of normalized
-relative workspace paths to strings or `Uint8Array` (2 MiB per file, 4 MiB total,
-1000 files). It seeds only a new allocation. Upgrades, reconnections and deleted
-seed files do not reseed an existing durable workspace; legacy allocations are
-preserved. Ephemeral providers seed each new physical session.
-
-`onSession({ use, ctx })` runs after seeds and bundled Skills are ready, before
-model Tools. `use()` supplies that same session. It runs once per physical
-session, including replacement after confirmed expiry, and is skipped for live
-reconnects. Make the callback idempotent and check nonzero command exit codes;
-failed initialization prevents Tool execution. No unknown command is replayed.
-
-Computer lifecycle uses `create()` / `stop()`. The Worker owns it: create and
-initialize before tools, then stop after the model, tools, context writes and
-response stream have settled. Initialization/setup failures and cancellation also
-release the session, with a separate cleanup signal. Stop preserves durable files
-and the local project; ephemeral files disappear. Repeated stop is safe and must
-not create a new runtime or affect a newer generation. Services need their own
-expiry policy for Worker crashes or unreachable networks. The updated SDK requires
-a lifecycle-capable Worker Runtime; Native retains open/close aliases for older
-immutable Agent bundles. Lifecycle methods are not exposed as model Tools.
-
-`justbash()` provides virtual shell commands in Worker memory, with a 32 MiB public-write
-limit. It and E2B currently create ephemeral sessions per invocation; use Artifacts
-for retained files. No independent GEA Computer Host or additional Pod is required.
-Developer-owned services implement the Remote Computer HTTP v1 protocol
-and connect through `remoteComputer`. Developers choose their image, installed
-CLI tools, environment, and filesystem persistence. The URL's `filesystemId`
-identifies authorized storage; sessionId/invocationId/generation identify execution
-state. There is no Computer SDK, prescribed service framework, or base image in
-this release. Declared capabilities are checked against the actual session.
-
-`localComputer` requires local execution and matching explicit CLI authorization:
-`gea agent dev --json '{"localComputer":"sandbox","sandboxdPath":"/absolute/path/to/sandboxd"}'`.
-It uses the existing project, accepts no seed files, and never deletes the project
-on stop. Tools use returned roots and preserve literal shell commands.
-Trusted mode runs as the OS user and cannot enforce read-only Skills. macOS
-sandbox mode has native tests; Linux requires host-supplied bwrap configuration,
-and Windows local mode is currently unsupported. GUI operations are not exposed.
-Hosted Agents reject local mode. The factories do not add model-visible Tools;
-select them using the Tool files below.
-
-This provides the isolated Computer and makes `context.computer` available to
-custom Tools. `scope` declares whether the durable filesystem belongs to one
-chat, the current user, or a custom partition; it does not select a physical storage provider.
-It does not expose any built-in Computer Tool to the model.
-
-Runtime sessions and their read-only Skill mounts can be reclaimed while the
-durable filesystem remains. With the matching updated Worker Runtime, the SDK
-reconstructs the bundled Skill mount and retries a confirmed pre-execution
-`MOUNT_MISMATCH` once. It does not automatically replay commands after network
-or persistence failures. Publishing the SDK update requires updating hosted
-Worker Runtime first; existing immutable Agent bundles retain their old behavior.
-
-Then explicitly select the model-visible Computer Tools through the same Tool
-file convention. Each SDK factory fixes the Tool ID, input schema, and runtime
-implementation; the caller may override only its description:
-
-```ts
-// tools/computer.ts
-import {
-  applyPatch,
-  bash,
-  defineToolSet,
-  editFile,
-  findFiles,
-  listDirectory,
-  readFile,
-  searchText,
-  writeFile,
-} from "@gea-ai/agent-sdk";
-
-export default defineToolSet([
-  readFile(),
-  listDirectory(),
-  findFiles(),
-  searchText(),
-  writeFile({
-    description:
-      "Write new or small complete files. Build long reports in bounded editFile steps.",
-  }),
-  editFile(),
-  applyPatch(),
-  bash(),
-]);
-```
-
-This array is the complete model-visible Computer Tool set and order. Only
-listed Computer Tools are visible: enabling Computer alone does not add
-`bash`, `readFile`, `writeFile`, or any other built-in Tool. Declaring no
-Computer Tools leaves the model with none, while custom Tools may still use
-`context.computer`.
-
-| Factory           | Fixed Tool ID   | Purpose                                                       |
-| ----------------- | --------------- | ------------------------------------------------------------- |
-| `readFile()`      | `readFile`      | Read bounded text from files, the Agent package, or artifacts |
-| `listDirectory()` | `listDirectory` | List one bounded directory                                    |
-| `findFiles()`     | `findFiles`     | Find files with a glob                                        |
-| `searchText()`    | `searchText`    | Search text across files                                      |
-| `writeFile()`     | `writeFile`     | Create a file or completely write a small file                |
-| `editFile()`      | `editFile`      | Prefer for exact, unique replacements in an existing file     |
-| `applyPatch()`    | `applyPatch`    | Apply a Codex patch to create, update, move, or delete files  |
-| `bash()`          | `bash`          | Run a Bash command from `/workspace`                          |
-
-The CLI discovers `tools/**/*.ts` deterministically and preserves Tool Set
-array order. The default `writeFile()` description tells the model to create a
-small skeleton for a long report and fill it with bounded `editFile()` calls
-instead of sending one large full-report Tool input.
-
-Prefer `editFile()` for ordinary edits to an existing file. Read the file
-first and provide exact, unique `oldText`/`newText` replacements; replacements
-are applied in order, so later edits see earlier edits in the same call.
-
-`applyPatch()` accepts **only Codex patch syntax**. It supports Add File,
-Delete File, Update File with optional Move to, multiple chunks, `@@` context
-anchors, and `*** End of File`. It uses a pinned upstream TypeScript port;
-see `THIRD_PARTY_NOTICES.md` included in this package. Update matching follows
-Codex's context and whitespace rules. Prefer enough surrounding context or a
-named `@@` anchor when the same text appears more than once.
-
-```text
-*** Begin Patch
-*** Update File: notes.md
-@@ ## Next steps
--status: pending
-+status: done
-*** Add File: notes/summary.md
-+Work completed.
-*** End Patch
-```
-
-Paths are literal workspace-relative paths or absolute paths under
-`/workspace`; `a/` and `b/` are actual directory names. Unified diffs and
-Environment ID routing are not supported by this Computer Tool. All paths
-are validated before mutation, and file operations run in order, stopping at
-the first failure. A multi-file patch is not a transaction: `changedPaths`
-reports completed writes/deletes even on failure, `results` lists completed
-operations (a move uses its destination path), and `conflicts` contains the
-failure message. Inspect these outputs and reread changed files before retrying.
-
-This replaces the previous unified-diff input contract. Existing immutable
-Agent bundles retain their embedded SDK; rebuild and publish each Agent with
-the updated SDK to adopt the new behavior. Update custom tool descriptions
-and any callers that still generate unified diffs at the same time.
-
-The package tree above is the minimal starting point. Add Connector-dependent
-custom Tools and referenced Skills only when the Agent needs those capabilities.
-
-`gea agent dev` also generates `.gea/bindings.d.ts`. A custom Tool receives
-configured environment values, capability-bound stable identity, and declared
-Durable Object namespaces without receiving model, Connector, Computer, or
-Durable Object service credentials. A configured `tsconfig.json` should include
-`.gea/bindings.d.ts`; inferred TypeScript projects discover it automatically.
-
-```ts
-const counter = context.durableObjects.COUNTER.getByName(
-  context.identity.chat.id,
-);
-const response = await counter.fetch("https://counter.internal/increment", {
-  method: "POST",
-});
-```
-
-## 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.
-  apiKey: env.GEA_PROJECT_API_KEY,
-});
-// In an application route, after authentication and Chat ownership checks:
-const response = await agent.run(
-  { chatId, message },
-  { signal: request.signal },
-);
-```
-
-The backend provides new-Chat metadata from trusted application state. Do not
-forward browser Cookie/Authorization headers to GEA or expose an anonymous
-proxy. The server client constructs its own headers, refuses redirects, and
-filters response headers while preserving the stream. Its browser export is
-blocked. See the [application integration guide](https://musegea.com/developers/agent-studio-quick-start#api-invocation)
-for session/CSRF integration, Chat ownership checks and reconnecting. These
-entrypoints are available in `0.1.260906-alpha.0` and later.
-
-Applications select the user through the backend Run request's `principal`.
-Computer scope callbacks receive it directly as `principal`; existing Tool and
-hook contexts expose the same value through `auth.current`. GEA resource identity
-is separate and must not be used to infer the application principal. The SDK
-neither fabricates a GEA user nor requires principal IDs to equal GEA user IDs.
-
-## Lazy Computer allocation and scope resolvers
-
-SDK-first Web execution passes trusted identity and caller metadata to the Worker;
-it no longer allocates a filesystem before dispatch. An Agent may declare `chat`,
-`user`, or a synchronous function for `computer.filesystem.scope`. The function
-receives `{ chatId, principal, metadata }` and returns a non-empty string of at most
-256 characters without control characters. The Worker bundle contains the function;
-the immutable snapshot records only `scope: "custom"`.
-
-AgentSession pins the first resolved scope. For custom resolvers, later metadata
-or principal changes never recompute the key; applications must authorize Chat
-access accordingly. Built-in `"user"` scope instead selects the current Run's
-user partition on each allocation and rechecks that a user principal is present. The function receives business metadata
-from Chat creation / first-run input; the application backend must authenticate its
-users and authorize that data. Metadata never grants GEA user permissions.
-
-The native Computer binding requests an allocation from the existing ORPC registry
-on first use. Trusted Run/version context determines ownership. Custom partitions
-include Workspace, Project, Agent and environment; changing API keys preserves
-storage. Runtime coalesces concurrent first operations using an invocation-owned
-cache and keeps allocation IDs, provider details and credentials out of JavaScript.
-Cancellation during allocation prevents Computer dispatch. No Computer use means
-no allocation. Computer opening and Skill mount initialization also remain lazy.
-
-New SDK-first Computer filesystems use shared POSIX for every scope. Locally this
-is the configured filesystem directory; production mounts the common filesystem
-at `AGENT_FILESYSTEM_ROOT` on the Computer hosts. SDK, API and Studio expose scope,
-not provider selection. The Legacy deployment mode does not enable new DO filesystems
-for Studio. Existing allocation identities/providers remain readable without migration.
-User scope requires `principalType: "user"` and uses the current Run's
-`principalId`, including opaque external application identifiers. Studio user
-partitions include Workspace, Project, Agent and environment. Attributes do not
-change that identity. Hosted omission selects the Project service principal and
-cannot reuse a previous Run's user files. The caller supplies `principal`; the
-platform business adapter converts GEA session users before SDK execution.
-Computer does not infer identity from `userId` or `identity.user`.
-
-The local CLI forwards the same selected principal to its allocation callback.
-User files are partitioned by local project, Agent and principal ID; omission
-selects `local-user` and preserves its existing directory. Existing non-Studio
-GEA-user allocation IDs and Chat/custom allocation IDs are retained. Its just-bash
-bridge is a development runtime.
-
-Rollout requires matching Web/ORPC and Worker Runtime, plus Agents rebuilt and
-published with this SDK. No database migration or virtual user is introduced.
-
-```ts
-computer: {
-  enabled: true,
-  filesystem: {
-    durability: "durable",
-    scope: ({ metadata }) => {
-      if (typeof metadata.customerId !== "string" || !metadata.customerId)
-        throw new Error("customerId is required");
-      return `customer:${metadata.customerId}`;
-    },
-  },
-}
-```
-
-## Project Artifacts
-
-Declare `artifacts: {}` to enable `ctx.artifacts` in custom Tools. The default scope
-is the runtime principal; Project and environment are always fixed by the host.
-Enable `artifacts: { tools: true }` for three standard model tools:
-
-| Tool                                                  | Behavior                                                                                        |
-| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
-| `listArtifacts({ query?, prefix?, cursor?, limit? })` | Case-insensitive filename substring search and scoped pagination.                               |
-| `getArtifact({ key })`                                | Metadata and a temporary download URL, bounded text/JSON preview, and current-turn image reads. |
-| `createUpload({ filename, contentType?, key? })`      | A temporary HTTP upload target; optional key selects an output to replace.                      |
-
-A target includes `key`, `uploadUrl`, `method`, `headers`, `expiresAt`, and `maxBytes`.
-Use every returned header and upload original bytes with an ordinary HTTP client.
-For example, in a Computer with curl and network access:
-
-```bash
-curl --fail-with-body --silent --show-error -X PUT \
-  -H 'Authorization: Bearer <returned authorization>' \
-  -H 'Content-Type: application/pdf' \
-  --upload-file /workspace/report.pdf '<uploadUrl>'
-```
-
-The server verifies and publishes in that request; HTTP success returns the
-Artifact. No completion tool is needed. To download, use the `downloadUrl` from
-`getArtifact`, or share that URL directly with the user. If optional text/image
-preview fails, `getArtifact` still returns metadata and the download URL together
-with `previewError`; lookup/authorization failures remain Tool errors. No Computer is allocated
-for Artifact metadata, image reads, or upload authorization. A network-disabled
-Computer cannot use these HTTP URLs; the tools do not bypass its network policy.
-
-Custom Tools use `ctx.artifacts.createUpload`, `get`, `readText`, `list`, `delete`,
-and bounded text `put`. For example:
-
-```ts
-const target = await ctx.artifacts.createUpload({
-  filename: "report.pdf",
-  contentType: "application/pdf",
-});
-const files = await ctx.artifacts.list({ query: "report.pdf", limit: 20 });
-```
-
-`put({key, content, contentType?, title?, filename?, metadata?})` stores UTF-8 text
-up to 2 MiB. `readText(key)` accepts text/JSON up to 2 MiB. `getArtifact` limits its
-model text preview to 8,000 characters and keeps image bytes transient. The SDK's
-old Computer path-copy methods and dedicated transfer protocol have been removed.
-
-A developer can share a scope with trusted code:
-
-```ts
-artifacts: {
-  tools: true,
-  scope: ({ metadata }) => typeof metadata.customerId === "string" ? `customer:${metadata.customerId}` : null,
-},
-```
-
-Authorize customer membership in the application before using business metadata
-as a scope. Null/empty results fail closed. Matching scopes share across Agents
-and Chats. An omitted upload key is `files/<uuid>/<filename>`. Explicit repeated
-keys replace content while preserving Artifact ID and original creation provenance;
-last committed write wins. The reserved `uploads/` namespace is immutable message
-input and cannot be overwritten by Agent uploads. `createUpload` authority lasts
-one hour and can be reused for its same key until expiration. After an uncertain
-HTTP response, inspect the key; failure to receive a reply does not imply rollback.
-
-Downloads use attachment disposition, including HTML/SVG. Temporary links are
-bearer access; get a fresh link from the persistent Artifact key when needed.
-Hosted uploads use bounded disk staging and streaming object-store writes, with a
-1 GiB default limit (configurable up to 10 GiB); local dev supports 1 GiB and stores
-files under `.gea/artifacts`. Ingress and client limits still apply. The saved copy
-is independent of later Computer edits.
-
-For Agent authoring and local development, see the public
-[Agent development guide](https://musegea.com/developers/agent-development).
+[Developer documentation](https://musegea.com/developers/agent-development)