@gea-ai/agent-sdk 0.1.261007-alpha.1 → 0.1.261008-alpha.0

package/dist/agent-media-read.d.ts

@@ -0,0 +1,13 @@
+declare const AgentMediaReadError_base: import("better-result").TaggedErrorClass<"AgentMediaReadError", {
+    message: string;
+    operation: "download Tool output media" | "read Artifact image";
+    status?: number;
+}>;
+export declare class AgentMediaReadError extends AgentMediaReadError_base {
+}
+/** Translate Fetch failures at the Tool/model media boundary, without signed URLs. */
+export declare function readAgentMedia(request: () => Promise<Response>, operation: "download Tool output media" | "read Artifact image", signal?: AbortSignal): Promise<{
+    data: ArrayBuffer;
+    mediaType: string | null;
+}>;
+export {};

package/dist/agent-media-read.js

@@ -0,0 +1,29 @@
+import { TaggedError } from "better-result";
+export class AgentMediaReadError extends TaggedError("AgentMediaReadError")() {
+}
+/** Translate Fetch failures at the Tool/model media boundary, without signed URLs. */
+export async function readAgentMedia(request, operation, signal) {
+    try {
+        signal?.throwIfAborted();
+        const response = await request();
+        if (!response.ok)
+            throw new AgentMediaReadError({
+                operation,
+                status: response.status,
+                message: `Could not ${operation} (HTTP ${response.status}).`,
+            });
+        const data = await response.arrayBuffer();
+        return { data, mediaType: response.headers.get("content-type") };
+    }
+    catch (error) {
+        signal?.throwIfAborted();
+        if (AgentMediaReadError.is(error))
+            throw error;
+        // Fetch/body exceptions may contain credentials or signed URLs. These errors
+        // enter model feedback and traces, so retain the operation, not the raw cause.
+        throw new AgentMediaReadError({
+            operation,
+            message: `Could not ${operation} (network or response-body failure).`,
+        });
+    }
+}

package/dist/agent-worker.js

@@ -15,6 +15,7 @@ import { decodeAgentModelProxyValue, encodeAgentModelProxyValue, } from "@gea-ai
 import { createGeaAI, modelDescriptorSchema } from "./gea-ai.js";
 import { storeToolModelOutput, resolveToolArtifacts, } from "./tool-model-output.js";
 import { mcpToolModelOutput } from "./mcp-tool-output.js";
+import { AgentMediaReadError, readAgentMedia } from "./agent-media-read.js";
 export { createGeaAI } from "./gea-ai.js";
 import { mergeLlmJson, llmRuntimeRequestOptionsSchema, } from "@gea-ai/contract/llm-catalog";
 import { executeChannelAgentRun, uploadChannelInput, } from "./agent-channel-api.js";
@@ -3802,7 +3803,7 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
     const readImage = async (file) => {
         if (!artifactScope)
             throw new Error("Images require Agent Artifacts.");
-        const response = await host.fetch(`${HOST_PATH}/tools/attachments/read`, {
+        const image = await readAgentMedia(() => host.fetch(`${HOST_PATH}/tools/attachments/read`, {
             method: "POST",
             headers: { "content-type": "application/json" },
             body: JSON.stringify({
@@ -3810,16 +3811,14 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
                 ...(file.id ? { id: file.id } : { key: file.key }),
             }),
             signal: input.request.signal,
-        });
-        if (!response.ok)
-            throw new Error(`Could not read Artifact image (${response.status}).`);
-        const bytes = new Uint8Array(await response.arrayBuffer());
+        }), "read Artifact image", input.request.signal);
+        const bytes = new Uint8Array(image.data);
         if (bytes.byteLength > MAX_AGENT_ARTIFACT_IMAGE_BYTES)
             throw new Error("Prepared image exceeds the model image limit.");
         return {
             type: "file",
             data: { type: "data", data: bytes },
-            mediaType: response.headers.get("content-type") ?? file.mediaType,
+            mediaType: image.mediaType ?? file.mediaType,
         };
     };
     const addImage = async (file) => {
@@ -4115,6 +4114,12 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
     const initialPrompt = await startupTracing.withSpan("agent.startup.prompt", () => preparePrompt(withTurnImages(assembleAgentWorkerContext({ context, runtimeContext }), turnImages)));
     const modelCancellation = new AbortController();
     let failure;
+    const executionErrorText = (error, fallback = "Agent execution failed.") => {
+        const original = failure?.error ?? error;
+        return original instanceof AgentMediaReadError
+            ? original.message
+            : fallback;
+    };
     let pendingMainCall;
     let pendingMainModel = configuredModel;
     let lastStepNumber = 0;
@@ -4129,7 +4134,7 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
         // the execution's original failure before publishing that chunk.
         ownSessionOutcome({
             status: input.request.signal.aborted ? "cancelled" : "failed",
-            text: "Agent execution failed.",
+            text: executionErrorText(error),
         });
         recordExecutionFailure(error);
     };
