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

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

@@ -19,6 +19,19 @@ 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;
 } | {
@@ -43,19 +56,6 @@ 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-worker.d.ts

@@ -135,6 +135,7 @@ export type AgentToolRuntimeDefinition = {
             input: unknown;
             sdk: AgentToolRuntimeSdk;
         }): Promise<unknown>;
+        scriptRuntime?: ReturnType<typeof import("./script-tools").getScriptToolRuntime>;
         inputSchema: z.ZodType;
         toModelOutput?: import("./index").DefinedCustomTool["toModelOutput"];
     }>;

package/dist/agent-worker.js

@@ -1,3 +1,6 @@
+import { AGENT_WORKER_TOOL_METADATA_HEADER, AGENT_WORKER_TOOL_METADATA_VERSION, } from "@gea-ai/contract/agent-worker-tools";
+import { isAgentConnectorExposed } from "@gea-ai/contract/agent-packages";
+import { createCodeMode } from "./code-mode.js";
 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";
@@ -185,7 +188,11 @@ async function runPreparedConnectorAuthorization(input, environment) {
     }
     const [identityValue, initializationValue] = await Promise.all([
         requireHostJson(environment.IDENTITY, "/context"),
-        requireHostJson(environment.TOOLS, "/tools/initialize"),
+        requireHostJson(environment.TOOLS, "/tools/initialize", {
+            headers: {
+                [AGENT_WORKER_TOOL_METADATA_HEADER]: AGENT_WORKER_TOOL_METADATA_VERSION,
+            },
+        }),
     ]);
     const identity = agentToolIdentitySchema.parse(identityValue);
     const initialization = agentWorkerToolInitializationSchema.parse(initializationValue);
@@ -300,6 +307,7 @@ async function runPreparedAgent(runtime, agentKey, request, environment, startup
                     "content-type": "application/json",
                     "x-gea-agent-runs": "1",
                     "x-gea-session-inbox": "1",
+                    [AGENT_WORKER_TOOL_METADATA_HEADER]: AGENT_WORKER_TOOL_METADATA_VERSION,
                     ...Object.fromEntries([...request.headers.entries()].filter(([name]) => ["traceparent", "tracestate", "x-gea-request-id"].includes(name))),
                 },
                 body: JSON.stringify({ metadata: parsed.data.metadata }),
