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

package/THIRD_PARTY_NOTICES.md

@@ -58,6 +58,13 @@ and packaged Worker conformance fixtures before changing the pin.
 
 ## Agent Core WASM
 
+The bundled Core's Anthropic output-schema sanitizer is ported from
+`@ai-sdk/anthropic` **4.0.67**, `src/sanitize-json-schema.ts` (Vercel AI SDK).
+Copyright 2023 Vercel, Inc.; see
+[license and notice](./third-party/anthropic-schema/LICENSE).
+The Rust port retains the upstream transformation using `serde_json` values;
+the original schema still controls final validation.
+
 The optional Agent Core asset is built from this repository's Apache-2.0 Rust
 crate with Rust 1.94.1. Its Cargo dependencies are pinned in
 `crates/agent-core/Cargo.lock`; exact-version license copies and a dependency

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-session-inbox.js

@@ -633,13 +633,18 @@ export async function handleAgentSessionInboxRequest(request, storage) {
                     canonicalAgentChannelJson(input.identity))
                     return Response.json({ error: "session_identity_conflict" }, { status: 409 });
                 if (state.execution?.id === input.executionId) {
-                    if (path === "/v1/inbox/start") {
-                        if (state.started)
-                            return Response.json({ error: "execution_already_started" }, {
-                                status: 409,
-                                headers: { "x-gea-session-execution": "already-started" },
-                            });
-                        state.started = true;
+                    if (input.runId && input.runId !== state.execution.turnId)
+                        return Response.json({ error: "execution_mismatch" }, { status: 409 });
+                    if (path === "/v1/inbox/start" && state.started)
+                        return Response.json({ error: "execution_already_started" }, {
+                            status: 409,
+                            headers: { "x-gea-session-execution": "already-started" },
+                        });
+                    if (!state.started) {
+                        // An inbox claim retains the previous transport until the Host
+                        // admits this execution with its current Run authority.
+                        state.transport = input.transport;
+                        state.started = path === "/v1/inbox/start";
                         await save(tx, state, runs);
                     }
                     return Response.json({ execution: state.execution });

package/dist/agent-worker-context.js

@@ -66,6 +66,62 @@ function groupMessages(messages) {
     }
     return groups;
 }
+// Provider usage is request-wide, not per message. This deliberately estimates
+// content only: UTF-8 bytes / 3 plus framing, without opaque reasoning signatures
+// or base64 expansion. Media gets a fixed allowance, not an exact token count.
+function estimateMessageTokens(message) {
+    const textTokens = (text) => Math.ceil(new TextEncoder().encode(text).length / 3);
+    const mediaTokens = 4_096;
+    if (typeof message.content === "string")
+        return 8 + textTokens(message.content);
+    return (8 +
+        message.content.reduce((total, part) => {
+            switch (part.type) {
+                case "text":
+                case "reasoning":
+                    return total + 8 + textTokens(part.text);
+                case "image":
+                case "reasoning-file":
+                    return total + mediaTokens;
+                case "file":
+                    return (total +
+                        (typeof part.data === "object" &&
+                            "type" in part.data &&
+                            part.data.type === "text"
+                            ? textTokens(part.data.text)
+                            : mediaTokens));
+                case "tool-call":
+                    return (total +
+                        16 +
+                        textTokens(part.toolName) +
+                        textTokens(JSON.stringify(part.input) ?? ""));
+                case "tool-result": {
+                    const output = part.output;
+                    let tokens;
+                    switch (output.type) {
+                        case "content":
+                            tokens = output.value.reduce((count, item) => count +
+                                (item.type === "text"
+                                    ? textTokens(item.text)
+                                    : item.type === "file" && item.data.type === "text"
+                                        ? textTokens(item.data.text)
+                                        : mediaTokens), 0);
+                            break;
+                        case "text":
+                        case "error-text":
+                            tokens = textTokens(output.value);
+                            break;
+                        default:
+                            tokens = textTokens(JSON.stringify(output));
+                    }
+                    return total + 16 + textTokens(part.toolName) + tokens;
+                }
+                default: {
+                    return total + 8 + textTokens(JSON.stringify(part));
+                }
+            }
+        }, 0));
+}
 function getToolOutputText(part) {
     switch (part.output.type) {
         case "error-text":
@@ -224,7 +280,7 @@ export async function applyAgentWorkerToolOutputOffload(input) {
         return input.messages;
     const groups = groupMessages(input.messages);
     const firstProtectedIndex = input.protectRecentGroups
-        ? Math.max(0, groups.length - input.options.preserveRecentGroups)
+        ? Math.max(0, groups.length - (input.options.preserveRecentGroups ?? 5))
         : groups.length;
     const messages = [];
     for (const [groupIndex, group] of groups.entries()) {
@@ -263,13 +319,135 @@ function summarySchema() {
         "## Critical Exact Details\n- Preserve exact IDs, commands, paths, API names, error messages, and config values.",
     ].join("\n\n");
 }
+// Summary input is a textual projection, not a provider request. Keep resource
+// references for recovery but never stringify media bytes or opaque metadata.
+function summaryFileData(data) {
+    if (data instanceof URL) {
+        return data.protocol === "data:"
+            ? { omitted: "inline media bytes" }
+            : { url: data.href };
+    }
+    if (typeof data === "string" ||
+        data instanceof ArrayBuffer ||
+        ArrayBuffer.isView(data)) {
+        return { omitted: "inline media bytes; recover from raw chat history" };
+    }
+    if ("type" in data) {
+        switch (data.type) {
+            case "text":
+                return { text: data.text };
+            case "url": {
+                const url = String(data.url);
+                return url.startsWith("data:")
+                    ? { omitted: "inline media bytes" }
+                    : { url };
+            }
+            case "reference":
+                return { reference: data.reference };
+            case "data":
+                return { omitted: "inline media bytes; recover from raw chat history" };
+        }
+    }
+    return { reference: data };
+}
+function summaryContentPart(part) {
+    switch (part.type) {
+        case "text":
+        case "reasoning":
+            return { type: part.type, text: part.text };
+        case "tool-call":
+            return {
+                type: part.type,
+                toolName: part.toolName,
+                toolCallId: part.toolCallId,
+                input: part.input,
+                providerExecuted: part.providerExecuted,
+            };
+        case "tool-result": {
+            const output = part.output;
+            return {
+                type: part.type,
+                toolName: part.toolName,
+                toolCallId: part.toolCallId,
+                output: output.type === "content"
+                    ? { type: output.type, value: output.value.map(summaryContentPart) }
+                    : output.type === "execution-denied"
+                        ? { type: output.type, reason: output.reason }
+                        : { type: output.type, value: output.value },
+            };
+        }
+        case "file":
+        case "file-data":
+            return {
+                type: part.type,
+                mediaType: part.mediaType,
+                filename: part.filename,
+                data: summaryFileData(part.data),
+            };
+        case "image":
+            return {
+                type: part.type,
+                mediaType: part.mediaType,
+                data: summaryFileData(part.image),
+            };
+        case "image-data":
+        case "reasoning-file":
+            return {
+                type: part.type,
+                mediaType: part.mediaType,
+                data: summaryFileData(part.data),
+            };
+        case "file-url":
+        case "image-url":
+            return {
+                type: part.type,
+                mediaType: "mediaType" in part ? part.mediaType : undefined,
+                url: part.url.startsWith("data:") ? "[inline media omitted]" : part.url,
+            };
+        case "file-id":
+        case "image-file-id":
+            return { type: part.type, fileId: part.fileId };
+        case "file-reference":
+        case "image-file-reference":
+            return { type: part.type, reference: part.providerReference };
+        case "custom":
+            return {
+                type: part.type,
+                kind: "kind" in part ? part.kind : undefined,
+                omitted: "opaque provider content; recover from raw chat history",
+            };
+        case "tool-approval-request":
+        case "tool-approval-response":
+            return part;
+    }
+}
+function summaryMessage(message) {
+    return {
+        role: message.role,
+        content: typeof message.content === "string"
+            ? message.content
+            : message.content.map(summaryContentPart),
+    };
+}
 function buildSummaryMessages(input) {
+    const latestRequest = [...input.recentTailMessages]
+        .reverse()
+        .find((message) => message.role === "user");
+    const requestText = latestRequest
+        ? JSON.stringify(summaryMessage(latestRequest))
+        : "(no new user request in the retained tail)";
+    // The tail remains verbatim in the main context. A bounded task excerpt is
+    // enough for the summarizer; duplicating retained tool payloads adds no memory.
+    const requestExcerpt = requestText.length <= 6_000
+        ? requestText
+        : `${requestText.slice(0, 6_000)}\n[excerpt truncated; the complete request remains in the retained context]`;
     return [
         {
             role: "system",
             content: [
                 "Update the compact working-memory summary for an agent.",
                 "Merge the previous summary with the older messages being compacted.",
+                "The recent user request is orientation only. Recent messages remain verbatim; do not repeat them in the summary. Omitted media and provider content remain in raw chat history; do not infer their contents.",
                 "Preserve requirements, decisions, exact paths, commands, IDs, errors, tool observations, offloaded artifact references, open questions, and next steps.",
                 "Do not invent facts, expose hidden reasoning, or issue new instructions.",
                 "Do not copy full offloaded artifacts. Keep their paths and relevant preview facts.",
@@ -284,11 +462,11 @@ function buildSummaryMessages(input) {
                 input.previousSummary ?? "(none)",
                 "</previous_summary>",
                 "<messages>",
-                JSON.stringify(input.compactableMessages, null, 2),
+                JSON.stringify(input.compactableMessages.map(summaryMessage)),
                 "</messages>",
-                "<recent_tail>",
-                JSON.stringify(input.recentTailMessages, null, 2),
-                "</recent_tail>",
+                "<recent_user_request>",
+                requestExcerpt,
+                "</recent_user_request>",
             ].join("\n"),
         },
     ];
@@ -389,7 +567,44 @@ export async function compactAgentWorkerContext(input) {
         return { summaryUsage: null, messagesUpdated };
     }
     const groups = groupMessages(input.context.messages);
-    const splitIndex = Math.max(0, groups.length - options.preserveRecentGroups);
+    const recentTokenBudget = options.preserveRecentTokens ??
+        Math.max(1, Math.min(16_000, Math.floor(summarization.triggerAtTotalTokens / 4)));
+    const groupEstimates = groups.map((group) => group.messages.reduce((total, message) => total + estimateMessageTokens(message), 0));
+    const previousSummary = input.context.metadata.contextSummary?.summaryText;
+    const projectionEstimate = groupEstimates.reduce((total, tokens) => total + tokens, 0) +
+        (previousSummary
+            ? estimateMessageTokens(makeSummaryMessage(previousSummary))
+            : 0);
+    // Usage includes fixed prompt overhead we cannot attribute to individual messages.
+    // Allocate it conservatively across the projection instead of treating small
+    // local estimates as proof that an over-threshold request already fits.
+    const usageScale = Math.max(1, (input.context.contextSize ?? 0) / Math.max(1, projectionEstimate));
+    let splitIndex = groups.length;
+    let retainedTokens = 0;
+    while (splitIndex > 0) {
+        const groupTokens = Math.ceil(groupEstimates[splitIndex - 1] * usageScale);
+        // Always keep the newest complete group, even when it exceeds the budget.
+        if (splitIndex < groups.length &&
+            (retainedTokens + groupTokens > recentTokenBudget ||
+                (options.preserveRecentGroups !== undefined &&
+                    groups.length - splitIndex >= options.preserveRecentGroups)))
+            break;
+        retainedTokens += groupTokens;
+        splitIndex--;
+    }
+    // Fixed overhead alone is not a reason to pay for summarizing a tiny history.
+    // Explicit retention limits still take precedence over this default safeguard.
+    if (options.preserveRecentTokens === undefined &&
+        options.preserveRecentGroups === undefined &&
+        groupEstimates
+            .slice(0, splitIndex)
+            .reduce((total, tokens) => total + tokens, 0) <
+            Math.max(1, Math.min(1_024, Math.floor(recentTokenBudget / 4)))) {
+        createAgentTracing().currentSpan?.setAttributes({
+            "gea.context.compaction.skip_reason": "insufficient_reduction",
+        });
+        return { summaryUsage: null, messagesUpdated };
+    }
     const compactableMessages = groups
         .slice(0, splitIndex)
         .flatMap((group) => group.messages)
@@ -433,7 +648,18 @@ export async function compactAgentWorkerContext(input) {
                 if (part.type === "content_delta" && kinds.get(part.id) === "text")
                     summaryText += part.delta;
             }
-            summaryUsage = (await result.result).usage;
+            const completion = await result.result;
+            summaryUsage = completion.usage;
+            if (completion.finishReason !== "stop") {
+                // The provider call still counts toward usage, but an incomplete
+                // summary must not replace the previous summary or active history.
+                span.setAttributes({
+                    "gea.context.compaction.outcome": "rejected",
+                    "gea.context.compaction.finish_reason": completion.finishReason,
+                    "gea.context.messages.output_count": input.context.messages.length,
+                });
+                return { summaryUsage, messagesUpdated };
+            }
             if (!summaryText.trim())
                 throw new Error("Context summary was empty.");
             const missingHeadings = REQUIRED_SUMMARY_HEADINGS.filter((heading) => !summaryText.includes(heading));
@@ -480,7 +706,11 @@ export async function compactAgentWorkerContext(input) {
             "gea.context.tokens.estimate": input.context.contextSize ?? undefined,
             "gea.context.tokens.threshold": summarization.triggerAtTotalTokens,
             "gea.context.messages.compacted_count": compactableMessages.length,
-            "gea.context.groups.preserved": options.preserveRecentGroups,
+            "gea.context.groups.preserved": groups.length - splitIndex,
+            "gea.context.tokens.retained_estimate": retainedTokens,
+            "gea.context.tokens.usage_scale": usageScale,
+            "gea.context.tokens.retained_budget": recentTokenBudget,
+            "gea.context.tokens.retained_over_budget": retainedTokens > recentTokenBudget,
         },
     });
 }

package/dist/agent-worker.js

@@ -1,3 +1,4 @@
+import { contextSystemInputSchema } from "@gea-ai/contract/agent-worker-tools";
 import { getAgentProgrammaticToolCalling, isAgentConnectorConnectionHelperExposed, } from "@gea-ai/contract/agent-packages";
 import { AGENT_WORKER_TOOL_METADATA_HEADER, AGENT_WORKER_TOOL_METADATA_VERSION, } from "@gea-ai/contract/agent-worker-tools";
 import { isAgentConnectorExposed } from "@gea-ai/contract/agent-packages";
@@ -15,6 +16,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";
@@ -2231,6 +2233,21 @@ function createHostBackedAgentTools(input) {
                 inputSchema: webSearchInputSchema,
             });
         }
+        else if (definition.id === "context_system") {
+            registerAgentWorkerTool(tools, "contextSystem", tool({
+                description: "Access the current OAuth user's GEA Context resources. Call action=list to discover operations and their input schemas, then action=call with tool and arguments. Documents use Markdown; read before editing and retain contentHash for conflict checks. Requires OAuth; Project keys, custom principals and local calls are unsupported.",
+                inputSchema: contextSystemInputSchema,
+                toModelOutput: mcpToolModelOutput,
+                execute: async (toolInput, options) => invokeHostTool({
+                    host: input.host,
+                    messages: options.messages,
+                    signal: options.abortSignal,
+                    toolCallId: options.toolCallId,
+                    toolInput,
+                    toolName: definition.id,
+                }),
+            }));
+        }
         else if (definition.id === "agent") {
             // The negotiated target catalog below owns registration, including declared subagents.
         }
@@ -2569,7 +2586,6 @@ async function requestSessionJson(input) {
             method: input.method,
         })),
     });