@@ -4267,9 +4272,9 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
             // both the error and final usage from clients.
             ownSessionOutcome({
                 status: input.request.signal.aborted ? "cancelled" : "failed",
-                text: responseMessage.parts
+                text: executionErrorText(failure.error, responseMessage.parts
                     .flatMap((part) => (part.type === "text" ? [part.text] : []))
-                    .join(""),
+                    .join("")),
             });
             return;
         }
@@ -4645,7 +4650,13 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
                     throw failure.error;
             },
             async prepareModel(request) {
-                const prepared = await preparePrompt(withTurnImages(assembleAgentWorkerContext({ context, runtimeContext }), turnImages));
+                const prepared = await preparePrompt(withTurnImages(assembleAgentWorkerContext({ context, runtimeContext }), turnImages)).catch((error) => {
+                    // Core serializes host exceptions through WASM. Preserve this safe,
+                    // typed media failure before that boundary loses its identity.
+                    if (error instanceof AgentMediaReadError)
+                        fail(error);
+                    throw error;
+                });
                 const prompt = [...prepared.instructions, ...prepared.messages];
                 modelPrompt = prompt;
                 const decoratedTools = addCacheControlToToolList(request.tools.map((tool) => ({
@@ -4742,6 +4753,7 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
             async execute({ writer }) {
                 for await (const chunk of projectAgentCoreEvents(tracked, {
                     messageId,
+                    onError: executionErrorText,
                     approvals: pending?.pendingStep.approvals,
                     tools,
                     messageMetadata: {
@@ -4842,6 +4854,7 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
                 : stepCountIs(Number.POSITIVE_INFINITY),
         });
         stream = result.toUIMessageStream({
+            onError: (error) => executionErrorText(error, "An error occurred."),
             generateMessageId: () => payload.responseMessageId,
             originalMessages: payload.originalMessages,
             sendReasoning: true,
@@ -4948,7 +4961,7 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
                         !input.request.signal.aborted) {
                         events.push({
                             type: "error",
-                            errorText: "Agent execution failed.",
+                            errorText: executionErrorText(failure?.error),
                         });
                         streamedError = true;
                     }

package/dist/index.d.ts

@@ -10,7 +10,7 @@ export type { AgentEngine } from "./agent-core-engine.js";
 import type { AgentTracing } from "@gea-ai/contract/agent-tracing";
 export type { AgentTracing, AgentTraceSpan, } from "@gea-ai/contract/agent-tracing";
 import { type AgentContextStrategy } from "./context.js";
-import { remoteAgentDeclarationSchema, type AgentReference } from "@gea-ai/contract/agent-references";
+import { workerAgentReferenceSchema, remoteAgentDeclarationSchema, type AgentReference } from "@gea-ai/contract/agent-references";
 export type { AgentContextStrategy, AgentContextRuntime, AgentContextPrepareStepEvent, AgentContextStepEndEvent, AgentContextEndEvent, } from "./context.js";
 import type { ComputerCommands } from "@gea-ai/contract/computer-commands";
 import type { AgentArtifacts, AgentArtifactScopeResolver } from "@gea-ai/contract/studio-artifacts";
@@ -439,7 +439,7 @@ export declare function agentTool(): DefinedManagedTool<"agent">;
 export interface WorkerAgentRegistry {
 }
 export type WorkerAgentSlug = keyof WorkerAgentRegistry extends never ? string : Extract<keyof WorkerAgentRegistry, string>;
-/** Explicitly makes a main Agent in the same Worker available to the owning Agent. */
+/** @deprecated Use defineRemoteAgent({ slug, description }) instead. */
 export declare function defineAgentReference<const TSlug extends WorkerAgentSlug>(input: {
     slug: TSlug;
     description: string;
@@ -448,15 +448,28 @@ export declare function defineAgentReference<const TSlug extends WorkerAgentSlug
     description: string;
     slug: TSlug;
 };
-export type DefineRemoteAgentInput = Omit<z.input<typeof remoteAgentDeclarationSchema>, "type">;
-/** Invoke a fixed Agent ID. Omitted invocationAuthority uses a protected Project key; oauth requires an existing target installation. Environment defaults to the Host environment. */
-export declare function defineRemoteAgent(input: DefineRemoteAgentInput): {
-    type: "remote";
-    agentId: string;
-    invocationAuthority?: "oauth" | "project_key" | undefined;
-    environment?: "local" | "preview" | "production" | undefined;
+export type DefineRemoteAgentInput = {
+    slug: WorkerAgentSlug;
     description: string;
+    agentId?: never;
+    environment?: never;
+    invocationAuthority?: never;
+} | (Omit<z.input<typeof remoteAgentDeclarationSchema>, "type"> & {
+    slug?: never;
+});
+/** Reference a same-Worker entry by slug, or an independently admitted Agent by ID. */
+export declare function defineRemoteAgent<const TSlug extends WorkerAgentSlug>(input: {
+    slug: TSlug;
+    description: string;
+    agentId?: never;
+    environment?: never;
+    invocationAuthority?: never;
+}): Omit<z.output<typeof workerAgentReferenceSchema>, "slug"> & {
+    slug: TSlug;
 };
+export declare function defineRemoteAgent(input: Omit<z.input<typeof remoteAgentDeclarationSchema>, "type"> & {
+    slug?: never;
+}): z.output<typeof remoteAgentDeclarationSchema>;
 /** @deprecated Enable defineAgent({ sessionTools: true }) instead. */
 export declare function chatList(): DefinedManagedTool<"chat_list">;
 /** @deprecated Enable defineAgent({ sessionTools: true }) instead. */

package/dist/index.js

@@ -3,7 +3,7 @@ import { agentToolOutputOffloadOptionsSchema, } from "@gea-ai/contract/agent-con
 import { resolveModelOptions, } from "@gea-ai/contract/model-options";
 export { aiSdk } from "./ai-sdk.js";
 import { describeAgentContext } from "./context.js";
-import { workerAgentReferenceSchema, remoteAgentDeclarationSchema, } from "@gea-ai/contract/agent-references";
+import { workerAgentReferenceSchema, remoteAgentDeclarationSchema, remoteAgentInputSchema, } from "@gea-ai/contract/agent-references";
 import { agentConnectorAuthSchema, agentConnectorDefinitionSchema, agentConnectorGrantSchema, agentConnectorRuntimeSchema, agentEnvironmentVariableSchema, getAgentConnectorPrincipalType, agentPackageSnapshotSchema, agentSlugSchema, agentSkillSchema, agentToolSchema, GEA_AGENT_PACKAGE_SCHEMA_VERSION, } from "@gea-ai/contract/agent-packages";
 import { agentChannelKeySchema, agentChannelPathSchema, agentCustomChannelDefinitionSchema, agentHttpChannelDefinitionSchema, canonicalAgentChannelJson, } from "@gea-ai/contract/agent-channels";
 import { z } from "zod";
@@ -339,7 +339,7 @@ const agentToolConnectorAliases = Symbol("agentToolConnectorAliases");
 export function agentTool() {
     return { id: "agent", type: "managed" };
 }
-/** Explicitly makes a main Agent in the same Worker available to the owning Agent. */
+/** @deprecated Use defineRemoteAgent({ slug, description }) instead. */
 export function defineAgentReference(input) {
     const reference = workerAgentReferenceSchema.parse({
         ...input,
@@ -347,9 +347,11 @@ export function defineAgentReference(input) {
     });
     return { ...reference, slug: input.slug };
 }
-/** Invoke a fixed Agent ID. Omitted invocationAuthority uses a protected Project key; oauth requires an existing target installation. Environment defaults to the Host environment. */
 export function defineRemoteAgent(input) {
-    return remoteAgentDeclarationSchema.parse({ ...input, type: "remote" });
+    const reference = remoteAgentInputSchema.parse(input);
+    return "slug" in reference
+        ? workerAgentReferenceSchema.parse({ ...reference, type: "worker" })
+        : remoteAgentDeclarationSchema.parse({ ...reference, type: "remote" });
 }
 /** @deprecated Enable defineAgent({ sessionTools: true }) instead. */
 export function chatList() {

package/dist/tool-model-output.js

@@ -1,5 +1,6 @@
 import { convertInlineFileDataToUint8Array } from "@ai-sdk/provider-utils";
 import { z } from "zod";
+import { readAgentMedia } from "./agent-media-read.js";
 const uploadResultSchema = z.object({ id: z.uuid() });
 /** Persist only immutable references in the model context, never signed URLs or bytes. */
 export async function storeToolModelOutput(output, artifacts, signal) {
@@ -29,10 +30,8 @@ export async function storeToolModelOutput(output, artifacts, signal) {
             });
             let body;
             if (part.data.type === "url") {
-                const response = await fetch(part.data.url, { signal });
-                if (!response.ok)
-                    throw new Error(`Tool file download failed (${response.status}).`);
-                body = await response.arrayBuffer();
+                const url = part.data.url;
+                body = (await readAgentMedia(() => fetch(url, { signal }), "download Tool output media", signal)).data;
             }
             else {
                 const bytes = convertInlineFileDataToUint8Array(part.data);

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const agentSdkVersion = "0.1.261007-alpha.1";
+export declare const agentSdkVersion = "0.1.261008-alpha.0";

package/dist/version.js

@@ -1,2 +1,2 @@
 // Generated by scripts/build-sdk-version.mjs from package.json.
-export const agentSdkVersion = "0.1.261007-alpha.1";
+export const agentSdkVersion = "0.1.261008-alpha.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gea-ai/agent-sdk",
-  "version": "0.1.261007-alpha.1",
+  "version": "0.1.261008-alpha.0",
   "private": false,
   "homepage": "https://musegea.com/developers",
   "license": "Apache-2.0",
@@ -119,7 +119,7 @@
     "@ai-sdk/otel": "1.0.119",
     "@ai-sdk/provider": "4.0.19",
     "@ai-sdk/provider-utils": "5.0.50",
-    "@gea-ai/contract": "0.1.261007-alpha.1",
+    "@gea-ai/contract": "0.1.261008-alpha.0",
     "@opentelemetry/api": "1.9.1",
     "@opentelemetry/context-async-hooks": "2.10.0",
     "@opentelemetry/core": "2.10.0",