@gea-ai/agent-sdk 0.1.261012-alpha.0 → 0.1.261016-alpha.0

package/dist/agent-ai.d.ts

@@ -6,4 +6,5 @@ export declare function createAgentAI(input: {
     modelId: string;
     signal(): AbortSignal;
     recordUsage(entry: AgentContextUsage): void;
+    startUsage?(callId: string, model: string): Promise<void>;
 }): AgentAI;

package/dist/agent-ai.js

@@ -29,9 +29,9 @@ export function createAgentAI(input) {
     };
     // The binding owns the model span. Forward the active SDK parent so generic
     // native calls and Agent-owned calls share the same trace without two model spans.
-    const observe = (options, result) => result.then((value) => {
+    const observe = (options, result, callId) => result.then((value) => {
         input.recordUsage({
-            callId: value.callId,
+            callId: callId ?? value.callId,
             model: value.model,
             label: options.label,
             usage: value.usage,
@@ -40,6 +40,7 @@ export function createAgentAI(input) {
         return value;
     }, (error) => {
         input.recordUsage({
+            callId,
             model: options.model,
             label: options.label,
             usage: null,
@@ -53,20 +54,26 @@ export function createAgentAI(input) {
     return {
         async generateText(options) {
             const parameters = prepare(options);
+            const callId = input.startUsage ? crypto.randomUUID() : undefined;
+            if (callId)
+                await input.startUsage(callId, parameters.model);
             return observe(parameters, (async () => {
                 if (!input.binding.generateText)
                     throw new Error("AI generation binding is unavailable. Update Worker Runtime.");
                 return input.binding.generateText(parameters);
-            })());
+            })(), callId);
         },
         async streamText(options) {
             const parameters = prepare(options);
+            const callId = input.startUsage ? crypto.randomUUID() : undefined;
+            if (callId)
+                await input.startUsage(callId, parameters.model);
             const opened = (async () => {
                 if (!input.binding.streamText)
                     throw new Error("AI generation binding is unavailable. Update Worker Runtime.");
                 return input.binding.streamText(parameters);
             })();
-            const result = observe(parameters, opened.then((call) => call.result));
+            const result = observe(parameters, opened.then((call) => call.result), callId);
             result.catch(() => { });
             const call = await opened;
             return { stream: call.stream, result };

package/dist/agent-call.d.ts

@@ -1,12 +1,12 @@
 import { z } from "zod";
 import { type AgentWorkerToolInitialization } from "@gea-ai/contract/agent-worker-tools";
 import type { AgentHostBinding } from "./agent-worker.js";
-import type { StudioArtifactScope } from "@gea-ai/contract/studio-artifacts";
+import type { BuilderArtifactScope } from "@gea-ai/contract/builder-artifacts";
 /** Fresh Sessions keep the declared-target rule. A resume only needs sessionId. */
 export declare function workerAgentToolInputSchema(input: {
     agents: NonNullable<AgentWorkerToolInitialization["agents"]>;
     canCopy?: boolean;
-    artifactScope?: StudioArtifactScope;
+    artifactScope?: BuilderArtifactScope;
 }): z.ZodObject<{
     sessionId: z.ZodOptional<z.ZodUUID>;
     target: z.ZodOptional<z.ZodString>;
@@ -31,8 +31,9 @@ export declare function workerAgentToolInputSchema(input: {
 export declare function createWorkerAgentTool(input: {
     agents: NonNullable<AgentWorkerToolInitialization["agents"]>;
     host: AgentHostBinding;
+    runId?: string;
     canCopy?: boolean;
-    artifactScope?: StudioArtifactScope;
+    artifactScope?: BuilderArtifactScope;
 }): ({
     deferLoading?: boolean;
     title?: string;
@@ -146,6 +147,16 @@ export declare function createWorkerAgentTool(input: {
         } | {
             error: string;
             message: string;
+        } | {
+            code: "UPSTREAM_HTTP_ERROR";
+            status: number;
+            message: string;
+        } | {
+            code: string;
+            reason: string;
+            status: number;
+            requestId?: string | undefined;
+            message: string;
         }>;
     }) => import("@ai-sdk/provider-utils").ToolResultOutput | PromiseLike<import("@ai-sdk/provider-utils").ToolResultOutput>) | undefined;
 } & {
@@ -168,6 +179,16 @@ export declare function createWorkerAgentTool(input: {
     } | {
         error: string;
         message: string;
+    } | {
+        code: "UPSTREAM_HTTP_ERROR";
+        status: number;
+        message: string;
+    } | {
+        code: string;
+        reason: string;
+        status: number;
+        requestId?: string | undefined;
+        message: string;
     }> | undefined;
     execute: import("ai").ToolExecuteFunction<{
         sessionId?: string | undefined;
@@ -207,6 +228,16 @@ export declare function createWorkerAgentTool(input: {
     } | {
         error: string;
         message: string;
+    } | {
+        code: "UPSTREAM_HTTP_ERROR";
+        status: number;
+        message: string;
+    } | {
+        code: string;
+        reason: string;
+        status: number;
+        requestId?: string | undefined;
+        message: string;
     }, NoInfer<import("@ai-sdk/provider-utils").Context>>;
 } & {
     description?: string | ((options: {
@@ -281,6 +312,16 @@ export declare function createWorkerAgentTool(input: {
     } | {
         error: string;
         message: string;
+    } | {
+        code: "UPSTREAM_HTTP_ERROR";
+        status: number;
+        message: string;
+    } | {
+        code: string;
+        reason: string;
+        status: number;
+        requestId?: string | undefined;
+        message: string;
     }, NoInfer<import("@ai-sdk/provider-utils").Context>>;
 }) | ({
     deferLoading?: boolean;
@@ -395,6 +436,16 @@ export declare function createWorkerAgentTool(input: {
         } | {
             error: string;
             message: string;
+        } | {
+            code: "UPSTREAM_HTTP_ERROR";
+            status: number;
+            message: string;
+        } | {
+            code: string;
+            reason: string;
+            status: number;
+            requestId?: string | undefined;
+            message: string;
         }>;
     }) => import("@ai-sdk/provider-utils").ToolResultOutput | PromiseLike<import("@ai-sdk/provider-utils").ToolResultOutput>) | undefined;
 } & {
@@ -417,6 +468,16 @@ export declare function createWorkerAgentTool(input: {
     } | {
         error: string;
         message: string;
+    } | {
+        code: "UPSTREAM_HTTP_ERROR";
+        status: number;
+        message: string;
+    } | {
+        code: string;
+        reason: string;
+        status: number;
+        requestId?: string | undefined;
+        message: string;
     }> | undefined;
     execute: import("ai").ToolExecuteFunction<{
         sessionId?: string | undefined;
@@ -456,6 +517,16 @@ export declare function createWorkerAgentTool(input: {
     } | {
         error: string;
         message: string;
+    } | {
+        code: "UPSTREAM_HTTP_ERROR";
+        status: number;
+        message: string;
+    } | {
+        code: string;
+        reason: string;
+        status: number;
+        requestId?: string | undefined;
+        message: string;
     }, NoInfer<import("@ai-sdk/provider-utils").Context>>;
 } & {
     description?: string | ((options: {
@@ -530,6 +601,16 @@ export declare function createWorkerAgentTool(input: {
     } | {
         error: string;
         message: string;
+    } | {
+        code: "UPSTREAM_HTTP_ERROR";
+        status: number;
+        message: string;
+    } | {
+        code: string;
+        reason: string;
+        status: number;
+        requestId?: string | undefined;
+        message: string;
     }, NoInfer<import("@ai-sdk/provider-utils").Context>>;
 }) | ({
     deferLoading?: boolean;
@@ -644,6 +725,16 @@ export declare function createWorkerAgentTool(input: {
         } | {
             error: string;
             message: string;
+        } | {
+            code: "UPSTREAM_HTTP_ERROR";
+            status: number;
+            message: string;
+        } | {
+            code: string;
+            reason: string;
+            status: number;
+            requestId?: string | undefined;
+            message: string;
         }>;
     }) => import("@ai-sdk/provider-utils").ToolResultOutput | PromiseLike<import("@ai-sdk/provider-utils").ToolResultOutput>) | undefined;
 } & {
@@ -666,6 +757,16 @@ export declare function createWorkerAgentTool(input: {
     } | {
         error: string;
         message: string;
+    } | {
+        code: "UPSTREAM_HTTP_ERROR";
+        status: number;
+        message: string;
+    } | {
+        code: string;
+        reason: string;
+        status: number;
+        requestId?: string | undefined;
+        message: string;
     }> | undefined;
     execute: import("ai").ToolExecuteFunction<{
         sessionId?: string | undefined;
@@ -705,6 +806,16 @@ export declare function createWorkerAgentTool(input: {
     } | {
         error: string;
         message: string;
+    } | {
+        code: "UPSTREAM_HTTP_ERROR";
+        status: number;
+        message: string;
+    } | {
+        code: string;
+        reason: string;
+        status: number;
+        requestId?: string | undefined;
+        message: string;
     }, NoInfer<import("@ai-sdk/provider-utils").Context>>;
 } & {
     type: 'provider';
@@ -755,6 +866,16 @@ export declare function createWorkerAgentTool(input: {
     } | {
         error: string;
         message: string;
+    } | {
+        code: "UPSTREAM_HTTP_ERROR";
+        status: number;
+        message: string;
+    } | {
+        code: string;
+        reason: string;
+        status: number;
+        requestId?: string | undefined;
+        message: string;
     }, NoInfer<import("@ai-sdk/provider-utils").Context>>;
 }) | ({
     deferLoading?: boolean;
@@ -869,6 +990,16 @@ export declare function createWorkerAgentTool(input: {
         } | {
             error: string;
             message: string;
+        } | {
+            code: "UPSTREAM_HTTP_ERROR";
+            status: number;
+            message: string;
+        } | {
+            code: string;
+            reason: string;
+            status: number;
+            requestId?: string | undefined;
+            message: string;
         }>;
     }) => import("@ai-sdk/provider-utils").ToolResultOutput | PromiseLike<import("@ai-sdk/provider-utils").ToolResultOutput>) | undefined;
 } & {
@@ -891,6 +1022,16 @@ export declare function createWorkerAgentTool(input: {
     } | {
         error: string;
         message: string;
+    } | {
+        code: "UPSTREAM_HTTP_ERROR";
+        status: number;
+        message: string;
+    } | {
+        code: string;
+        reason: string;
+        status: number;
+        requestId?: string | undefined;
+        message: string;
     }> | undefined;
     execute: import("ai").ToolExecuteFunction<{
         sessionId?: string | undefined;
@@ -930,6 +1071,16 @@ export declare function createWorkerAgentTool(input: {
     } | {
         error: string;
         message: string;
+    } | {
+        code: "UPSTREAM_HTTP_ERROR";
+        status: number;
+        message: string;
+    } | {
+        code: string;
+        reason: string;
+        status: number;
+        requestId?: string | undefined;
+        message: string;
     }, NoInfer<import("@ai-sdk/provider-utils").Context>>;
 } & {
     type: 'provider';
@@ -980,6 +1131,16 @@ export declare function createWorkerAgentTool(input: {
     } | {
         error: string;
         message: string;
+    } | {
+        code: "UPSTREAM_HTTP_ERROR";
+        status: number;
+        message: string;
+    } | {
+        code: string;
+        reason: string;
+        status: number;
+        requestId?: string | undefined;
+        message: string;
     }, NoInfer<import("@ai-sdk/provider-utils").Context>>;
 });
 export declare function createWorkerRunCancelTool({ host, }: {
@@ -1251,7 +1412,18 @@ export declare function createWorkerRunCancelTool({ host, }: {
         status: "abort_requested" | "not_running";
     }, NoInfer<import("@ai-sdk/provider-utils").Context>>;
 });
+export declare function readChildHttpRejection(response: Response): Promise<{
+    body: unknown;
+    bodyPrefix: string;
+    bodyState: string;
+    logReason: string;
+    code: string;
+    reason: string;
+    requestId: string | undefined;
+}>;
 export declare function readWorkerAgentResponse(response: Response, options?: {
+    runId?: string;
+    requestPath?: string;
     persistedSessionWaiting?: () => Promise<boolean>;
 }): Promise<{
     status: "completed" | "suspended";

package/dist/agent-call.js

@@ -59,9 +59,9 @@ export function createWorkerAgentTool(input) {
                 signal: options.abortSignal,
             });
             if (!response.ok) {
-                const body = await Result.tryPromise(() => response.json());
-                if (body.isOk()) {
-                    const value = body.value;
+                const rejection = await readChildHttpRejection(response);
+                if (rejection.body !== undefined) {
+                    const value = rejection.body;
                     const limit = agentSubagentConcurrencyErrorSchema.safeParse(value);
                     if (limit.success)
                         return {
@@ -95,25 +95,14 @@ export function createWorkerAgentTool(input) {
                             error: "child_busy",
                             message: "This child Session has unfinished work. Wait for its Run before continuing the Session.",
                         };
-                    if (response.status === 403) {
-                        const rejection = z
-                            .object({
-                            error: z
-                                .string()
-                                .max(80)
-                                .regex(/^[A-Za-z0-9_.-]+$/),
-                        })
-                            .safeParse(value);
-                        if (rejection.success) {
-                            console.error("Child run rejected", {
-                                status: 403,
-                                error: rejection.data.error,
-                            });
-                            throw new Error(`Agent invocation was rejected (403 ${rejection.data.error}).`);
-                        }
-                    }
                 }
-                throw new Error(`Agent invocation was rejected (${response.status}).`);
+                logChildHttpRejection(response, rejection, {
+                    path: "/internal/agent-worker-host/v1/agents/runs",
+                    ...(input.runId ? { runId: input.runId } : {}),
+                });
+                // Return the rejection instead of throwing. A thrown tool error is
+                // replaced by a generic execution message before it reaches the model.
+                return agentToolRejectionResult(response.status, rejection);
             }
             return agentRunCallResultSchema.parse(await response.json());
         },
@@ -149,18 +138,202 @@ function childDiagnosticIdentifier(value) {
         ? value
         : undefined;
 }
+// Only fixed protocol vocabulary may appear outside the shape-redacted prefix.
+// Identifier-shaped strings can still be tokens, so a character regex is insufficient.
+const childHttpLogReasonSchema = z.enum([
+    "UPSTREAM_HTTP_ERROR",
+    "BAD_REQUEST",
+    "UNAUTHORIZED",
+    "FORBIDDEN",
+    "NOT_FOUND",
+    "CONFLICT",
+    "NESTED_RESUME_REQUIRES_NEW_SDK",
+    "CHILD_SESSION_AUTHORITY_MISMATCH",
+    "invalid_request",
+    "invalid_child_request",
+    "invalid_json",
+    "unknown_child_session",
+    "child_busy",
+    "session_identity_conflict",
+    "subagent_concurrency_limit",
+    "runtime_unavailable",
+    "empty_error_response",
+    "invalid_error_response",
+    "unreadable_error_response",
+    "error_response_too_large",
+    "error_response_timeout",
+]);
+// Both admission and dispatch consume untrusted HTTP failures. Bound diagnostics
+// independently of a streaming Run: a stalled error body must never hold its slot.
+export async function readChildHttpRejection(response) {
+    let bodyPrefix = "";
+    let reason = "empty_error_response";
+    let body;
+    if (response.body) {
+        reason = "unreadable_error_response";
+        const reader = response.body.getReader();
+        let timer;
+        const read = await Result.tryPromise(() => Promise.race([
+            (async () => {
+                const chunks = [];
+                let size = 0;
+                let reads = 0;
+                while (true) {
+                    if (++reads > 8192) {
+                        reason = "error_response_too_large";
+                        return undefined;
+                    }
+                    const next = await reader.read();
+                    if (next.done)
+                        break;
+                    // Shape-only redaction: arbitrary error text may contain credentials or
+                    // user content under any key. Never guess which strings are safe.
+                    const prefix = next.value.subarray(0, Math.max(0, 512 - bodyPrefix.length));
+                    bodyPrefix += Array.from(prefix, (byte) => [123, 125, 91, 93, 34, 58, 44, 32].includes(byte)
+                        ? String.fromCharCode(byte)
+                        : "*").join("");
+                    size += next.value.byteLength;
+                    if (size > 8192) {
+                        reason = "error_response_too_large";
+                        return undefined;
+                    }
+                    chunks.push(next.value);
+                }
+                if (!size) {
+                    reason = "empty_error_response";
+                    return undefined;
+                }
+                reason = "invalid_error_response";
+                const bytes = new Uint8Array(size);
+                let offset = 0;
+                for (const chunk of chunks) {
+                    bytes.set(chunk, offset);
+                    offset += chunk.byteLength;
+                }
+                const parsed = JSON.parse(new TextDecoder().decode(bytes));
+                reason = "complete";
+                return parsed;
+            })(),
+            new Promise((resolve) => {
+                timer = setTimeout(() => {
+                    reason = "error_response_timeout";
+                    resolve(undefined);
+                }, 1000);
+            }),
+        ]));
+        clearTimeout(timer);
+        // Do not await a peer's cancellation acknowledgement on the rejection path.
+        void reader.cancel().catch(() => { });
+        reader.releaseLock();
+        if (read.isOk())
+            body = read.value;
+    }
+    const bodyState = reason;
+    const identifier = z
+        .string()
+        .max(80)
+        .regex(/^[A-Za-z0-9_.-]+$/);
+    const parsed = z
+        .object({
+        code: identifier.optional(),
+        requestId: z.uuid().optional(),
+        reason: z.string().max(1000).optional(),
+        error: z
+            .union([
+            identifier,
+            z.object({
+                code: identifier,
+                reason: z.string().max(1000).optional(),
+            }),
+        ])
+            .optional(),
+    })
+        .safeParse(body);
+    if (parsed.success) {
+        const error = parsed.data.error;
+        const code = typeof error === "string" ? error : (error?.code ?? parsed.data.code);
+        const detail = (typeof error === "object" ? error.reason : undefined) ??
+            parsed.data.reason;
+        if (code || detail)
+            return {
+                body,
+                bodyPrefix,
+                bodyState,
+                logReason: childHttpLogReasonSchema.safeParse(detail).data ??
+                    childHttpLogReasonSchema.safeParse(code).data ??
+                    "unclassified_upstream_error",
+                code: code ?? "UPSTREAM_HTTP_ERROR",
+                reason: detail ?? code,
+                requestId: parsed.data.requestId,
+            };
+    }
+    return {
+        body,
+        bodyPrefix,
+        bodyState,
+        logReason: reason === "complete" ? "invalid_error_response" : reason,
+        code: "UPSTREAM_HTTP_ERROR",
+        reason: reason === "complete" ? "invalid_error_response" : reason,
+        requestId: undefined,
+    };
+}
+function agentToolRejectionResult(status, rejection) {
+    const recognized = rejection.bodyState === "complete" &&
+        !(rejection.code === "UPSTREAM_HTTP_ERROR" &&
+            rejection.reason === "invalid_error_response");
+    if (!recognized) {
+        return {
+            code: "UPSTREAM_HTTP_ERROR",
+            status,
+            message: `Agent invocation was rejected (${status}). The server did not return a readable error.`,
+        };
+    }
+    const request = rejection.requestId
+        ? ` (request ${rejection.requestId})`
+        : "";
+    return {
+        code: rejection.code,
+        reason: rejection.reason,
+        status,
+        ...(rejection.requestId ? { requestId: rejection.requestId } : {}),
+        message: `Agent invocation was rejected (${status}) ${rejection.code}: ${rejection.reason}${request}`,
+    };
+}
+function logChildHttpRejection(response, rejection, identity) {
+    const requestId = rejection.requestId ??
+        z.uuid().safeParse(response.headers.get("x-gea-request-id")).data;
+    // JSON stays readable in native console forwarding as well as Node/Nitro.
+    console.error(JSON.stringify({
+        event: "agent.child_http.rejected",
+        ...identity,
+        status: response.status,
+        bodyState: rejection.bodyState,
+        reason: rejection.logReason,
+        bodyPrefix: rejection.bodyPrefix,
+        ...(requestId ? { requestId } : {}),
+    }));
+}
 export async function readWorkerAgentResponse(response, options) {
     if (response.status === 409 &&
         response.headers.get("x-gea-session-execution") === "already-started") {
-        await response.body?.cancel();
+        void response.body?.cancel().catch(() => { });
         return { status: "suspended", text: "" };
     }
     if (!response.ok || !response.body) {
-        await response.body?.cancel();
+        const rejection = await readChildHttpRejection(response);
+        logChildHttpRejection(response, rejection, {
+            path: response.url
+                ? new URL(response.url).pathname
+                : (options?.requestPath?.split(/[?#]/, 1)[0] ?? "unknown"),
+            ...(options?.runId ? { runId: options.runId } : {}),
+        });
         throw new AgentChildRunResponseError({
             code: "child_http_error",
             status: response.status,
-            message: `Child Agent invocation failed (${response.status}).`,
+            data: {
+                reason: rejection.logReason,
+            },
+            message: `Child Agent invocation failed (${response.status}) ${rejection.code}: ${rejection.reason}`,
         });
     }
     let text = "";