-    input.onResponse?.(response);
     if (!response.ok)
         throw new Error(`AgentSession rejected ${input.path} (${response.status}).`);
     return input.schema.parse(await response.json());
@@ -3026,15 +3042,9 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
     }
     const mutateSession = (values) => {
         const queuedAt = performance.now();
-        const mutationSpan = trace
-            .getTracer("gea.agent-session")
-            .startSpan("agent.session.mutation", {
-            attributes: { "gea.agent.run.id": payload.runId },
-        });
         const result = writeTail.then(async () => {
             const startedAt = performance.now();
             const queueMs = startedAt - queuedAt;
-            const sequence = mutationSequence;
             let failed = true;
             try {
                 if (writeFailure)
@@ -3046,12 +3056,6 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
                     namespace: input.sessionNamespace,
                     path: "/v2/mutations",
                     schema: agentSessionExecutionMutationResultSchema,
-                    onResponse(response) {
-                        mutationSpan.setAttribute("http.response.status_code", response.status);
-                        const timing = response.headers.get("server-timing");
-                        if (timing)
-                            mutationSpan.setAttribute("gea.session.mutation.server_timing", timing);
-                    },
                 });
                 mutationSequence += 1;
                 failed = false;
@@ -3072,22 +3076,6 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
                     "gea.session.persistence.queue_ms": Math.round(persistenceTotals.queueMs),
                     "gea.session.persistence.request_ms": Math.round(persistenceTotals.requestMs),
                 });
