@gea-ai/agent-sdk 0.1.261003-alpha.1 → 0.1.261004-alpha.0

package/dist/agent-call.d.ts

@@ -117,7 +117,7 @@ export declare function createWorkerAgentTool(input: {
             sessionId?: string | undefined;
             message: string;
         } | {
-            error: "child_busy";
+            error: string;
             message: string;
         }>;
     }) => import("@ai-sdk/provider-utils").ToolResultOutput | PromiseLike<import("@ai-sdk/provider-utils").ToolResultOutput>) | undefined;
@@ -139,7 +139,7 @@ export declare function createWorkerAgentTool(input: {
         sessionId?: string | undefined;
         message: string;
     } | {
-        error: "child_busy";
+        error: string;
         message: string;
     }> | undefined;
     execute: import("ai").ToolExecuteFunction<{
@@ -178,7 +178,7 @@ export declare function createWorkerAgentTool(input: {
         sessionId?: string | undefined;
         message: string;
     } | {
-        error: "child_busy";
+        error: string;
         message: string;
     }, NoInfer<import("@ai-sdk/provider-utils").Context>>;
 } & {
@@ -252,7 +252,7 @@ export declare function createWorkerAgentTool(input: {
         sessionId?: string | undefined;
         message: string;
     } | {
-        error: "child_busy";
+        error: string;
         message: string;
     }, NoInfer<import("@ai-sdk/provider-utils").Context>>;
 }) | ({
@@ -365,7 +365,7 @@ export declare function createWorkerAgentTool(input: {
             sessionId?: string | undefined;
             message: string;
         } | {
-            error: "child_busy";
+            error: string;
             message: string;
         }>;
     }) => import("@ai-sdk/provider-utils").ToolResultOutput | PromiseLike<import("@ai-sdk/provider-utils").ToolResultOutput>) | undefined;
@@ -387,7 +387,7 @@ export declare function createWorkerAgentTool(input: {
         sessionId?: string | undefined;
         message: string;
     } | {
-        error: "child_busy";
+        error: string;
         message: string;
     }> | undefined;
     execute: import("ai").ToolExecuteFunction<{
@@ -426,7 +426,7 @@ export declare function createWorkerAgentTool(input: {
         sessionId?: string | undefined;
         message: string;
     } | {
-        error: "child_busy";
+        error: string;
         message: string;
     }, NoInfer<import("@ai-sdk/provider-utils").Context>>;
 } & {
@@ -500,7 +500,7 @@ export declare function createWorkerAgentTool(input: {
         sessionId?: string | undefined;
         message: string;
     } | {
-        error: "child_busy";
+        error: string;
         message: string;
     }, NoInfer<import("@ai-sdk/provider-utils").Context>>;
 }) | ({
@@ -613,7 +613,7 @@ export declare function createWorkerAgentTool(input: {
             sessionId?: string | undefined;
             message: string;
         } | {
-            error: "child_busy";
+            error: string;
             message: string;
         }>;
     }) => import("@ai-sdk/provider-utils").ToolResultOutput | PromiseLike<import("@ai-sdk/provider-utils").ToolResultOutput>) | undefined;
@@ -635,7 +635,7 @@ export declare function createWorkerAgentTool(input: {
         sessionId?: string | undefined;
         message: string;
     } | {
-        error: "child_busy";
+        error: string;
         message: string;
     }> | undefined;
     execute: import("ai").ToolExecuteFunction<{
@@ -674,7 +674,7 @@ export declare function createWorkerAgentTool(input: {
         sessionId?: string | undefined;
         message: string;
     } | {
-        error: "child_busy";
+        error: string;
         message: string;
     }, NoInfer<import("@ai-sdk/provider-utils").Context>>;
 } & {
@@ -724,7 +724,7 @@ export declare function createWorkerAgentTool(input: {
         sessionId?: string | undefined;
         message: string;
     } | {
-        error: "child_busy";
+        error: string;
         message: string;
     }, NoInfer<import("@ai-sdk/provider-utils").Context>>;
 }) | ({
@@ -837,7 +837,7 @@ export declare function createWorkerAgentTool(input: {
             sessionId?: string | undefined;
             message: string;
         } | {
-            error: "child_busy";
+            error: string;
             message: string;
         }>;
     }) => import("@ai-sdk/provider-utils").ToolResultOutput | PromiseLike<import("@ai-sdk/provider-utils").ToolResultOutput>) | undefined;
@@ -859,7 +859,7 @@ export declare function createWorkerAgentTool(input: {
         sessionId?: string | undefined;
         message: string;
     } | {
-        error: "child_busy";
+        error: string;
         message: string;
     }> | undefined;
     execute: import("ai").ToolExecuteFunction<{
@@ -898,7 +898,7 @@ export declare function createWorkerAgentTool(input: {
         sessionId?: string | undefined;
         message: string;
     } | {
-        error: "child_busy";
+        error: string;
         message: string;
     }, NoInfer<import("@ai-sdk/provider-utils").Context>>;
 } & {
@@ -948,7 +948,7 @@ export declare function createWorkerAgentTool(input: {
         sessionId?: string | undefined;
         message: string;
     } | {
-        error: "child_busy";
+        error: string;
         message: string;
     }, NoInfer<import("@ai-sdk/provider-utils").Context>>;
 });

package/dist/agent-call.js

@@ -8,7 +8,7 @@ import { captureTraceContext } from "./trace-context.js";
 /** The host opens a fresh Worker invocation; only its visible answer returns to the caller. */
 export function createWorkerAgentTool(input) {
     return tool({
-        description: `Start an Agent Run in a new or idle child Session. Use runWait with returned runIds and runCancel to cancel. Use sessionId to continue the same Session. ${input.canCopy ? "Omit target to create a copy of yourself." : "Select a declared target."} Available targets: ${JSON.stringify(input.agents)}. Supply context in message.${input.artifactScope ? " To send files, use an AI SDK user message with file parts containing immutable Artifact file_id values." : ""}`,
+        description: `Start an Agent Run in a new or idle child Session. Use runWait with returned runIds and runCancel to cancel. Use sessionId to continue the same Session. ${input.canCopy ? "Omit target to create a copy of yourself." : "Select a declared target."} Available targets: ${JSON.stringify(input.agents)}. Supply context in message.${input.artifactScope ? " To send selected files, use a user message with file parts containing immutable Artifact file_id values. Refer to attachments by filename or order in task text; remote transfer may assign new IDs, exposed to the child in Attached Artifact metadata. IDs hardcoded in text are not rewritten." : ""}`,
         inputSchema: agentCallInputSchema.extend({
             target: input.agents.length
                 ? input.canCopy
@@ -50,9 +50,18 @@ export function createWorkerAgentTool(input) {
                         return {
                             ...remote.data,
                             message: remote.data.error === "remote_run_rejected"
-                                ? "The remote Run was not admitted. Resolve the remote service failure before retrying."
+                                ? "The remote Run was not admitted. Check Artifact transfer and remote service diagnostics before retrying. Local Hosts support files only through the implicit same-Project binding. An unconfirmed upload may have left an orphan copy."
                                 : "Remote Run admission is uncertain and its capacity is retained. Do not resubmit; reconcile the reservation with the remote service first.",
                         };
+                    if (z
+                        .object({
+                        error: z.literal("remote_artifact_transfer_unsupported"),
+                    })
+                        .safeParse(value).success)
+                        return {
+                            error: "remote_artifact_transfer_unsupported",
+                            message: "This Host cannot transfer files to remote Agents. Use a Host with Artifact transfer support.",
+                        };
                     const busy = z
                         .object({ error: z.literal("child_busy") })
                         .safeParse(value);

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

@@ -1,13 +1,16 @@
 import { Result } from "better-result";
 import { z } from "zod";
 import { agentApplicationAssistantMessageSchema } from "@gea-ai/contract/agent-applications";
-import type { AgentCallMessage, AgentChildRun, AgentChildRunDestination, AgentChildRunOutcome } from "@gea-ai/contract/agent-worker-tools";
+import type { AgentRemoteFileMapping, AgentCallMessage, AgentChildRun, AgentChildRunDestination, AgentChildRunOutcome } from "@gea-ai/contract/agent-worker-tools";
 import type { StudioArtifactInputFile } from "@gea-ai/contract/studio-artifacts";
 /** Internal transport shared by hosted and local Run dispatch; not a public API client. */
 export type RemoteRunFetch = (path: string, init?: RequestInit) => Promise<Response>;
 export type RemoteRunDestination = Extract<AgentChildRunDestination, {
     type: "remote";
 }>;
+export type RemoteInputFiles = NonNullable<AgentChildRun["artifacts"]>;
+export type RemoteFileMapping = AgentRemoteFileMapping;
+export type RemoteInputTransfer = (files: RemoteInputFiles, signal: AbortSignal) => Promise<RemoteFileMapping>;
 declare const RemoteRunAdmissionError_base: import("better-result").TaggedErrorClass<"RemoteRunAdmissionError", {
     message: string;
     cause: unknown;
@@ -23,6 +26,9 @@ export declare function submitRemoteRun(fetch: RemoteRunFetch, input: {
     artifacts?: Array<StudioArtifactInputFile & {
         id: string;
     }>;
+}, options?: {
+    transferFiles?: RemoteInputTransfer;
+    signal?: AbortSignal;
 }): Promise<Result<{
     runId: string;
     sessionId: string;

package/dist/agent-remote-run.js

@@ -2,6 +2,7 @@ import { Result, TaggedError } from "better-result";
 import { z } from "zod";
 import { agentApplicationAssistantMessageSchema, agentInputRequestKey, } from "@gea-ai/contract/agent-applications";
 import { agentHttpRunSchema, agentHttpMessageResourceSchema, } from "@gea-ai/contract/agent-http-api";
+import { getAgentCallFileIds, agentRemoteFileMappingSchema, } from "@gea-ai/contract/agent-worker-tools";
 const sessionSchema = z.object({ id: z.uuid() });
 const messagesSchema = z.object({
     items: z.array(agentHttpMessageResourceSchema.extend({ run_id: z.uuid().nullable() })),
@@ -16,26 +17,57 @@ async function responseJson(response) {
 }
 class RemoteRunAdmissionError extends TaggedError("RemoteRunAdmissionError")() {
 }
-export async function submitRemoteRun(fetch, input) {
+export async function submitRemoteRun(fetch, input, options = {}) {
     let sessionId = input.sessionId;
     let submitting = false;
     let rejected = false;
     return Result.tryPromise({
         try: async () => {
+            const signal = options.signal ?? AbortSignal.timeout(120_000);
+            signal.throwIfAborted();
+            let message = input.message;
+            const ids = [...new Set(getAgentCallFileIds(message))];
+            if (ids.length) {
+                if (!options.transferFiles)
+                    throw new Error("This Host does not support remote Artifact transfer.");
+                const files = ids.map((id) => {
+                    const file = input.artifacts?.find((file) => file.id === id);
+                    if (!file)
+                        throw new Error("Selected Artifact was not authorized by the Host.");
+                    return file;
+                });
+                const copies = agentRemoteFileMappingSchema.parse(await options.transferFiles(files, signal));
+                const mapping = new Map(copies.map((copy) => [copy.sourceId, copy.id]));
+                if (copies.length !== ids.length ||
+                    mapping.size !== ids.length ||
+                    ids.some((id) => !mapping.has(id)))
+                    throw new Error("Remote Artifact transfer receipt is incomplete.");
+                if (typeof message !== "string")
+                    message = {
+                        ...message,
+                        parts: message.parts.map((part) => part.type === "file"
+                            ? { ...part, file_id: mapping.get(part.file_id) }
+                            : part),
+                    };
+            }
+            signal.throwIfAborted();
             sessionId ??= sessionSchema.parse(await responseJson(await fetch("/sessions", {
                 method: "POST",
+                signal,
                 headers: { "content-type": "application/json" },
                 body: JSON.stringify({
                     agent_id: input.destination.agentId,
                     environment: input.destination.environment,
                 }),
             }))).id;
+            signal.throwIfAborted();
             submitting = true;
             // No automatic replay: a lost response does not prove Run admission failed.
             const response = await fetch(`/sessions/${sessionId}/runs`, {
                 method: "POST",
                 headers: { "content-type": "application/json" },
-                body: JSON.stringify({ input: input.message, stream: false }),
+                signal,
+                body: JSON.stringify({ input: message, stream: false }),
             });
             rejected = [400, 401, 403, 404, 405, 409, 413, 415, 422, 429].includes(response.status);
             const run = agentHttpRunSchema.parse(await responseJson(response));
@@ -48,7 +80,7 @@ export async function submitRemoteRun(fetch, input) {
             sessionId,
             definitive: !submitting || rejected,
             message: !submitting || rejected
-                ? "Remote Run was not admitted."
+                ? "Remote Run was not admitted. Artifact preparation or admission failed; inspect Host diagnostics before retrying. An unconfirmed upload may leave an orphan copy."
                 : "Remote Run admission is unknown; do not resubmit.",
         }),
     });

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

@@ -1,8 +1,9 @@
-import { type RemoteRunDestination } from "./agent-remote-run";
+import { type RemoteRunDestination, type RemoteInputFiles, type RemoteFileMapping } from "./agent-remote-run";
 import { type AgentCallMessage, type AgentChildRun, type AgentChildRunDestination, type AgentChildRunHostEvent } from "@gea-ai/contract/agent-worker-tools";
 import type { TraceContext, TraceContinuation } from "@gea-ai/contract/traces";
 import type { AgentSessionInboxExecution } from "@gea-ai/contract/agent-session-inbox";
-import type { StudioArtifactInputFile } from "@gea-ai/contract/studio-artifacts";
+import type { StudioArtifactScope, StudioArtifactInputFile } from "@gea-ai/contract/studio-artifacts";
+export type { RemoteRunFetch, RemoteRunDestination, RemoteInputFiles, RemoteFileMapping, } from "./agent-remote-run";
 export { readWorkerAgentResponse } from "./agent-call";
 export { streamManagedAgentSessionRun } from "./agent-session-stream";
 export type AgentChildRunSession = (operation: string, body: unknown, traceContext?: TraceContext) => Promise<Response>;
@@ -12,9 +13,11 @@ export declare class AgentRunHost {
     private readonly executions;
     private readonly work;
     private closed;
+    private readonly shutdown;
     constructor(host: {
         session: AgentChildRunSession;
         remoteFetch?(destination: RemoteRunDestination, path: string, init?: RequestInit): Promise<Response>;
+        transferRemoteInputs?(destination: RemoteRunDestination, files: RemoteInputFiles, scope: StudioArtifactScope | undefined, signal: AbortSignal): Promise<RemoteFileMapping>;
         register(run: AgentChildRun): Promise<string>;
         invoke(run: AgentChildRun, signal: AbortSignal, continuation?: TraceContinuation, inboxExecution?: AgentSessionInboxExecution): Promise<{
             response: Response;
@@ -44,6 +47,8 @@ export declare class AgentRunHost {
         artifacts?: Array<StudioArtifactInputFile & {
             id: string;
         }>;
+        artifactScope?: StudioArtifactScope;
+        signal?: AbortSignal;
         traceContext?: TraceContext;
     }): Promise<Response>;
     startRemote(input: {
@@ -54,6 +59,8 @@ export declare class AgentRunHost {
         artifacts?: Array<StudioArtifactInputFile & {
             id: string;
         }>;
+        artifactScope?: StudioArtifactScope;
+        signal?: AbortSignal;
         traceContext?: TraceContext;
     }): Promise<Response>;
     dispatch(run: AgentChildRun, inboxExecution?: AgentSessionInboxExecution): void;

package/dist/agent-run-host.js

@@ -1,7 +1,7 @@
 import { submitRemoteRun, observeRemoteRun, cancelRemoteRun, } from "./agent-remote-run.js";
 import { z } from "zod";
 import { Result } from "better-result";
-import { agentChildRunSchema, agentChildRunListResultSchema, agentChildRunStartResultSchema, } from "@gea-ai/contract/agent-worker-tools";
+import { agentChildRunSchema, getAgentCallFileIds, agentChildRunListResultSchema, agentChildRunStartResultSchema, } from "@gea-ai/contract/agent-worker-tools";
 import { readWorkerAgentResponse } from "./agent-call.js";
 export { readWorkerAgentResponse } from "./agent-call.js";
 export { streamManagedAgentSessionRun } from "./agent-session-stream.js";
@@ -11,6 +11,7 @@ export class AgentRunHost {
     executions = new Map();
     work = new Set();
     closed = false;
+    shutdown = new AbortController();
     constructor(host) {
         this.host = host;
     }
@@ -54,7 +55,8 @@ export class AgentRunHost {
         }
         if (this.closed)
             return new Response("Run dispatcher is stopping", { status: 503 });
-        const response = await this.host.session("start", input);
+        const { artifactScope: _artifactScope, signal: _signal, ...sessionInput } = input;
+        const response = await this.host.session("start", sessionInput);
         if (!response.ok)
             return response;
         const { run, scheduled } = agentChildRunStartResultSchema.parse(await response.json());
@@ -67,6 +69,10 @@ export class AgentRunHost {
     async startRemote(input) {
         if (this.closed || !this.host.remoteFetch)
             return new Response("Remote Agents API unavailable", { status: 503 });
+        if (getAgentCallFileIds(input.message).length &&
+            !this.host.transferRemoteInputs)
+            return Response.json({ error: "remote_artifact_transfer_unsupported" }, { status: 501 });
+        const { artifactScope: _artifactScope, signal: _signal, ...sessionInput } = input;
         const listed = await this.host.session("list", {});
         if (!listed.ok)
             return listed;
@@ -74,7 +80,7 @@ export class AgentRunHost {
         let reservationId;
         if (subagentConcurrencyVersion) {
             const reserved = await this.host.session("reserve", {
-                ...input,
+                ...sessionInput,
                 agentKey: input.destination.agentId,
             });
             if (!reserved.ok)
@@ -99,7 +105,16 @@ export class AgentRunHost {
             }
         }
         const fetch = (path, init) => this.host.remoteFetch(input.destination, path, init);
-        const admission = await submitRemoteRun(fetch, input);
+        const admission = await submitRemoteRun(fetch, input, {
+            signal: AbortSignal.any([
+                this.shutdown.signal,
+                AbortSignal.timeout(120_000),
+                ...(input.signal ? [input.signal] : []),
+            ]),
+            transferFiles: this.host.transferRemoteInputs
+                ? (files, signal) => this.host.transferRemoteInputs(input.destination, files, input.artifactScope, signal)
+                : undefined,
+        });
         return admission.match({
             err: async (error) => {
                 if (reservationId && error.definitive) {
@@ -130,7 +145,7 @@ export class AgentRunHost {
                         traceContext: input.traceContext,
                     }
                     : {
-                        ...input,
+                        ...sessionInput,
                         id: receipt.runId,
                         sessionId: receipt.sessionId,
                         agentKey: input.destination.agentId,
@@ -305,6 +320,7 @@ export class AgentRunHost {
     }
     async close() {
         this.closed = true;
+        this.shutdown.abort();
         for (const cancellation of this.executions.values())
             cancellation.abort();
         while (this.work.size)

package/dist/index.d.ts

@@ -10,7 +10,7 @@ export type { AgentEngine } from "./agent-core-engine";
 import type { AgentTracing } from "@gea-ai/contract/agent-tracing";
 export type { AgentTracing, AgentTraceSpan, } from "@gea-ai/contract/agent-tracing";
 import { type AgentContextStrategy } from "./context";
-import { type AgentReference } from "@gea-ai/contract/agent-references";
+import { remoteAgentDeclarationSchema, type AgentReference } from "@gea-ai/contract/agent-references";
 export type { AgentContextStrategy, AgentContextRuntime, AgentContextPrepareStepEvent, AgentContextStepEndEvent, AgentContextEndEvent, } from "./context";
 import type { ComputerCommands } from "@gea-ai/contract/computer-commands";
 import type { AgentArtifacts, AgentArtifactScopeResolver } from "@gea-ai/contract/studio-artifacts";
@@ -447,15 +447,18 @@ export declare function defineAgentReference<const TSlug extends WorkerAgentSlug
     description: string;
     slug: TSlug;
 };
-export type DefineRemoteAgentInput = {
-    agentId: string;
-    description: string;
-};
-/** Invoke an exported Agent in the current Project using the caller's authority and environment. */
+export type DefineRemoteAgentInput = Omit<z.input<typeof remoteAgentDeclarationSchema>, "type">;
+/** Invoke a fixed Agent ID. Omitted transport options inherit the Host binding;
+ * auth.bearerTokenEnv names a Host-only credential for explicit remote authority. */
 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

@@ -340,7 +340,8 @@ export function defineAgentReference(input) {
     });
     return { ...reference, slug: input.slug };
 }
-/** Invoke an exported Agent in the current Project using the caller's authority and environment. */
+/** Invoke a fixed Agent ID. Omitted transport options inherit the Host binding;
+ * auth.bearerTokenEnv names a Host-only credential for explicit remote authority. */
 export function defineRemoteAgent(input) {
     return remoteAgentDeclarationSchema.parse({ ...input, type: "remote" });
 }

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const agentSdkVersion = "0.1.261003-alpha.1";
+export declare const agentSdkVersion = "0.1.261004-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.261003-alpha.1";
+export const agentSdkVersion = "0.1.261004-alpha.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gea-ai/agent-sdk",
-  "version": "0.1.261003-alpha.1",
+  "version": "0.1.261004-alpha.0",
   "private": false,
   "homepage": "https://musegea.com/developers",
   "license": "Apache-2.0",
@@ -119,7 +119,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.261003-alpha.1",
+    "@gea-ai/contract": "0.1.261004-alpha.0",
     "@opentelemetry/api": "1.9.1",
     "@opentelemetry/context-async-hooks": "2.10.0",
     "@opentelemetry/core": "2.10.0",