@gea-ai/agent-sdk 0.1.260920-alpha.3 → 0.1.260922-alpha.0

package/dist/agent-call.d.ts

@@ -103,12 +103,44 @@ export declare function createWorkerAgentTool(input: {
         output: NoInfer<{
             runId: string;
             sessionId: string;
+        } | {
+            error: "subagent_concurrency_limit";
+            limit: number;
+            active: number;
+            pendingRunIds: string[];
+            pendingAdmissions: number;
+            message: string;
+        } | {
+            error: "remote_admission_unknown" | "remote_attachment_unconfirmed" | "remote_run_rejected";
+            reservationId: string;
+            runId?: string | undefined;
+            sessionId?: string | undefined;
+            message: string;
+        } | {
+            error: "child_busy";
+            message: string;
         }>;
     }) => import("@ai-sdk/provider-utils").ToolResultOutput | PromiseLike<import("@ai-sdk/provider-utils").ToolResultOutput>) | undefined;
 } & {
     outputSchema?: import("ai").FlexibleSchema<{
         runId: string;
         sessionId: string;
+    } | {
+        error: "subagent_concurrency_limit";
+        limit: number;
+        active: number;
+        pendingRunIds: string[];
+        pendingAdmissions: number;
+        message: string;
+    } | {
+        error: "remote_admission_unknown" | "remote_attachment_unconfirmed" | "remote_run_rejected";
+        reservationId: string;
+        runId?: string | undefined;
+        sessionId?: string | undefined;
+        message: string;
+    } | {
+        error: "child_busy";
+        message: string;
     }> | undefined;
     execute: import("ai").ToolExecuteFunction<{
         sessionId?: string | undefined;
@@ -132,6 +164,22 @@ export declare function createWorkerAgentTool(input: {
     }, {
         runId: string;
         sessionId: string;
+    } | {
+        error: "subagent_concurrency_limit";
+        limit: number;
+        active: number;
+        pendingRunIds: string[];
+        pendingAdmissions: number;
+        message: string;
+    } | {
+        error: "remote_admission_unknown" | "remote_attachment_unconfirmed" | "remote_run_rejected";
+        reservationId: string;
+        runId?: string | undefined;
+        sessionId?: string | undefined;
+        message: string;
+    } | {
+        error: "child_busy";
+        message: string;
     }, NoInfer<import("@ai-sdk/provider-utils").Context>>;
 } & {
     description?: string | ((options: {
@@ -190,6 +238,22 @@ export declare function createWorkerAgentTool(input: {
     }, {
         runId: string;
         sessionId: string;
+    } | {
+        error: "subagent_concurrency_limit";
+        limit: number;
+        active: number;
+        pendingRunIds: string[];
+        pendingAdmissions: number;
+        message: string;
+    } | {
+        error: "remote_admission_unknown" | "remote_attachment_unconfirmed" | "remote_run_rejected";
+        reservationId: string;
+        runId?: string | undefined;
+        sessionId?: string | undefined;
+        message: string;
+    } | {
+        error: "child_busy";
+        message: string;
     }, NoInfer<import("@ai-sdk/provider-utils").Context>>;
 }) | ({
     title?: string;
@@ -287,12 +351,44 @@ export declare function createWorkerAgentTool(input: {
         output: NoInfer<{
             runId: string;
             sessionId: string;
+        } | {
+            error: "subagent_concurrency_limit";
+            limit: number;
+            active: number;
+            pendingRunIds: string[];
+            pendingAdmissions: number;
+            message: string;
+        } | {
+            error: "remote_admission_unknown" | "remote_attachment_unconfirmed" | "remote_run_rejected";
+            reservationId: string;
+            runId?: string | undefined;
+            sessionId?: string | undefined;
+            message: string;
+        } | {
+            error: "child_busy";
+            message: string;
         }>;
     }) => import("@ai-sdk/provider-utils").ToolResultOutput | PromiseLike<import("@ai-sdk/provider-utils").ToolResultOutput>) | undefined;
 } & {
     outputSchema?: import("ai").FlexibleSchema<{
         runId: string;
         sessionId: string;
+    } | {
+        error: "subagent_concurrency_limit";
+        limit: number;
+        active: number;
+        pendingRunIds: string[];
+        pendingAdmissions: number;
+        message: string;
+    } | {
+        error: "remote_admission_unknown" | "remote_attachment_unconfirmed" | "remote_run_rejected";
+        reservationId: string;
+        runId?: string | undefined;
+        sessionId?: string | undefined;
+        message: string;
+    } | {
+        error: "child_busy";
+        message: string;
     }> | undefined;
     execute: import("ai").ToolExecuteFunction<{
         sessionId?: string | undefined;
@@ -316,6 +412,22 @@ export declare function createWorkerAgentTool(input: {
     }, {
         runId: string;
         sessionId: string;
+    } | {
+        error: "subagent_concurrency_limit";
+        limit: number;
+        active: number;
+        pendingRunIds: string[];
+        pendingAdmissions: number;
+        message: string;
+    } | {
+        error: "remote_admission_unknown" | "remote_attachment_unconfirmed" | "remote_run_rejected";
+        reservationId: string;
+        runId?: string | undefined;
+        sessionId?: string | undefined;
+        message: string;
+    } | {
+        error: "child_busy";
+        message: string;
     }, NoInfer<import("@ai-sdk/provider-utils").Context>>;
 } & {
     description?: string | ((options: {
@@ -374,6 +486,22 @@ export declare function createWorkerAgentTool(input: {
     }, {
         runId: string;
         sessionId: string;
+    } | {
+        error: "subagent_concurrency_limit";
+        limit: number;
+        active: number;
+        pendingRunIds: string[];
+        pendingAdmissions: number;
+        message: string;
+    } | {
+        error: "remote_admission_unknown" | "remote_attachment_unconfirmed" | "remote_run_rejected";
+        reservationId: string;
+        runId?: string | undefined;
+        sessionId?: string | undefined;
+        message: string;
+    } | {
+        error: "child_busy";
+        message: string;
     }, NoInfer<import("@ai-sdk/provider-utils").Context>>;
 }) | ({
     title?: string;
@@ -471,12 +599,44 @@ export declare function createWorkerAgentTool(input: {
         output: NoInfer<{
             runId: string;
             sessionId: string;
+        } | {
+            error: "subagent_concurrency_limit";
+            limit: number;
+            active: number;
+            pendingRunIds: string[];
+            pendingAdmissions: number;
+            message: string;
+        } | {
+            error: "remote_admission_unknown" | "remote_attachment_unconfirmed" | "remote_run_rejected";
+            reservationId: string;
+            runId?: string | undefined;
+            sessionId?: string | undefined;
+            message: string;
+        } | {
+            error: "child_busy";
+            message: string;
         }>;
     }) => import("@ai-sdk/provider-utils").ToolResultOutput | PromiseLike<import("@ai-sdk/provider-utils").ToolResultOutput>) | undefined;
 } & {
     outputSchema?: import("ai").FlexibleSchema<{
         runId: string;
         sessionId: string;
+    } | {
+        error: "subagent_concurrency_limit";
+        limit: number;
+        active: number;
+        pendingRunIds: string[];
+        pendingAdmissions: number;
+        message: string;
+    } | {
+        error: "remote_admission_unknown" | "remote_attachment_unconfirmed" | "remote_run_rejected";
+        reservationId: string;
+        runId?: string | undefined;
+        sessionId?: string | undefined;
+        message: string;
+    } | {
+        error: "child_busy";
+        message: string;
     }> | undefined;
     execute: import("ai").ToolExecuteFunction<{
         sessionId?: string | undefined;
@@ -500,6 +660,22 @@ export declare function createWorkerAgentTool(input: {
     }, {
         runId: string;
         sessionId: string;
+    } | {
+        error: "subagent_concurrency_limit";
+        limit: number;
+        active: number;
+        pendingRunIds: string[];
+        pendingAdmissions: number;
+        message: string;
+    } | {
+        error: "remote_admission_unknown" | "remote_attachment_unconfirmed" | "remote_run_rejected";
+        reservationId: string;
+        runId?: string | undefined;
+        sessionId?: string | undefined;
+        message: string;
+    } | {
+        error: "child_busy";
+        message: string;
     }, NoInfer<import("@ai-sdk/provider-utils").Context>>;
 } & {
     type: 'provider';
@@ -534,6 +710,22 @@ export declare function createWorkerAgentTool(input: {
     }, {
         runId: string;
         sessionId: string;
+    } | {
+        error: "subagent_concurrency_limit";
+        limit: number;
+        active: number;
+        pendingRunIds: string[];
+        pendingAdmissions: number;
+        message: string;
+    } | {
+        error: "remote_admission_unknown" | "remote_attachment_unconfirmed" | "remote_run_rejected";
+        reservationId: string;
+        runId?: string | undefined;
+        sessionId?: string | undefined;
+        message: string;
+    } | {
+        error: "child_busy";
+        message: string;
     }, NoInfer<import("@ai-sdk/provider-utils").Context>>;
 }) | ({
     title?: string;
@@ -631,12 +823,44 @@ export declare function createWorkerAgentTool(input: {
         output: NoInfer<{
             runId: string;
             sessionId: string;
+        } | {
+            error: "subagent_concurrency_limit";
+            limit: number;
+            active: number;
+            pendingRunIds: string[];
+            pendingAdmissions: number;
+            message: string;
+        } | {
+            error: "remote_admission_unknown" | "remote_attachment_unconfirmed" | "remote_run_rejected";
+            reservationId: string;
+            runId?: string | undefined;
+            sessionId?: string | undefined;
+            message: string;
+        } | {
+            error: "child_busy";
+            message: string;
         }>;
     }) => import("@ai-sdk/provider-utils").ToolResultOutput | PromiseLike<import("@ai-sdk/provider-utils").ToolResultOutput>) | undefined;
 } & {
     outputSchema?: import("ai").FlexibleSchema<{
         runId: string;
         sessionId: string;
+    } | {
+        error: "subagent_concurrency_limit";
+        limit: number;
+        active: number;
+        pendingRunIds: string[];
+        pendingAdmissions: number;
+        message: string;
+    } | {
+        error: "remote_admission_unknown" | "remote_attachment_unconfirmed" | "remote_run_rejected";
+        reservationId: string;
+        runId?: string | undefined;
+        sessionId?: string | undefined;
+        message: string;
+    } | {
+        error: "child_busy";
+        message: string;
     }> | undefined;
     execute: import("ai").ToolExecuteFunction<{
         sessionId?: string | undefined;
@@ -660,6 +884,22 @@ export declare function createWorkerAgentTool(input: {
     }, {
         runId: string;
         sessionId: string;
+    } | {
+        error: "subagent_concurrency_limit";
+        limit: number;
+        active: number;
+        pendingRunIds: string[];
+        pendingAdmissions: number;
+        message: string;
+    } | {
+        error: "remote_admission_unknown" | "remote_attachment_unconfirmed" | "remote_run_rejected";
+        reservationId: string;
+        runId?: string | undefined;
+        sessionId?: string | undefined;
+        message: string;
+    } | {
+        error: "child_busy";
+        message: string;
     }, NoInfer<import("@ai-sdk/provider-utils").Context>>;
 } & {
     type: 'provider';
@@ -694,6 +934,22 @@ export declare function createWorkerAgentTool(input: {
     }, {
         runId: string;
         sessionId: string;
+    } | {
+        error: "subagent_concurrency_limit";
+        limit: number;
+        active: number;
+        pendingRunIds: string[];
+        pendingAdmissions: number;
+        message: string;
+    } | {
+        error: "remote_admission_unknown" | "remote_attachment_unconfirmed" | "remote_run_rejected";
+        reservationId: string;
+        runId?: string | undefined;
+        sessionId?: string | undefined;
+        message: string;
+    } | {
+        error: "child_busy";
+        message: string;
     }, NoInfer<import("@ai-sdk/provider-utils").Context>>;
 });
 export declare function createWorkerRunCancelTool({ host, }: {

package/dist/agent-call.js

@@ -1,9 +1,9 @@
 import { agentHttpCancellationSchema } from "@gea-ai/contract/agent-http-api";
 import { z } from "zod";
-import { TaggedError } from "better-result";
+import { Result, TaggedError } from "better-result";
 import { parseJsonEventStream } from "@ai-sdk/provider-utils";
 import { tool, uiMessageChunkSchema } from "ai";
-import { agentCallInputSchema, agentCallTextMessageSchema, agentRunCallResultSchema, getAgentCallFileIds, } from "@gea-ai/contract/agent-worker-tools";
+import { agentSubagentConcurrencyErrorSchema, agentRemoteAdmissionErrorSchema, agentCallInputSchema, agentCallTextMessageSchema, agentRunCallResultSchema, getAgentCallFileIds, } from "@gea-ai/contract/agent-worker-tools";
 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) {
@@ -33,8 +33,37 @@ export function createWorkerAgentTool(input) {
                 }),
                 signal: options.abortSignal,
             });
-            if (!response.ok)
+            if (!response.ok) {
+                const body = await Result.tryPromise(() => response.json());
+                if (body.isOk()) {
+                    const value = body.value;
+                    const limit = agentSubagentConcurrencyErrorSchema.safeParse(value);
+                    if (limit.success)
+                        return {
+                            ...limit.data,
+                            message: limit.data.pendingRunIds.length
+                                ? "Subagent concurrency is full. Call runWait with pendingRunIds before retrying agent. Cancellation releases capacity only after terminal cleanup."
+                                : "Remote admissions still hold all capacity. Their outcomes must be resolved before retrying; do not resubmit an uncertain remote Run.",
+                        };
+                    const remote = agentRemoteAdmissionErrorSchema.safeParse(value);
+                    if (remote.success)
+                        return {
+                            ...remote.data,
+                            message: remote.data.error === "remote_run_rejected"
+                                ? "The remote Run was not admitted. Resolve the remote service failure before retrying."
+                                : "Remote Run admission is uncertain and its capacity is retained. Do not resubmit; reconcile the reservation with the remote service first.",
+                        };
+                    const busy = z
+                        .object({ error: z.literal("child_busy") })
+                        .safeParse(value);
+                    if (busy.success)
+                        return {
+                            error: "child_busy",
+                            message: "This child Session has unfinished work. Wait for its Run before continuing the Session.",
+                        };
+                }
                 throw new Error(`Agent invocation was rejected (${response.status}).`);
+            }
             return agentRunCallResultSchema.parse(await response.json());
         },
     });

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-remote-run.d.ts

@@ -1,3 +1,4 @@
+import { Result } from "better-result";
 import type { 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. */
@@ -5,6 +6,14 @@ export type RemoteRunFetch = (path: string, init?: RequestInit) => Promise<Respo
 export type RemoteRunDestination = Extract<AgentChildRunDestination, {
     type: "remote";
 }>;
+declare const RemoteRunAdmissionError_base: import("better-result").TaggedErrorClass<"RemoteRunAdmissionError", {
+    message: string;
+    cause: unknown;
+    sessionId?: string;
+    definitive: boolean;
+}>;
+declare class RemoteRunAdmissionError extends RemoteRunAdmissionError_base {
+}
 export declare function submitRemoteRun(fetch: RemoteRunFetch, input: {
     destination: RemoteRunDestination;
     sessionId?: string;
@@ -12,9 +21,10 @@ export declare function submitRemoteRun(fetch: RemoteRunFetch, input: {
     artifacts?: Array<StudioArtifactInputFile & {
         id: string;
     }>;
-}): Promise<{
+}): Promise<Result<{
     runId: string;
     sessionId: string;
-}>;
+}, RemoteRunAdmissionError>>;
 export declare function cancelRemoteRun(fetch: RemoteRunFetch, run: AgentChildRun): Promise<void>;
 export declare function observeRemoteRun(fetch: RemoteRunFetch, run: AgentChildRun, signal: AbortSignal): Promise<AgentChildRunOutcome>;
+export {};

package/dist/agent-remote-run.js

@@ -1,3 +1,4 @@
+import { Result, TaggedError } from "better-result";
 import { z } from "zod";
 import { agentHttpRunSchema, agentHttpMessageResourceSchema, } from "@gea-ai/contract/agent-http-api";
 const sessionSchema = z.object({ id: z.uuid() });
@@ -12,28 +13,44 @@ async function responseJson(response) {
     }
     return response.json();
 }
+class RemoteRunAdmissionError extends TaggedError("RemoteRunAdmissionError")() {
+}
 export async function submitRemoteRun(fetch, input) {
-    const sessionId = input.sessionId ??
-        sessionSchema.parse(await responseJson(await fetch("/sessions", {
-            method: "POST",
-            headers: { "content-type": "application/json" },
-            body: JSON.stringify({
-                agent_id: input.destination.agentId,
-                environment: input.destination.environment,
-            }),
-        }))).id;
-    // No automatic replay: a lost response does not prove that Run admission failed.
-    const run = agentHttpRunSchema.parse(await responseJson(await fetch(`/sessions/${sessionId}/runs`, {
-        method: "POST",
-        headers: { "content-type": "application/json" },
-        body: JSON.stringify({
-            input: input.message,
-            stream: false,
+    let sessionId = input.sessionId;
+    let submitting = false;
+    let rejected = false;
+    return Result.tryPromise({
+        try: async () => {
+            sessionId ??= sessionSchema.parse(await responseJson(await fetch("/sessions", {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({
+                    agent_id: input.destination.agentId,
+                    environment: input.destination.environment,
+                }),
+            }))).id;
+            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 }),
+            });
+            rejected = [400, 401, 403, 404, 405, 409, 413, 415, 422, 429].includes(response.status);
+            const run = agentHttpRunSchema.parse(await responseJson(response));
+            if (run.session_id !== sessionId)
+                throw new Error("Remote Run Session mismatch.");
+            return { runId: run.id, sessionId };
+        },
+        catch: (cause) => new RemoteRunAdmissionError({
+            cause,
+            sessionId,
+            definitive: !submitting || rejected,
+            message: !submitting || rejected
+                ? "Remote Run was not admitted."
+                : "Remote Run admission is unknown; do not resubmit.",
         }),
-    })));
-    if (run.session_id !== sessionId)
-        throw new Error("Remote Run Session mismatch.");
-    return { runId: run.id, sessionId };
+    });
 }
 export async function cancelRemoteRun(fetch, run) {
     const response = await fetch(`/runs/${run.id}/cancel`, { method: "POST" });