-                mutationSpan.setAttributes({
-                    "gea.session.mutation.sequence": sequence,
-                    "gea.session.mutation.kinds": Object.keys(values),
-                    "gea.session.mutation.event_count": values.events?.length ?? 0,
-                    "gea.session.mutation.queue_ms": Math.round(queueMs),
-                    "gea.session.mutation.request_ms": Math.round(requestMs),
-                    ...(invocationTiming.lastModelFinishedAt === undefined
-                        ? {}
-                        : {
-                            "gea.session.mutation.start_after_model_ms": Math.round(startedAt - invocationTiming.lastModelFinishedAt),
-                            "gea.session.mutation.end_after_model_ms": Math.round(performance.now() - invocationTiming.lastModelFinishedAt),
-                        }),
-                });
-                if (failed)
-                    mutationSpan.setStatus({ code: SpanStatusCode.ERROR });
-                mutationSpan.end();
                 if (failed || queueMs + requestMs >= 250)
                     console.info("AgentSession mutation timing", {
                         runId: payload.runId,
@@ -3802,7 +3790,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 +3798,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 +4101,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 +4121,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 +4259,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 +4637,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 +4740,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 +4841,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 +4948,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";
@@ -429,7 +429,7 @@ type CustomAgentToolDefinition = {
     readonly type: "custom";
     readonly [agentToolConnectorAliases]?: Readonly<Record<string, string>>;
 };
-type ManagedToolId = "agent" | "chat_list" | "chat_read" | "chat_send" | "web_search";
+type ManagedToolId = "agent" | "chat_list" | "chat_read" | "chat_send" | "web_search" | "context_system";
 export type DefinedManagedTool<TId extends ManagedToolId = ManagedToolId> = {
     readonly id: TId;
     readonly type: "managed";
@@ -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. */
@@ -464,6 +477,8 @@ export declare function chatRead(): DefinedManagedTool<"chat_read">;
 /** @deprecated Enable defineAgent({ sessionTools: true }) instead. */
 export declare function chatSend(): DefinedManagedTool<"chat_send">;
 export declare function webSearch(): DefinedManagedTool<"web_search">;
+/** Access the current OAuth user's GEA Context without a separate Connection. */
+export declare function contextSystem(): DefinedManagedTool<"context_system">;
 type LegacyAgentToolPreset = {
     readonly preset: "coding" | "default";
     readonly type: "preset";

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() {
@@ -366,6 +368,10 @@ export function chatSend() {
 export function webSearch() {
     return { id: "web_search", type: "managed" };
 }
+/** Access the current OAuth user's GEA Context without a separate Connection. */
+export function contextSystem() {
+    return { id: "context_system", type: "managed" };
+}
 export function defineToolSet(tools) {
     return { tools, type: "tool-set" };
 }

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.261009-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.261009-alpha.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gea-ai/agent-sdk",
-  "version": "0.1.261007-alpha.1",
+  "version": "0.1.261009-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.261009-alpha.0",
     "@opentelemetry/api": "1.9.1",
     "@opentelemetry/context-async-hooks": "2.10.0",
     "@opentelemetry/core": "2.10.0",

package/third-party/anthropic-schema/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2023 Vercel, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.