@@ -2185,6 +2193,7 @@ function createHostBackedAgentTools(input) {
             execute: async (toolInput, options) => await invokeHostTool({
                 host: input.host,
                 messages: options.messages,
+                signal: options.abortSignal,
                 toolCallId: options.toolCallId,
                 toolInput,
                 toolName: definition.hostToolName ?? name,
@@ -2251,7 +2260,7 @@ function createHostBackedAgentTools(input) {
             continue;
         }
         const declaredOperation = grant.definition.operations.find((operation) => operation.name === descriptor.operation);
-        if (!grant.exposeToModel ||
+        if (!isAgentConnectorExposed(grant, input.snapshot.codeMode) ||
             (grant.definition.runtime.type !== "mcp" && !declaredOperation)) {
             throw new Error("Agent Worker Connector operation is not granted.");
         }
@@ -2265,11 +2274,21 @@ function createHostBackedAgentTools(input) {
                 .join("\n"),
             inputSchema: jsonSchema(descriptor.inputSchema),
             ...(grant.definition.runtime.type === "mcp"
-                ? { toModelOutput: mcpToolModelOutput }
+                ? {
+                    toModelOutput: mcpToolModelOutput,
+                    ...(descriptor.outputSchema === undefined
+                        ? {}
+                        : {
+                            providerOptions: {
+                                gea: { mcpOutputSchema: descriptor.outputSchema },
+                            },
+                        }),
+                }
                 : {}),
             execute: async (toolInput, options) => await invokeHostTool({
                 host: input.host,
                 messages: options.messages,
+                signal: options.abortSignal,
                 toolCallId: options.toolCallId,
                 toolInput,
                 toolName,
@@ -3090,7 +3109,10 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
                 !!Object.keys(input.snapshot.agentReferences ?? {}).length ||
                 requiresToolInitialization(input.snapshot, input.hookRuntime)
                 ? startupTracing.withSpan("agent.startup.tools", () => requireHostJson(host, "/tools/initialize", {
-                    headers: { "x-gea-agent-runs": "1" },
+                    headers: {
+                        "x-gea-agent-runs": "1",
+                        [AGENT_WORKER_TOOL_METADATA_HEADER]: AGENT_WORKER_TOOL_METADATA_VERSION,
+                    },
                 }).then((value) => agentWorkerToolInitializationSchema.parse(value)))
                 : Promise.resolve(agentWorkerToolInitializationSchema.parse({
                     connectors: [],
@@ -3247,6 +3269,11 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
         mountedRoot: mountedSkillRoot,
         snapshot: input.snapshot,
     });
+    const skills = skillTool
+        ? {
+            readText: ({ name, path }) => skillTool.execute({ skill: name, path }).content,
+        }
+        : undefined;
     const agentEnvironment = Object.fromEntries(input.snapshot.environment.flatMap((definition) => {
         const value = initialization.runtime.variables[definition.name];
         if (value !== undefined)
@@ -3313,7 +3340,7 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
         if (!runtime) {
             throw new Error(`Custom Connector runtime is missing: ${definition.alias}`);
         }
-        if (!definition.exposeToModel)
+        if (!isAgentConnectorExposed(definition, input.snapshot.codeMode))
             continue;
         if (definition.authorization === "interactive") {
             registerAgentWorkerTool(tools, `${definition.alias}__connect`, tool({
@@ -3440,6 +3467,7 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
                                 }),
                             }
                             : {}),
+                        skills,
                         auth: initialization.runtime.auth,
                         agentTools: {
                             commands: createComputerCommands({
@@ -4298,6 +4326,34 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
             },
         };
     };
+    if (input.snapshot.codeMode) {
+        const configured = await createCodeMode({
+            skills,
+            scriptRuntime: input.toolRuntime.actions.executeJavaScript?.scriptRuntime,
+            scriptToolNames: Object.entries(input.toolRuntime.actions)
+                .filter(([, action]) => action.scriptRuntime)
+                .map(([name]) => name),
+            readArtifact: artifactScope
+                ? async (id, execution) => createAgentArtifacts({
+                    scope: artifactScope,
+                    invoke: (operation) => invokeArtifact(operation, "executeJavaScript", execution),
+                }).readText({ id })
+                : undefined,
+            tools,
+            snapshot: input.snapshot,
+            approval: toolApproval,
+            messages: () => context.messages,
+            guardrail: engine?.guardrail,
+            sdk: {
+                tracing: createAgentTracing(),
+                auth: initialization.runtime.auth,
+                env: agentEnvironment,
+                environment: initialization.runtime.environment,
+                identity,
+            },
+        });
+        tools = configured.tools;
+    }
     let stream;
     if (engine) {
         if (!coreConnection || !coreModule)

package/dist/code-mode-discovery.d.ts

@@ -0,0 +1,38 @@
+import type { AgentToolNamespace } from "@gea-ai/contract/agent-packages";
+export type CodeModeCatalogEntry = {
+    name: string;
+    namespace: string;
+    description: string;
+    inputSchema: unknown;
+    outputSchema?: unknown;
+    structuredContentSchema?: unknown;
+    declaration: string;
+    mcp: boolean;
+};
+type Namespace = AgentToolNamespace & {
+    name: string;
+};
+/** Bounded hints, never a substitute for validation by the original tool schema. */
+export declare function codeModeDeclaration(name: string, input: unknown, output: unknown, mcp: boolean): string;
+/** Pi-compatible helper shapes, implemented against the GEA callable snapshot. */
+export declare function createCodeModeDiscovery(catalog: CodeModeCatalogEntry[], namespaces: Namespace[]): {
+    allTools: {
+        name: string;
+        description: string;
+    }[];
+    searchTools(query: string, options?: {
+        limit?: number;
+        namespace?: string | null;
+    } | null): {
+        name: string;
+        description: string;
+    }[];
+    describeTool(name: string): string | undefined;
+    describeNamespace(name: string): {
+        description?: string | undefined;
+        instructions?: string | undefined;
+        name: string;
+        tools: string[];
+    } | undefined;
+};
+export {};

package/dist/code-mode-discovery.js

@@ -0,0 +1,259 @@
+import { z } from "zod";
+const encoder = new TextEncoder();
+const bytes = (value) => encoder.encode(JSON.stringify(value)).length;
+const nameSchema = z.string().max(256);
+const searchSchema = z.object({
+    query: z.string().max(512),
+    options: z
+        .object({
+        limit: z.number().int().positive().optional(),
+        namespace: nameSchema.nullish(),
+    })
+        .nullish(),
+});
+/** Bounded hints, never a substitute for validation by the original tool schema. */
+export function codeModeDeclaration(name, input, output, mcp) {
+    let remaining = 256;
+    function type(value, depth = 0) {
+        if (--remaining < 0 || depth > 8 || !value || typeof value !== "object")
+            return "unknown";
+        const schema = value;
+        if (schema.$ref || schema.allOf || schema.not || schema.if)
+            return "unknown";
+        if ("const" in schema) {
+            const literal = JSON.stringify(schema.const);
+            return literal.length <= 1024 ? literal : "unknown";
+        }
+        if (Array.isArray(schema.enum)) {
+            const text = schema.enum.length <= 32
+                ? schema.enum.map((value) => JSON.stringify(value)).join(" | ")
+                : "unknown";
+            return text.length <= 1024 ? text || "never" : "unknown";
+        }
+        const union = schema.anyOf ?? schema.oneOf;
+        if (Array.isArray(union))
+            return union.length <= 16
+                ? union.map((value) => type(value, depth + 1)).join(" | ")
+                : "unknown";
+        if (Array.isArray(schema.type))
+            return schema.type.length <= 8
+                ? schema.type
+                    .map((kind) => type({ ...schema, type: kind }, depth + 1))
+                    .join(" | ")
+                : "unknown";
+        switch (schema.type) {
+            case "string":
+            case "boolean":
+            case "null":
+                return schema.type;
+            case "integer":
+            case "number":
+                return "number";
+            case "array":
+                return `Array<${type(schema.items, depth + 1)}>`;
+            case "object": {
+                const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+                const properties = schema.properties && typeof schema.properties === "object"
+                    ? Object.entries(schema.properties)
+                    : [];
+                if (properties.length > 64 ||
+                    properties.some(([key]) => key.length > 128))
+                    return "Record<string, unknown>";
+                const fields = properties.map(([key, value]) => `${JSON.stringify(key)}${required.has(key) ? "" : "?"}: ${type(value, depth + 1)}`);
+                if (schema.additionalProperties !== false)
+                    fields.push("[key: string]: unknown");
+                return `{ ${fields.join("; ")} }`;
+            }
+            default:
+                return "unknown";
+        }
+    }
+    const result = mcp
+        ? "{ content: Array<unknown>; structuredContent?: unknown; isError?: boolean }"
+        : type(output);
+    const prefix = `tools[${JSON.stringify(name)}]`;
+    const text = `${prefix}(input: ${type(input)}): Promise<${result}>`;
+    return text.length <= 4096
+        ? text
+        : `${prefix}(input: unknown): Promise<unknown>`;
+}
+/** No semantic search: ASCII words/identifier pieces, plus Han unigrams and bigrams. */
+function terms(text) {
+    const normalized = text
+        .slice(0, 16384)
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .replace(/([A-Z])([A-Z][a-z])/g, "$1 $2")
+        .toLowerCase();
+    const stop = new Set("a an and are as at be by for from in is it of on or that the this to with".split(" "));
+    const result = [];
+    for (const part of normalized.match(/[a-z0-9]+|\p{Script=Han}+/gu) ?? []) {
+        if (/\p{Script=Han}/u.test(part)) {
+            const chars = [...part];
+            for (let i = 0; i < chars.length; i++) {
+                result.push(chars[i]);
+                if (i + 1 < chars.length)
+                    result.push(chars[i] + chars[i + 1]);
+            }
+        }
+        else if (!stop.has(part)) {
+            result.push(part.length > 4 && part.endsWith("ies")
+                ? part.slice(0, -3) + "y"
+                : part.length > 4 && /(?:ches|shes|sses|xes|zes)$/.test(part)
+                    ? part.slice(0, -2)
+                    : part.length > 3 && part.endsWith("s") && !part.endsWith("ss")
+                        ? part.slice(0, -1)
+                        : part);
+        }
+        if (result.length >= 2048)
+            break;
+    }
+    return result.slice(0, 2048);
+}
+/** Only parameter names/descriptions; bounded traversal of untrusted MCP schemas. */
+function parameterText(input) {
+    const pieces = [];
+    let visited = 0, length = 0;
+    function visit(value, depth) {
+        if (++visited > 256 ||
+            depth > 8 ||
+            length >= 8192 ||
+            !value ||
+            typeof value !== "object")
+            return;
+        const schema = value;
+        if (typeof schema.description === "string") {
+            const text = schema.description.slice(0, 512);
+            pieces.push(text);
+            length += text.length;
+        }
+        if (schema.properties && typeof schema.properties === "object") {
+            for (const [key, property] of Object.entries(schema.properties).slice(0, 64)) {
+                if (visited > 256 || length >= 8192)
+                    break;
+                pieces.push(key.slice(0, 128));
+                length += Math.min(key.length, 128);
+                visit(property, depth + 1);
+            }
+        }
+        visit(schema.items, depth + 1);
+        for (const key of ["anyOf", "oneOf", "allOf"]) {
+            const variants = schema[key];
+            if (Array.isArray(variants))
+                for (const variant of variants.slice(0, 16))
+                    visit(variant, depth + 1);
+        }
+    }
+    visit(input, 0);
+    return pieces.join(" ").slice(0, 8192);
+}
+/** Pi-compatible helper shapes, implemented against the GEA callable snapshot. */
+export function createCodeModeDiscovery(catalog, namespaces) {
+    const summary = (entry) => ({
+        name: entry.name,
+        description: `${entry.description.slice(0, 1024)}\n\n${entry.declaration}\n${entry.mcp ? "Returns the full MCP result envelope (content, optional structuredContent/isError)." : "Returns the original JSON tool result; unknown means no known output schema."}`,
+    });
+    const allTools = catalog.map(summary);
+    if (bytes(allTools) > 256 * 1024)
+        throw new Error("Code mode catalog exceeds the 256 KiB discovery budget; expose fewer tools.");
+    const documents = catalog.map((entry) => {
+        const namespace = namespaces.find((item) => item.name === entry.namespace);
+        const text = [
+            entry.name,
+            entry.name.replaceAll("_", " "),
+            entry.description.slice(0, 2048),
+            namespace?.name,
+            namespace?.description,
+            namespace?.instructions,
+            parameterText(entry.inputSchema),
+        ].join(" ");
+        const tokens = terms(text);
+        const frequencies = new Map();
+        for (const token of tokens)
+            frequencies.set(token, (frequencies.get(token) ?? 0) + 1);
+        return { entry, frequencies, length: tokens.length };
+    });
+    function resolveNamespace(name) {
+        const exact = namespaces.find((item) => item.name === name);
+        if (exact)
+            return exact;
+        const identifier = (value) => value.replace(/[^a-zA-Z0-9_$]/g, "_");
+        const matches = namespaces.filter((item) => identifier(item.name) === identifier(name) ||
+            (item.name.includes("__") &&
+                identifier(item.name.slice(item.name.lastIndexOf("__") + 2)) ===
+                    identifier(name)));
+        if (matches.length > 1)
+            throw new Error("Ambiguous namespace; use its full alias.");
+        return matches[0];
+    }
+    return {
+        allTools,
+        searchTools(query, options) {
+            const parsed = searchSchema.parse({ query, options });
+            const queryTerms = [...new Set(terms(parsed.query))].slice(0, 32);
+            if (!queryTerms.length)
+                return [];
+            const namespace = parsed.options?.namespace
+                ? resolveNamespace(parsed.options.namespace)
+                : undefined;
+            const candidates = parsed.options?.namespace
+                ? documents.filter((doc) => doc.entry.namespace === namespace?.name)
+                : documents;
+            if (!candidates.length)
+                return [];
+            const average = candidates.reduce((sum, doc) => sum + doc.length, 0) /
+                candidates.length || 1;
+            const weights = new Map(queryTerms.map((term) => {
+                const frequency = candidates.filter((doc) => doc.frequencies.has(term)).length;
+                return [
+                    term,
+                    Math.log(1 + (candidates.length - frequency + 0.5) / (frequency + 0.5)),
+                ];
+            }));
+            const ranked = candidates
+                .map((doc) => ({
+                doc,
+                score: queryTerms.reduce((score, term) => {
+                    const tf = doc.frequencies.get(term) ?? 0;
+                    return (score +
+                        ((weights.get(term) ?? 0) * tf * 2.2) /
+                            (tf + 1.2 * (0.25 + (0.75 * doc.length) / average)));
+                }, 0),
+            }))
+                .filter((item) => item.score > 0)
+                .sort((a, b) => b.score - a.score);
+            const results = [];
+            for (const { doc } of ranked.slice(0, Math.min(parsed.options?.limit ?? 8, 20))) {
+                const next = summary(doc.entry);
+                if (bytes([...results, next]) > 32 * 1024)
+                    break;
+                results.push(next);
+            }
+            return results;
+        },
+        describeTool(name) {
+            nameSchema.parse(name);
+            const entry = catalog.find((item) => item.name === name);
+            if (!entry)
+                return undefined;
+            const detail = `${summary(entry).description}\nInput JSON Schema: ${JSON.stringify(entry.inputSchema)}${entry.outputSchema === undefined ? "" : `\nOutput JSON Schema: ${JSON.stringify(entry.outputSchema)}`}${entry.structuredContentSchema === undefined ? "" : `\nMCP structuredContent JSON Schema: ${JSON.stringify(entry.structuredContentSchema)}`}`;
+            if (bytes(detail) > 64 * 1024)
+                throw new Error("Tool description exceeds the 64 KiB discovery budget; use searchTools for its bounded declaration.");
+            return detail;
+        },
+        describeNamespace(name) {
+            nameSchema.parse(name);
+            const namespace = resolveNamespace(name);
+            if (!namespace)
+                return undefined;
+            const result = {
+                ...namespace,
+                tools: catalog
+                    .filter((entry) => entry.namespace === namespace.name)
+                    .map((entry) => entry.name),
+            };
+            if (bytes(result) > 32 * 1024)
+                throw new Error("Namespace exceeds the 32 KiB discovery budget; use searchTools with its full namespace.");
+            return result;
+        },
+    };
+}