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

package/README.md

@@ -13,7 +13,83 @@ for validation, Studio display, and exact-version execution. Snapshots never
 contain handler functions, credentials, Connector Connections, tenant identity,
 provider configuration, or environment values.
 
-## Tenant application authentication
+## 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
@@ -34,26 +110,13 @@ approval for external test tenants and explicit environment enablement. The
 application starts standard OAuth; GEA confirms the actual user and consumer tenant
 and resolves the installation internally. Do not send an installation ID.
 
-```ts
-import { StudioAgentClient } from "@gea-ai/agent-sdk/studio-server";
-
-const agent = new StudioAgentClient({
-  api: copiedEnvironmentUrl, // The copied /run URL is accepted directly.
-  token: currentUserAccessToken,
-});
-const response = await agent.run({ message: "Hello" });
-```
-
-The token identifies the user, app and tenant; the URL selects the environment
-and Agent. Users need current consumer tenant membership and application authorization.
-Their configuration, Connections, Chats, files and traces belong to that environment
-installation. Existing Chat/Run calls retain their pinned execution version;
-historical Workspace-bound records still require access to that Workspace.
-
-`projectKeyAuth()` and Project API Keys retain Studio development access. `token`
-accepts either credential, subject to the Agent's declared auth; a Project Key does
-not represent a tenant user or grant cross-tenant installation access. There is no
-third marketplace URL. Standalone Worker OAuth publication remains future work.
+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
 
@@ -175,64 +238,28 @@ Generated code uses `createAgentApplicationFetch()`, which owns:
 /gea/agents[/<agentKey>]/sessions/<sessionId>/v1/<operation>
 ```
 
-Hosted Agent HTTP handlers accept Project API keys and platform user tokens by
-default, equivalent to this explicit configuration:
+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,
-  projectKeyAuth,
-  platformUserAuth,
-} from "@gea-ai/agent-sdk";
+import { defineAgent } from "@gea-ai/agent-sdk";
 
 export default defineAgent({
   name: "support",
   slug: "support",
   model: "gea-model-1",
-  http: { auth: [projectKeyAuth(), platformUserAuth()] },
+  http: { runPath: "/gea/support-entry" },
 });
 ```
 
-Set `auth: projectKeyAuth()` or `auth: platformUserAuth()` to accept only that
-credential type. Explicit configuration replaces the default; it never appends
-the other built-in method. Key calls retain Project ownership, while user tokens
-require application installation admission and keep the consumer's installation
-ownership. The two identities and permissions are never combined. These rules
-apply to Agent routes; ordinary routes in `worker.ts` retain their own authentication.
-
-```ts
-// Inside defineAgent(...):
-http: {
-  auth: false;
-} // Explicit public access to this Agent's HTTP API.
-```
-
-An application can replace the default with its own Session authenticator:
-
-```ts
-http: {
-  auth: async (request, { environment }) => {
-    const session = await getSession(request, environment); // Your verified session.
-    return session
-      ? { principalType: "user", principalId: session.userId }
-      : null;
-  },
-}
-```
-
-An authenticator returns a verified platform authorization, an external user,
-a `Response`, or `null`. An array runs in order: `null` means this method does
-not apply, while an identity or any `Response` stops the chain. An empty array
-or a chain that returns only `null` rejects with 401. Exceptions stop the chain
-and become an HTTP 500 at the Agent boundary. Built-in methods recognize their
-credential prefix before validation; malformed, revoked or denied credentials
-and service failures never fall through to another identity. Custom methods
-should likewise return an error `Response` for invalid credentials, reserving
-`null` for a method that does not apply. A single custom authenticator returning
-`null` still rejects with 401. Project Keys stay on the backend; they never
-represent the creator's GEA user.
-`authenticateProjectKey(request, environment.PROJECT)` also works in ordinary
-Worker routes with a declared Project binding and a Project attachment.
+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
@@ -640,7 +667,7 @@ override to the public `/run` API or Studio composer. See the upstream
 [OpenAI](https://ai-sdk.dev/providers/ai-sdk-providers/openai) and
 [Anthropic](https://ai-sdk.dev/providers/ai-sdk-providers/anthropic) options.
 
-## Background Agent tasks
+## 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.
 
@@ -649,18 +676,51 @@ References are explicit default exports from `subagents/<alias>.ts`:
 ```ts
 import { defineAgentReference, defineRemoteAgent } from "@gea-ai/agent-sdk";
 
-// Same Worker: slug is checked against the CLI-generated WorkerAgentRegistry.
+// Same Worker, checked against the generated WorkerAgentRegistry.
 const sales = defineAgentReference({
   slug: "sales",
   description: "Sales analysis",
 });
-// Same Project: uses the Studio Agent slug and the caller's environment.
+
+// Same Agents API: the host revalidates the calling Run's authority.
 const legal = defineRemoteAgent({
-  slug: "legal-advisor",
+  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 `run_wait({ runIds, timeoutMs? })` to wait for specific Runs and `run_cancel({ 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
@@ -708,22 +768,8 @@ const agent = new StudioAgentClient({
   api: env.GEA_AGENT_API_URL, // Agent base URL without /run.
   token: env.GEA_PROJECT_API_KEY,
 });
-// URL: a GEA Agent protocol endpoint. The key stays in runtime environment configuration.
-const external = defineRemoteAgent({
-  url: "https://legal.example.com/gea/agents/advisor",
-  description: "Legal review",
-  auth: { bearerTokenEnv: "LEGAL_AGENT_KEY" },
-});
 ```
 
-Each reference file default-exports one reference. All targets use `agent({ target: "alias", message, agentId? })`; callers only see their own declared aliases. Include `agentTool()` in the root's tools to additionally allow self copies by omitting `target`. Named delegation follows each node's own declarations; child invocations cannot create another unnamed copy.
-
-The tool returns `{ status: "working", taskId, agentId }`. `task_update({ message })` reports progress, and `task_cancel({ taskId })` requests cancellation. The host continues idle parent conversations when updates arrive. A child task finishes after its descendants and notification inbox settle, including any final summary turn. Continue an idle child with its returned `agentId` and the same target.
-
-URL targets implement GEA task create/status/cancel endpoints. New calls and continuations follow the deployment selected by the URL, retaining history while using its current model, instructions and tools. Accepted tasks finish on their selected version. URL credentials are explicitly configured; source credentials and principals are not forwarded. Pure local development uses URLs for cross-Worker calls because it has no hosted Project identity.
-
-This requires matching SDK, CLI, server and Worker Runtime support and rebuilding immutable bundles. Task Sessions opt into `durable-object-worker-namespace-v1`; existing ordinary Session storage is unchanged. Channel wakeups, approval relay, active-child steering and execution recovery after a host crash remain deferred.
-
 ### Worker build plugins
 
 The Node-only `@gea-ai/agent-sdk/worker-build-plugins` entry exports the shared
@@ -737,7 +783,7 @@ Applications call `/api/v1` using `fetch`, `curl` or another HTTP client. Payloa
 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 an Application user OAuth token. An independently running
+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
@@ -759,3 +805,10 @@ 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.