@gea-ai/agent-sdk 0.1.260925-alpha.0 → 0.1.261002-alpha.0

package/dist/agent-channel-author-runtime.d.ts

@@ -19,19 +19,6 @@ export declare function executeChannelBehavior(input: {
     environment: AgentChannelFetchEnvironment;
     signal: AbortSignal;
 }): Promise<{
-    sequence: number;
-    duplicate: boolean;
-} | {
-    state: AgentChannelJson;
-    intents: {
-        key: string;
-        payload: AgentChannelJson;
-        eventId: string;
-        operationId: string;
-    }[];
-    cursor: number;
-    idempotencyWindowMs?: number | undefined;
-} | {
     status: "sent";
     receipt?: AgentChannelJson | undefined;
 } | {
@@ -56,6 +43,19 @@ export declare function executeChannelBehavior(input: {
         message: string;
         retryable: boolean;
     };
+} | {
+    sequence: number;
+    duplicate: boolean;
+} | {
+    state: AgentChannelJson;
+    intents: {
+        key: string;
+        payload: AgentChannelJson;
+        eventId: string;
+        operationId: string;
+    }[];
+    cursor: number;
+    idempotencyWindowMs?: number | undefined;
 } | {
     events: {
         id: string;

package/dist/agent-core.js

@@ -7,6 +7,9 @@ let compiled;
 export function agentCore(options = {}) {
     return {
         ...options,
+        // A silent model stream must not retain a Run until the provider hard deadline.
+        // Explicit timeout options (including {}) retain caller-owned policy.
+        timeout: options.timeout ?? { chunkMs: 5 * 60_000 },
         output: options.output === undefined
             ? undefined
             : toAgentCoreOutput(options.output),

package/dist/agent-message-history.d.ts

@@ -0,0 +1,3 @@
+/** Old Core policy denials lacked the rejected approval required by AI SDK.
+ * Repair only their presentation; persisted Core decisions still own execution. */
+export declare function repairLegacyToolDenials(message: unknown): unknown;

package/dist/agent-message-history.js

@@ -0,0 +1,38 @@
+import { z } from "zod";
+const assistantHistorySchema = z
+    .object({
+    role: z.literal("assistant"),
+    parts: z.array(z.unknown()),
+})
+    .passthrough();
+const legacyDenialSchema = z
+    .object({
+    type: z.union([z.literal("dynamic-tool"), z.string().startsWith("tool-")]),
+    toolCallId: z.string(),
+    state: z.literal("output-denied"),
+    approval: z
+        .object({ id: z.string(), approved: z.literal(true) })
+        .passthrough()
+        .optional(),
+})
+    .passthrough();
+/** Old Core policy denials lacked the rejected approval required by AI SDK.
+ * Repair only their presentation; persisted Core decisions still own execution. */
+export function repairLegacyToolDenials(message) {
+    const history = assistantHistorySchema.safeParse(message);
+    if (!history.success)
+        return message;
+    return {
+        ...history.data,
+        parts: history.data.parts.map((part) => {
+            const denied = legacyDenialSchema.safeParse(part);
+            return denied.success
+                ? {
+                    ...denied.data,
+                    state: "output-error",
+                    errorText: "Tool execution was denied by policy.",
+                }
+                : part;
+        }),
+    };
+}

package/dist/agent-remote-run.js

@@ -57,60 +57,114 @@ export async function cancelRemoteRun(fetch, run) {
     const response = await fetch(`/runs/${run.id}/cancel`, { method: "POST" });
     await responseJson(response);
 }
+class RemoteRunReadError extends TaggedError("RemoteRunReadError")() {
+}
+async function waitForRemoteRead(ms, signal) {
+    signal.throwIfAborted();
+    await new Promise((resolve, reject) => {
+        const abort = () => {
+            clearTimeout(timer);
+            reject(signal.reason);
+        };
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", abort);
+            resolve();
+        }, ms);
+        signal.addEventListener("abort", abort, { once: true });
+        if (signal.aborted)
+            abort();
+    });
+}
+/** Only idempotent reads retry. Admission and Tool execution are never repeated here. */
+async function readRemoteRunPage(fetch, path, signal) {
+    for (let attempt = 0;; attempt++) {
+        signal.throwIfAborted();
+        const response = await Result.tryPromise(() => fetch(path, { signal }));
+        signal.throwIfAborted();
+        let status;
+        let delay = 250 * 2 ** attempt;
+        if (response.isOk()) {
+            if (response.value.ok)
+                return response.value.json();
+            status = response.value.status;
+            const retryAfter = response.value.headers.get("retry-after");
+            if (retryAfter) {
+                const requestedDelay = /^\d+$/u.test(retryAfter)
+                    ? Number(retryAfter) * 1000
+                    : Date.parse(retryAfter) - Date.now();
+                if (Number.isFinite(requestedDelay))
+                    delay = Math.max(delay, requestedDelay);
+            }
+            await response.value.body?.cancel();
+        }
+        if (attempt >= 2 ||
+            delay > 5000 ||
+            (status !== undefined && status !== 408 && status !== 429 && status < 500))
+            throw new RemoteRunReadError({
+                message: "Remote Run read failed.",
+                status,
+            });
+        await waitForRemoteRead(delay, signal);
+    }
+}
 export async function observeRemoteRun(fetch, run, signal, onInputRequired) {
     let reportedInput;
-    while (true) {
-        signal.throwIfAborted();
-        const record = agentHttpRunSchema.parse(await responseJson(await fetch(`/runs/${run.id}`, { signal })));
-        if (record.id !== run.id || record.session_id !== run.sessionId)
-            throw new Error("Remote Run identity mismatch.");
-        const terminal = ["finished", "error", "aborted", "interrupted"].includes(record.status);
-        const inputMessageId = record.status === "waiting" ? record.input_message_id : null;
-        if (terminal || (onInputRequired && inputMessageId)) {
-            const text = [];
-            let cursor = null;
-            do {
-                const page = messagesSchema.parse(await responseJson(await fetch(`/sessions/${run.sessionId}/messages?limit=100${cursor ? `&cursor=${encodeURIComponent(cursor)}` : ""}`, { signal })));
-                for (const message of page.items)
-                    if (message.run_id === run.id && message.role === "assistant") {
-                        if (!terminal && message.id === inputMessageId && onInputRequired) {
-                            const input = agentApplicationAssistantMessageSchema.parse({
-                                id: message.id,
-                                role: message.role,
-                                parts: message.parts,
-                            });
-                            const key = agentInputRequestKey(input);
-                            if (key !== reportedInput) {
-                                await onInputRequired(input);
-                                reportedInput = key;
+    try {
+        while (true) {
+            signal.throwIfAborted();
+            const record = agentHttpRunSchema.parse(await readRemoteRunPage(fetch, `/runs/${run.id}`, signal));
+            if (record.id !== run.id || record.session_id !== run.sessionId)
+                throw new Error("Remote Run identity mismatch.");
+            const terminal = ["finished", "error", "aborted", "interrupted"].includes(record.status);
+            const inputMessageId = record.status === "waiting" ? record.input_message_id : null;
+            if (terminal || (onInputRequired && inputMessageId)) {
+                const text = [];
+                let cursor = null;
+                do {
+                    const page = messagesSchema.parse(await readRemoteRunPage(fetch, `/sessions/${run.sessionId}/messages?limit=100${cursor ? `&cursor=${encodeURIComponent(cursor)}` : ""}`, signal));
+                    for (const message of page.items)
+                        if (message.run_id === run.id && message.role === "assistant") {
+                            if (!terminal &&
+                                message.id === inputMessageId &&
+                                onInputRequired) {
+                                const input = agentApplicationAssistantMessageSchema.parse({
+                                    id: message.id,
+                                    role: message.role,
+                                    parts: message.parts,
+                                });
+                                const key = agentInputRequestKey(input);
+                                if (key !== reportedInput) {
+                                    await onInputRequired(input);
+                                    reportedInput = key;
+                                }
                             }
+                            for (const part of message.parts)
+                                if (part.type === "text" && typeof part.text === "string")
+                                    text.push(part.text);
                         }
-                        for (const part of message.parts)
-                            if (part.type === "text" && typeof part.text === "string")
-                                text.push(part.text);
-                    }
-                cursor = page.next_cursor;
-            } while (cursor);
-            if (terminal)
-                return {
-                    status: record.status,
-                    text: text.join("\n").slice(0, 200_000),
-                };
+                    cursor = page.next_cursor;
+                } while (cursor);
+                if (terminal)
+                    return {
+                        status: record.status,
+                        text: text.join("\n").slice(0, 200_000),
+                    };
+            }
+            if (!["queued", "running", "waiting"].includes(record.status))
+                throw new Error("Unknown remote Run status.");
+            await waitForRemoteRead(1000, signal);
         }
-        if (!["queued", "running", "waiting"].includes(record.status))
-            throw new Error("Unknown remote Run status.");
-        await new Promise((resolve, reject) => {
-            const abort = () => {
-                clearTimeout(timer);
-                reject(signal.reason);
-            };
-            const timer = setTimeout(() => {
-                signal.removeEventListener("abort", abort);
-                resolve();
-            }, 1000);
-            signal.addEventListener("abort", abort, { once: true });
-            if (signal.aborted)
-                abort();
-        });
+    }
+    catch (error) {
+        // Stop only this parent-owned observation. The remote execution/directory is untouched.
+        // Host shutdown leaves the relation pending so another dispatcher can resume it.
+        signal.throwIfAborted();
+        const status = RemoteRunReadError.is(error) && error.status
+            ? ` (HTTP ${error.status})`
+            : "";
+        return {
+            status: "interrupted",
+            text: `Remote observation interrupted${status}; execution outcome is unknown. Run ${run.id}, Session ${run.sessionId}. Do not resubmit the task; inspect this existing Run.`,
+        };
     }
 }

package/dist/agent-run-host.d.ts

@@ -20,7 +20,7 @@ export declare class AgentRunHost {
             response: Response;
             dispose?: () => void;
         }>;
-        cancelChild(run: AgentChildRun): Promise<void>;
+        cancelChild(run: AgentChildRun): Promise<boolean | void>;
         onError(error: unknown, identity?: {
             runId?: string;
             sessionId?: string;

package/dist/agent-run-host.js

@@ -161,9 +161,7 @@ export class AgentRunHost {
     dispatch(run, inboxExecution) {
         if (this.closed)
             throw new Error("Run dispatcher is stopping.");
-        if (this.executions.has(run.id) ||
-            run.outcome ||
-            (run.cancelRequested && run.destination.type !== "remote"))
+        if (this.executions.has(run.id) || run.outcome)
             return;
         const cancellation = new AbortController();
         this.executions.set(run.id, cancellation);
@@ -207,8 +205,18 @@ export class AgentRunHost {
                         });
                 }
                 else {
-                    cancellation.abort();
-                    return;
+                    // Keep admission alive until the Session has received cancellation.
+                    // Aborting the request earlier can strand an uninitialized child.
+                    const cancelled = await Result.tryPromise(() => this.host.cancelChild(run));
+                    if (cancelled.isOk() && cancelled.value !== false) {
+                        cancellation.abort();
+                        return;
+                    }
+                    if (cancelled.isErr())
+                        this.host.onError(cancelled.error, {
+                            runId: run.id,
+                            sessionId: run.sessionId,
+                        });
                 }
             }
             timer = setTimeout(() => {
@@ -284,8 +292,9 @@ export class AgentRunHost {
                 this.dispatch(run);
             }
             else {
-                this.executions.get(runId)?.abort();
-                await this.host.cancelChild(run);
+                this.dispatch(run);
+                if ((await this.host.cancelChild(run)) !== false)
+                    this.executions.get(runId)?.abort();
             }
         }
         return Response.json({

package/dist/agent-session-execution.js

@@ -444,6 +444,15 @@ export async function handleAgentSessionExecutionRequest(request, storage) {
                 handlerMs = performance.now() - handlerStartedAt;
                 return response;
             });
+            console.info("AgentSession lease release completed", {
+                event: "agent.session.lease_released",
+                runId: input.runId,
+                attemptId: input.attemptId,
+                executionId: input.inbox.executionId,
+                inputWait: Boolean(input.inbox.inputWait),
+                status: response.status,
+                elapsedMs: Math.round(performance.now() - startedAt),
+            });
             response.headers.set("server-timing", `session-handler;dur=${handlerMs.toFixed(1)}, session-transaction;dur=${(performance.now() - startedAt).toFixed(1)}`);
             return response;
         }
@@ -683,7 +692,15 @@ export async function handleAgentSessionExecutionRequest(request, storage) {
                 .parse(await readBody(request, storage));
             const result = await storage.transaction(async (tx) => {
                 const active = await tx.get(key("active-turn"));
-                if (!active || active.runId !== input.runId)
+                if (!active) {
+                    // A local logical Run can execute or wait without a managed lease. The
+                    // inbox still owns its descendants and fences cancellation by Run ID.
+                    const state = await getAgentSessionRunState(tx, input.runId);
+                    return {
+                        requested: state?.status === "waiting" || state?.status === "running",
+                    };
+                }
+                if (active.runId !== input.runId)
                     return { requested: false };
                 if (!active.cancelRequestedAt) {
                     const turn = {

package/dist/agent-session-inbox.js

@@ -467,6 +467,20 @@ async function finishInbox(tx, state, runs, input) {
             await save(tx, state, runs);
             return Response.json({ error: "execution_not_expired" }, { status: 409 });
         }
+        console.warn("AgentSession execution lease expired", {
+            event: "agent.session.lease_expired",
+            sessionId: state.identity.sessionId,
+            runId: turn.runId,
+            attemptId: turn.attemptId,
+            requestId: turn.requestId,
+            executionId: state.execution.id,
+            leaseOwner: turn.leaseOwner,
+            leaseExpiresAt: turn.leaseExpiresAt,
+            started: state.started,
+            waiting: state.wait !== null,
+            pendingChildren: runs.filter((run) => !run.outcome).length,
+            pendingStarts: state.pendingStarts.length,
+        });
     }
     if (inputWait && !outcome && !state.stopped) {
         state.inputWait = {
@@ -644,6 +658,13 @@ export async function handleAgentSessionInboxRequest(request, storage) {
                 if (previous !== undefined)
                     return Response.json({ error: "message_already_accepted" }, { status: 409 });
                 if (input.message && state.inputWait) {
+                    // Retried dispatch of this Run is not a new user turn. In particular,
+                    // a late child-start command must not skip the input it just requested.
+                    if (state.inputWait.turnId === (input.runId ?? input.executionId))
+                        return Response.json({ error: "execution_already_started" }, {
+                            status: 409,
+                            headers: { "x-gea-session-execution": "already-started" },
+                        });
                     await skipInputWait(tx, state, runs);
                     if (state.draining)
                         return Response.json({ error: "session_busy" }, { status: 409 });

package/dist/agent-worker.js

@@ -1,6 +1,7 @@
 import { AGENT_SUBAGENT_CONCURRENCY_HEADER } from "@gea-ai/contract/agent-worker-tools";
 import { DEFAULT_MAX_CONCURRENT_SUBAGENTS } from "@gea-ai/contract/agent-packages";
 import { batchAgentStreamEvents, coalesceAgentTextDeltas, } from "./agent-stream-coalescing.js";
+import { repairLegacyToolDenials } from "./agent-message-history.js";
 import { sendAgentSessionRequest } from "./agent-session-transport.js";
 import { agentSessionOverridesSchema } from "@gea-ai/contract/agent-session-overrides";
 import { resolveModelOptions } from "@gea-ai/contract/model-options";
@@ -3146,13 +3147,19 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
     const submittedUser = payload.currentTurn.some((message) => message.role === "user")
         ? inputUser
         : undefined;
-    if (input.inboxExecution && submittedUser)
-        await appendSessionValue({
-            body: { message: submittedUser, runId: payload.runId },
-            chatId: payload.chatId,
-            namespace: input.sessionNamespace,
-            path: "/v1/messages",
-        });
+    if (input.inboxExecution && submittedUser) {
+        if (sessionExecution) {
+            await mutateSession({ messages: [{ ...submittedUser }] });
+        }
+        else {
+            await appendSessionValue({
+                body: { message: submittedUser, runId: payload.runId },
+                chatId: payload.chatId,
+                namespace: input.sessionNamespace,
+                path: "/v1/messages",
+            });
+        }
+    }
     // Tool continuations still need the current user's durable file references
     // when reconstructing model messages from saved UI history.
     const submittedFiles = inputUser?.parts.flatMap((part) => (part.type === "file" ? [part] : [])) ??
@@ -3615,7 +3622,7 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
             schema: z.object({ message: z.unknown() }),
         });
         const [message] = await validateUIMessages({
-            messages: [saved.message],
+            messages: [repairLegacyToolDenials(saved.message)],
         });
         if (!message || message.role !== "assistant")
             throw new Error("Suspended response is not an assistant message.");
@@ -3740,14 +3747,9 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
             .filter((file) => file.mediaType.startsWith("image/"))
             .map(({ url: _url, ...file }) => file);
     const turnImages = new Map();
-    const addImage = async (file) => {
-        const reference = file.id ?? file.key;
-        if (turnImages.has(reference))
-            return;
+    const readImage = async (file) => {
         if (!artifactScope)
             throw new Error("Images require Agent Artifacts.");
-        if (turnImages.size >= MAX_AGENT_ARTIFACT_IMAGES)
-            throw new Error(`At most ${MAX_AGENT_ARTIFACT_IMAGES} images can be viewed in one user turn.`);
         const response = await host.fetch(`${HOST_PATH}/tools/attachments/read`, {
             method: "POST",
             headers: { "content-type": "application/json" },
@@ -3762,11 +3764,19 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
         const bytes = new Uint8Array(await response.arrayBuffer());
         if (bytes.byteLength > MAX_AGENT_ARTIFACT_IMAGE_BYTES)
             throw new Error("Prepared image exceeds the model image limit.");
-        turnImages.set(reference, {
+        return {
             type: "file",
             data: { type: "data", data: bytes },
             mediaType: response.headers.get("content-type") ?? file.mediaType,
-        });
+        };
+    };
+    const addImage = async (file) => {
+        const reference = file.id ?? file.key;
+        if (turnImages.has(reference))
+            return;
+        if (turnImages.size >= MAX_AGENT_ARTIFACT_IMAGES)
+            throw new Error(`At most ${MAX_AGENT_ARTIFACT_IMAGES} images can be viewed in one user turn.`);
+        turnImages.set(reference, await readImage(file));
         context.metadata.turnImages ??= [];
         if (!context.metadata.turnImages.some((image) => (image.id ?? image.key) === reference))
             context.metadata.turnImages.push(file);
@@ -4040,12 +4050,7 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
     const coreConnections = new Map([[configuredModel, coreConnection]]);
     const coreCacheStates = new Map([[configuredModel, promptCacheState]]);
     const preparePrompt = async (messages) => {
-        messages = await resolveToolArtifacts(messages, (toolName, toolCallId) => artifactScope
-            ? createAgentArtifacts({
-                scope: artifactScope,
-                invoke: (operation) => invokeArtifact(operation, toolName, { toolCallId }),
-            })
-            : undefined);
+        messages = await resolveToolArtifacts(messages, (id, mediaType) => readImage({ id, mediaType }));
         const instructionCount = payload.instructions.length;
         const prepared = addCacheControlToMessages([...payload.instructions, ...messages], (coreModel === configuredModel
             ? payload.cacheControlProvider
@@ -4657,6 +4662,7 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
             async execute({ writer }) {
                 for await (const chunk of projectAgentCoreEvents(tracked, {
                     messageId,
+                    approvals: pending?.pendingStep.approvals,
                     tools,
                     messageMetadata: {
                         trace: invocationTrace,

package/dist/experimental/agent-core-ui.d.ts

@@ -8,6 +8,10 @@ export declare function projectAgentCoreEvents(turn: AsyncGenerator<AgentCoreEve
     messageMetadata?: unknown;
     /** Preserve AI SDK's declared Tool kind; raw hosts default to dynamic tools. */
     tools?: ToolSet;
+    approvals?: ReadonlyArray<{
+        id: string;
+        call_id: string;
+    }>;
     onError?: (error: Error) => string;
 }): AsyncGenerator<UIMessageChunk>;
 export declare function createAgentCoreUIStream(core: ReturnType<typeof createAgentCore>, message: AgentCoreInput, host: AgentCoreHost, options: {
@@ -15,6 +19,10 @@ export declare function createAgentCoreUIStream(core: ReturnType<typeof createAg
     signal?: AbortSignal;
     messageMetadata?: unknown;
     tools?: ToolSet;
+    approvals?: ReadonlyArray<{
+        id: string;
+        call_id: string;
+    }>;
     onError?: (error: Error) => string;
 }): ReadableStream<UIMessageChunk>;
 export declare function createAgentCoreUIResponse(stream: ReadableStream<UIMessageChunk>, init?: ResponseInit): Response;

package/dist/experimental/agent-core-ui.js

@@ -13,6 +13,8 @@ export async function* projectAgentCoreEvents(turn, options) {
     let resumed = false;
     const blocks = new Map();
     const calls = new Map();
+    const approvalCalls = new Map(options.approvals?.map((approval) => [approval.id, approval.call_id]));
+    const rejectedApprovals = new Set();
     let lastModelHadToolCalls = false;
     let outcome;
     try {
@@ -116,6 +118,7 @@ export async function* projectAgentCoreEvents(turn, options) {
                     lastModelHadToolCalls = event.finish_reason === "tool_calls";
                     break;
                 case "approval_requested": {
+                    approvalCalls.set(event.approval_id, event.call_id);
                     const call = calls.get(event.call_id);
                     if (!call)
                         throw new Error(`Missing approval tool call: ${event.call_id}`);
@@ -133,6 +136,11 @@ export async function* projectAgentCoreEvents(turn, options) {
                     break;
                 }
                 case "approval_resolved":
+                    if (!event.approved) {
+                        const callId = approvalCalls.get(event.approval_id);
+                        if (callId)
+                            rejectedApprovals.add(callId);
+                    }
                     yield {
                         type: "tool-approval-response",
                         approvalId: event.approval_id,
@@ -169,14 +177,14 @@ export async function* projectAgentCoreEvents(turn, options) {
                     const call = calls.get(event.call_id);
                     if (!call)
                         throw new Error(`Missing UI tool call: ${event.call_id}`);
-                    if (event.denied) {
+                    if (event.denied && rejectedApprovals.has(event.call_id)) {
                         part = {
                             type: "tool-output-denied",
                             toolCallId: call.id,
                             toolName: call.name,
                         };
                     }
-                    else if (event.is_error) {
+                    else if (event.is_error || event.denied) {
                         const error = toolErrorSchema.safeParse(event.output);
                         part = {
                             type: "tool-error",
@@ -273,7 +281,10 @@ export function createAgentCoreUIStream(core, message, host, options) {
         ? AbortSignal.any([options.signal, cancellation.signal])
         : cancellation.signal;
     const turn = runAgentCore(core, message, host, signal);
-    const projected = projectAgentCoreEvents(turn, options);
+    const projected = projectAgentCoreEvents(turn, {
+        ...options,
+        approvals: core.pendingApprovals,
+    });
     let cancelled = false;
     return new ReadableStream({
         async pull(controller) {

package/dist/experimental/agent-core.d.ts

@@ -35,6 +35,15 @@ export interface AgentCoreHost {
 }
 /** One turn per instance. All model/tool progression executes inside Rust. */
 export declare function createAgentCore(module: WebAssembly.Module, config: AgentCoreConfig): {
+    pendingApprovals: {
+        id: string;
+        call_id: string;
+        response?: {
+            id: string;
+            approved: boolean;
+            reason?: string | undefined;
+        } | undefined;
+    }[];
     run(message: AgentCoreInput, host: AgentCoreHost, emit: (event: AgentCoreEvent) => Promise<void>, signal: AbortSignal): Promise<{
         output?: z.util.JSONType | undefined;
         reason: "awaiting_approval" | "awaiting_tool_results" | "cancelled" | "completed" | "failed" | "model_limit" | "step_limit" | "stopped";

package/dist/experimental/agent-core.js

@@ -355,6 +355,7 @@ export function createAgentCore(module, config) {
         throw new Error("Unsupported Agent Core ABI.");
     const run = jspi.promising(exports.agent_run);
     return {
+        pendingApprovals: configuration.pending_step?.approvals ?? [],
         async run(message, host, emit, signal) {
             const outcome = await this.runOutcome(message, host, emit, signal);
             if (outcome.details)

package/dist/index.d.ts

@@ -427,22 +427,12 @@ export declare function defineAgentReference<const TSlug extends WorkerAgentSlug
 export type DefineRemoteAgentInput = {
     agentId: string;
     description: string;
-    url?: string;
-    environment?: "preview" | "production" | "local";
-    auth?: {
-        bearerTokenEnv: string;
-    };
 };
-/** Invoke a fixed Agent ID through Agents API; cross-service credentials stay in host secrets. */
+/** Invoke an exported Agent in the current Project using the caller's authority and environment. */
 export declare function defineRemoteAgent(input: DefineRemoteAgentInput): {
     type: "remote";
     agentId: string;
-    url?: string | undefined;
-    environment?: "local" | "preview" | "production" | undefined;
     description: string;
-    auth?: {
-        bearerTokenEnv: string;
-    } | undefined;
 };
 /** @deprecated Enable defineAgent({ sessionTools: true }) instead. */
 export declare function chatList(): DefinedManagedTool<"chat_list">;

package/dist/index.js

@@ -2,7 +2,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, remoteAgentReferenceSchema, } from "@gea-ai/contract/agent-references";
+import { workerAgentReferenceSchema, remoteAgentDeclarationSchema, } 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";
@@ -331,9 +331,9 @@ export function defineAgentReference(input) {
     });
     return { ...reference, slug: input.slug };
 }
-/** Invoke a fixed Agent ID through Agents API; cross-service credentials stay in host secrets. */
+/** Invoke an exported Agent in the current Project using the caller's authority and environment. */
 export function defineRemoteAgent(input) {
-    return remoteAgentReferenceSchema.parse({ ...input, type: "remote" });
+    return remoteAgentDeclarationSchema.parse({ ...input, type: "remote" });
 }
 /** @deprecated Enable defineAgent({ sessionTools: true }) instead. */
 export function chatList() {

package/dist/tool-model-output.d.ts

@@ -4,4 +4,10 @@ import type { AgentArtifacts, AgentToolModelOutput } from "@gea-ai/contract/stud
 /** Persist only immutable references in the model context, never signed URLs or bytes. */
 export declare function storeToolModelOutput(output: AgentToolModelOutput, artifacts: AgentArtifacts | undefined, signal?: AbortSignal): Promise<ToolResultOutput>;
 /** Resolve scoped Artifact access for this request without mutating durable messages. */
-export declare function resolveToolArtifacts(messages: ModelMessage[], artifacts: (toolName: string, toolCallId: string) => AgentArtifacts | undefined): Promise<ModelMessage[]>;
+export declare function resolveToolArtifacts(messages: ModelMessage[], readImage: (id: string, mediaType: string) => Promise<{
+    mediaType: string;
+    data: {
+        type: "data";
+        data: Uint8Array;
+    };
+}>): Promise<ModelMessage[]>;

package/dist/tool-model-output.js

@@ -68,7 +68,7 @@ export async function storeToolModelOutput(output, artifacts, signal) {
     return { type: "content", value };
 }
 /** Resolve scoped Artifact access for this request without mutating durable messages. */
-export async function resolveToolArtifacts(messages, artifacts) {
+export async function resolveToolArtifacts(messages, readImage) {
     return Promise.all(messages.map(async (message) => {
         if (message.role !== "tool")
             return message;
@@ -83,15 +83,11 @@ export async function resolveToolArtifacts(messages, artifacts) {
                         typeof item.data.reference !== "object" ||
                         !item.data.reference.geaArtifactId)
                         return item;
-                    const scoped = artifacts(part.toolName, part.toolCallId);
-                    if (!scoped)
-                        throw new Error("Tool Artifact references require Agent Artifacts.");
-                    const { downloadUrl } = await scoped.get({
-                        id: item.data.reference.geaArtifactId,
-                    });
+                    const image = await readImage(item.data.reference.geaArtifactId, item.mediaType);
                     return {
                         ...item,
-                        data: { type: "url", url: new URL(downloadUrl) },
+                        mediaType: image.mediaType,
+                        data: image.data,
                     };
                 }));
                 return { ...part, output: { ...part.output, value } };

package/dist/tracing.js

@@ -1,3 +1,4 @@
+import { agentSdkVersion } from "./version.js";
 import { Result } from "better-result";
 import { captureTraceContext } from "./trace-context.js";
 import { OpenTelemetry } from "@ai-sdk/otel";
@@ -135,7 +136,7 @@ function initializeTracing() {
     });
     trace.setGlobalTracerProvider(provider);
     registerTelemetry(new OpenTelemetry({
-        tracer: provider.getTracer("gea.agent-sdk", "0.1.260903-alpha.0"),
+        tracer: provider.getTracer("gea.agent-sdk", agentSdkVersion),
         headers: false,
         providerMetadata: false,
         runtimeContext: false,
@@ -167,7 +168,7 @@ export async function traceWorkerRequest(request, name, attributes, execute) {
     };
     const parent = extractTraceContext(request.headers).setValue(requestTraceScope, scope);
     const span = currentProvider
-        .getTracer("gea.agent-sdk", "0.1.260903-alpha.0")
+        .getTracer("gea.agent-sdk", agentSdkVersion)
         .startSpan(name, {
         attributes,
         kind: SpanKind.SERVER,
@@ -346,7 +347,9 @@ export function createAgentTracing(signal) {
         async withSpan(name, execute, options) {
             if (!available())
                 return await context.with(suppressTracing(ROOT_CONTEXT), () => execute(view()));
-            const span = trace.getTracer("gea.agent-sdk").startSpan(name, options);
+            const span = trace
+                .getTracer("gea.agent-sdk", agentSdkVersion)
+                .startSpan(name, options);
             return await context.with(trace.setSpan(context.active(), span), async () => {
                 // This callback boundary annotates outcomes without changing the protocol.
                 try {

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const agentSdkVersion = "0.1.261002-alpha.0";

package/dist/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gea-ai/agent-sdk",
-  "version": "0.1.260925-alpha.0",
+  "version": "0.1.261002-alpha.0",
   "private": false,
   "homepage": "https://musegea.com/developers",
   "license": "Apache-2.0",
@@ -115,7 +115,7 @@
     "@ai-sdk/otel": "1.0.9",
     "@ai-sdk/provider": "4.0.1",
     "@ai-sdk/provider-utils": "5.0.2",
-    "@gea-ai/contract": "0.1.260925-alpha.0",
+    "@gea-ai/contract": "0.1.261002-alpha.0",
     "@opentelemetry/api": "1.9.1",
     "@opentelemetry/context-async-hooks": "2.10.0",
     "@opentelemetry/core": "2.10.0",
@@ -151,7 +151,7 @@
     }
   },
   "scripts": {
-    "build": "node ../../scripts/build-worker-ai.mjs --check && node scripts/build-agent-core.mjs && pnpm --filter @gea-ai/contract build && rm -rf dist && tsc -p tsconfig.build.json && node ../../scripts/rewrite-esm-relative-imports.mjs dist && cp src/agent-core.wasm dist/agent-core.wasm",
+    "build": "node scripts/build-sdk-version.mjs && node ../../scripts/build-worker-ai.mjs --check && node scripts/build-agent-core.mjs && pnpm --filter @gea-ai/contract build && rm -rf dist && tsc -p tsconfig.build.json && node ../../scripts/rewrite-esm-relative-imports.mjs dist && cp src/agent-core.wasm dist/agent-core.wasm",
     "pack:npm": "pnpm pack --pack-destination dist",
     "publish:npm": "pnpm publish --access public --tag alpha",
     "test": "vp test run",