@phaseo/agent-sdk 0.1.1 → 0.1.3

package/dist/adapters/gateway-client.js

@@ -0,0 +1,179 @@
+import Phaseo, {} from "@phaseo/sdk";
+import { AgentGatewayError } from "../errors.js";
+function coerceTextContent(content) {
+    return typeof content === "string" ? content : String(content ?? "");
+}
+function toPresetModelAlias(preset) {
+    if (typeof preset !== "string")
+        return undefined;
+    const normalized = preset.trim().replace(/^@+/, "");
+    return normalized.length > 0 ? `@${normalized}` : undefined;
+}
+function toResponsesInput(messages) {
+    return messages.flatMap((message) => {
+        if (message.role === "system")
+            return [];
+        if (message.role === "tool") {
+            return [{
+                    type: "function_call_output",
+                    call_id: message.toolCallId,
+                    output: coerceTextContent(message.content),
+                }];
+        }
+        const baseMessage = {
+            type: "message",
+            role: message.role,
+            content: coerceTextContent(message.content),
+        };
+        if (message.role === "assistant" &&
+            Array.isArray(message.toolCalls) &&
+            message.toolCalls.length > 0) {
+            baseMessage.tool_calls = message.toolCalls.map((toolCall) => ({
+                id: toolCall.id,
+                type: "function",
+                function: {
+                    name: toolCall.name,
+                    arguments: JSON.stringify(toolCall.input ?? {}),
+                },
+            }));
+        }
+        return [baseMessage];
+    });
+}
+function toInstructions(messages, override) {
+    const systemText = messages
+        .filter((message) => message.role === "system")
+        .map((message) => coerceTextContent(message.content))
+        .filter((value) => value.trim().length > 0)
+        .join("\n\n");
+    if (override && systemText)
+        return `${override}\n\n${systemText}`;
+    return (override ?? systemText) || undefined;
+}
+function buildFunctionTools(request) {
+    return request.tools.map((tool) => ({
+        type: "function",
+        function: {
+            name: tool.id,
+            description: tool.description,
+            parameters: tool.parameters && typeof tool.parameters === "object"
+                ? tool.parameters
+                : {
+                    type: "object",
+                    additionalProperties: true,
+                },
+        },
+    }));
+}
+function buildRequestTools(request, extraTools) {
+    const functionTools = buildFunctionTools(request);
+    const nativeTools = Array.isArray(extraTools) ? extraTools : [];
+    const mergedTools = [...functionTools, ...nativeTools];
+    return mergedTools.length > 0 ? mergedTools : undefined;
+}
+function safeParseToolInput(raw) {
+    if (!raw)
+        return {};
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return { raw };
+    }
+}
+function extractToolCalls(response) {
+    const items = Array.isArray(response.output_items)
+        ? response.output_items
+        : Array.isArray(response.output)
+            ? response.output
+            : [];
+    const toolCalls = items
+        .filter((item) => String(item?.type ?? "").toLowerCase() === "function_call")
+        .map((item, index) => ({
+        id: item.call_id ?? `tool_call_${index}`,
+        name: item.name ?? "tool",
+        input: safeParseToolInput(item.arguments),
+    }));
+    return toolCalls.length > 0 ? toolCalls : undefined;
+}
+function extractAssistantText(response) {
+    const items = Array.isArray(response.output_items)
+        ? response.output_items
+        : Array.isArray(response.output)
+            ? response.output
+            : [];
+    const textParts = [];
+    for (const item of items) {
+        if (String(item?.type ?? "").toLowerCase() !== "message")
+            continue;
+        const content = Array.isArray(item.content) ? item.content : [];
+        for (const part of content) {
+            if (String(part?.type ?? "").toLowerCase() === "output_text" && typeof part.text === "string") {
+                textParts.push(part.text);
+            }
+        }
+    }
+    return textParts.join("\n\n");
+}
+function isAsyncIterableResponse(value) {
+    return Symbol.asyncIterator in Object(value);
+}
+function extractResponseMeta(response) {
+    const meta = response.meta;
+    if (!meta || typeof meta !== "object" || Array.isArray(meta))
+        return undefined;
+    return meta;
+}
+export function createGatewayAgentClient(options = {}) {
+    const client = options.client ?? new Phaseo(options.clientOptions ?? {});
+    return {
+        async generate(request) {
+            let response;
+            try {
+                const requestPayload = {
+                    model: request.model ??
+                        options.model ??
+                        toPresetModelAlias(options.preset) ??
+                        "phaseo/free",
+                    input: toResponsesInput(request.messages),
+                    instructions: toInstructions(request.messages, request.instructions),
+                    tools: buildRequestTools(request, options.gatewayTools),
+                    tool_choice: options.toolChoice,
+                    parallel_tool_calls: options.parallelToolCalls,
+                    temperature: options.temperature,
+                    max_output_tokens: options.maxOutputTokens,
+                    provider: options.provider,
+                    reasoning: options.reasoning,
+                    metadata: options.metadata,
+                    meta: options.includeMeta,
+                    user: options.user,
+                    response_format: options.responseFormat,
+                    web_search_options: options.webSearchOptions,
+                    plugins: options.plugins,
+                    provider_options: options.providerOptions,
+                    prompt_cache_key: options.promptCacheKey,
+                };
+                response = await client.responses.create(requestPayload);
+            }
+            catch (error) {
+                throw AgentGatewayError.fromUnknown(error) ?? error;
+            }
+            if (isAsyncIterableResponse(response)) {
+                throw new Error("Streaming agent client responses are not supported in the basic gateway adapter");
+            }
+            return {
+                message: {
+                    role: "assistant",
+                    content: extractAssistantText(response),
+                    toolCalls: extractToolCalls(response),
+                },
+                usage: response.usage,
+                requestId: response.id,
+                nativeResponseId: response.nativeResponseId ?? null,
+                provider: response.provider,
+                model: response.model,
+                responseMeta: extractResponseMeta(response),
+            };
+        },
+    };
+}

package/dist/agent.d.ts

@@ -0,0 +1,7 @@
+import type { AgentContinueOptions, AgentDefinition, AgentRunOptions, AgentTool } from "./types.js";
+export declare function defineTool<TInput = unknown, TOutput = unknown, TContext = unknown>(tool: AgentTool<TInput, TOutput, TContext>): AgentTool<TInput, TOutput, TContext>;
+export declare function createAgent<TInput = unknown, TOutput = string, TContext = unknown>(definition: AgentDefinition<TInput, TOutput, TContext>): {
+    definition: AgentDefinition<TInput, TOutput, TContext>;
+    run: (options: AgentRunOptions<TInput, TContext>) => Promise<import("./types.js").AgentRunResult<TOutput, TInput, TContext>>;
+    continueRun: (options: AgentContinueOptions<TInput, TOutput, TContext>) => Promise<import("./types.js").AgentRunResult<TOutput, TInput, TContext>>;
+};

package/dist/agent.js

@@ -0,0 +1,11 @@
+import { continueAgent, runAgent, } from "./runtime/loop.js";
+export function defineTool(tool) {
+    return tool;
+}
+export function createAgent(definition) {
+    return {
+        definition,
+        run: (options) => runAgent(definition, options),
+        continueRun: (options) => continueAgent(definition, options),
+    };
+}

package/dist/devtools.d.ts

@@ -0,0 +1,26 @@
+import type { AgentDefinition, AgentRunResult } from "./types.js";
+export type AgentDevtoolsConfig = {
+    enabled?: boolean;
+    directory?: string;
+    flushIntervalMs?: number;
+    maxQueueSize?: number;
+    captureHeaders?: boolean;
+    saveAssets?: boolean;
+};
+export declare function createAgentDevtools(options?: AgentDevtoolsConfig): Partial<AgentDevtoolsConfig>;
+export declare function captureAgentRunDevtools<TInput, TOutput, TContext>(args: {
+    type: "agent.run" | "agent.continue";
+    definition: AgentDefinition<TInput, TOutput, TContext>;
+    options: {
+        input?: TInput;
+        context?: TContext;
+        model?: string;
+        preset?: string;
+        maxSteps?: number;
+        devtools?: Partial<AgentDevtoolsConfig>;
+    };
+    startedAt: number;
+    result?: AgentRunResult<TOutput, TInput, TContext>;
+    error?: unknown;
+    runId?: string;
+}): void;

package/dist/devtools.js

@@ -0,0 +1,102 @@
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+const AGENT_SDK_VERSION = "0.1.3";
+const DEFAULT_DEVTOOLS_DIR = ".phaseo-devtools";
+export function createAgentDevtools(options = {}) {
+    return {
+        enabled: true,
+        ...options,
+    };
+}
+export function captureAgentRunDevtools(args) {
+    const config = resolveDevtoolsConfig(args.options.devtools);
+    if (!config.enabled)
+        return;
+    const latestStep = findLatestStep(args.result?.steps);
+    const entry = {
+        id: args.result?.run.id ?? args.runId ?? randomUUID(),
+        type: args.type,
+        timestamp: args.startedAt,
+        duration_ms: Date.now() - args.startedAt,
+        request: {
+            agent_id: args.definition.id,
+            input: args.options.input,
+            context: args.options.context,
+            model: args.options.model ?? args.definition.model,
+            preset: args.options.preset ?? args.definition.preset,
+            max_steps: args.options.maxSteps ?? args.definition.maxSteps,
+            tool_count: args.definition.tools?.length ?? 0,
+        },
+        response: args.result
+            ? {
+                run: args.result.run,
+                steps: args.result.steps,
+                output: args.result.output,
+                messages: args.result.messages,
+            }
+            : null,
+        error: args.error ? toDevtoolsError(args.error) : null,
+        metadata: {
+            sdk: "typescript",
+            sdk_version: AGENT_SDK_VERSION,
+            stream: false,
+            model: latestStep?.model,
+            provider: latestStep?.provider,
+            request_id: latestStep?.requestId,
+            native_response_id: latestStep?.nativeResponseId ?? undefined,
+            agent_id: args.definition.id,
+            run_id: args.result?.run.id ?? args.runId,
+            run_status: args.result?.run.status,
+            step_count: args.result?.steps.length,
+            tool_count: countToolCalls(args.result?.steps),
+        },
+    };
+    writeDevtoolsEntry(config.directory, entry);
+}
+function resolveDevtoolsConfig(config) {
+    const enabled = typeof config?.enabled === "boolean"
+        ? config.enabled
+        : process.env.PHASEO_DEVTOOLS === "true";
+    return {
+        enabled,
+        directory: config?.directory ?? process.env.PHASEO_DEVTOOLS_DIR ?? DEFAULT_DEVTOOLS_DIR,
+    };
+}
+function writeDevtoolsEntry(directory, entry) {
+    fs.mkdirSync(path.join(directory, "assets", "images"), { recursive: true });
+    fs.mkdirSync(path.join(directory, "assets", "audio"), { recursive: true });
+    fs.mkdirSync(path.join(directory, "assets", "video"), { recursive: true });
+    const metadataPath = path.join(directory, "metadata.json");
+    if (!fs.existsSync(metadataPath)) {
+        fs.writeFileSync(metadataPath, JSON.stringify({
+            session_id: randomUUID(),
+            started_at: Date.now(),
+            sdk: "typescript",
+            sdk_version: AGENT_SDK_VERSION,
+            platform: process.platform,
+            node_version: process.version,
+        }, null, 2), "utf-8");
+    }
+    fs.appendFileSync(path.join(directory, "generations.jsonl"), `${JSON.stringify(entry)}\n`, "utf-8");
+}
+function findLatestStep(steps) {
+    if (!steps?.length)
+        return undefined;
+    return steps[steps.length - 1];
+}
+function countToolCalls(steps) {
+    if (!steps?.length)
+        return 0;
+    return steps.reduce((count, step) => count + (step.toolCalls?.length ?? 0), 0);
+}
+function toDevtoolsError(error) {
+    return {
+        message: error instanceof Error ? error.message : String(error),
+        code: typeof error?.code === "string" ? error.code : undefined,
+        status: typeof error?.status === "number"
+            ? error.status
+            : undefined,
+        stack: error instanceof Error ? error.stack : undefined,
+    };
+}

package/dist/errors.d.ts

@@ -0,0 +1,60 @@
+export type AgentGatewayErrorBody = {
+    message?: string;
+    error?: unknown;
+    reason?: string;
+    error_origin?: string;
+    error_type?: string;
+    request_id?: string;
+    generation_id?: string;
+    failed_providers?: string[];
+    failed_statuses?: number[];
+    provider_failure_diagnostics?: Record<string, unknown>;
+    provider_enablement?: Record<string, unknown>;
+    routing_diagnostics?: Record<string, unknown>;
+    details?: Array<Record<string, unknown>>;
+    [key: string]: unknown;
+} | string | undefined;
+export type AgentGatewayErrorDetails = {
+    status: number;
+    statusText: string;
+    message: string;
+    requestId: string | null;
+    generationId: string | null;
+    reason: string | null;
+    errorOrigin: string | null;
+    errorType: string | null;
+    failedProviders: string[];
+    failedStatuses: number[];
+    providerFailureDiagnostics: Record<string, unknown> | null;
+    providerEnablement: Record<string, unknown> | null;
+    routingDiagnostics: Record<string, unknown> | null;
+    details: Array<Record<string, unknown>>;
+};
+export declare class AgentGatewayError extends Error {
+    readonly status: number;
+    readonly statusText: string;
+    readonly headers: Record<string, string>;
+    readonly body: AgentGatewayErrorBody;
+    readonly requestId: string | null;
+    readonly generationId: string | null;
+    readonly reason: string | null;
+    readonly errorOrigin: string | null;
+    readonly errorType: string | null;
+    readonly failedProviders: string[];
+    readonly failedStatuses: number[];
+    readonly providerFailureDiagnostics: Record<string, unknown> | null;
+    readonly providerEnablement: Record<string, unknown> | null;
+    readonly routingDiagnostics: Record<string, unknown> | null;
+    readonly details: Array<Record<string, unknown>>;
+    constructor(args: {
+        status: number;
+        statusText: string;
+        headers?: Record<string, string>;
+        body: AgentGatewayErrorBody;
+        message?: string;
+        cause?: unknown;
+    });
+    static fromUnknown(error: unknown): AgentGatewayError | null;
+}
+export declare function isAgentGatewayError(error: unknown): error is AgentGatewayError;
+export declare function toAgentGatewayErrorDetails(error: AgentGatewayError): AgentGatewayErrorDetails;

package/dist/errors.js

@@ -0,0 +1,161 @@
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function normalizeHeaders(value) {
+    if (!isRecord(value))
+        return {};
+    const headers = {};
+    for (const [key, rawValue] of Object.entries(value)) {
+        if (typeof rawValue === "string") {
+            headers[key.toLowerCase()] = rawValue;
+        }
+    }
+    return headers;
+}
+function readString(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}
+function headerValue(headers, ...keys) {
+    for (const key of keys) {
+        const value = headers[key.toLowerCase()];
+        if (typeof value === "string" && value.length > 0)
+            return value;
+    }
+    return undefined;
+}
+function isGatewayHttpErrorLike(value) {
+    if (!isRecord(value))
+        return false;
+    return (typeof value.status === "number" &&
+        typeof value.statusText === "string" &&
+        "body" in value &&
+        (value.name === "PhaseoHttpError" || value.name === "PhaseoHttpError" || "headers" in value));
+}
+function formatGatewayErrorMessage(args) {
+    if (args.fallback)
+        return args.fallback;
+    if (typeof args.body === "string" && args.body.trim().length > 0) {
+        return `Gateway request failed: ${args.status} ${args.statusText} - ${args.body}`;
+    }
+    if (isRecord(args.body)) {
+        const message = readString(args.body.message) ??
+            readString(args.body.description) ??
+            readString(args.body.reason);
+        if (message) {
+            return `Gateway request failed: ${args.status} ${args.statusText} - ${message}`;
+        }
+    }
+    return `Gateway request failed: ${args.status} ${args.statusText}`;
+}
+export class AgentGatewayError extends Error {
+    status;
+    statusText;
+    headers;
+    body;
+    requestId;
+    generationId;
+    reason;
+    errorOrigin;
+    errorType;
+    failedProviders;
+    failedStatuses;
+    providerFailureDiagnostics;
+    providerEnablement;
+    routingDiagnostics;
+    details;
+    constructor(args) {
+        super(formatGatewayErrorMessage({
+            status: args.status,
+            statusText: args.statusText,
+            body: args.body,
+            fallback: args.message,
+        }), { cause: args.cause });
+        this.name = "AgentGatewayError";
+        this.status = args.status;
+        this.statusText = args.statusText;
+        this.headers = args.headers ?? {};
+        this.body = args.body;
+        if (isRecord(args.body)) {
+            this.requestId =
+                readString(args.body.request_id) ??
+                    headerValue(this.headers, "x-request-id", "request-id", "x-phaseo-request-id") ??
+                    null;
+            this.generationId = readString(args.body.generation_id) ?? null;
+            this.reason = readString(args.body.reason) ?? null;
+            this.errorOrigin = readString(args.body.error_origin) ?? null;
+            this.errorType = readString(args.body.error_type) ?? null;
+            this.failedProviders = Array.isArray(args.body.failed_providers)
+                ? args.body.failed_providers.filter((value) => typeof value === "string")
+                : [];
+            this.failedStatuses = Array.isArray(args.body.failed_statuses)
+                ? args.body.failed_statuses.filter((value) => typeof value === "number")
+                : [];
+            this.providerFailureDiagnostics = isRecord(args.body.provider_failure_diagnostics)
+                ? args.body.provider_failure_diagnostics
+                : null;
+            this.providerEnablement = isRecord(args.body.provider_enablement)
+                ? args.body.provider_enablement
+                : null;
+            this.routingDiagnostics = isRecord(args.body.routing_diagnostics)
+                ? args.body.routing_diagnostics
+                : null;
+            this.details = Array.isArray(args.body.details)
+                ? args.body.details.filter((value) => isRecord(value))
+                : [];
+        }
+        else {
+            this.requestId =
+                headerValue(this.headers, "x-request-id", "request-id", "x-phaseo-request-id") ??
+                    null;
+            this.generationId = null;
+            this.reason = null;
+            this.errorOrigin = null;
+            this.errorType = null;
+            this.failedProviders = [];
+            this.failedStatuses = [];
+            this.providerFailureDiagnostics = null;
+            this.providerEnablement = null;
+            this.routingDiagnostics = null;
+            this.details = [];
+        }
+    }
+    static fromUnknown(error) {
+        if (!isGatewayHttpErrorLike(error))
+            return null;
+        return new AgentGatewayError({
+            status: error.status,
+            statusText: error.statusText,
+            headers: normalizeHeaders(error.headers),
+            body: error.body,
+            message: typeof error.message === "string" ? error.message : undefined,
+            cause: error,
+        });
+    }
+}
+export function isAgentGatewayError(error) {
+    return error instanceof AgentGatewayError;
+}
+export function toAgentGatewayErrorDetails(error) {
+    return {
+        status: error.status,
+        statusText: error.statusText,
+        message: error.message,
+        requestId: error.requestId,
+        generationId: error.generationId,
+        reason: error.reason,
+        errorOrigin: error.errorOrigin,
+        errorType: error.errorType,
+        failedProviders: [...error.failedProviders],
+        failedStatuses: [...error.failedStatuses],
+        providerFailureDiagnostics: error.providerFailureDiagnostics
+            ? structuredClone(error.providerFailureDiagnostics)
+            : null,
+        providerEnablement: error.providerEnablement
+            ? structuredClone(error.providerEnablement)
+            : null,
+        routingDiagnostics: error.routingDiagnostics
+            ? structuredClone(error.routingDiagnostics)
+            : null,
+        details: structuredClone(error.details),
+    };
+}

package/dist/index.d.ts

@@ -1 +1,8 @@
-export * from "@ai-stats/agent-sdk";
+export { createAgent, defineTool } from "./agent.js";
+export { createGatewayAgentClient } from "./adapters/gateway-client.js";
+export { createAgentDevtools } from "./devtools.js";
+export { AgentGatewayError, isAgentGatewayError } from "./errors.js";
+export type { AgentDefinition, AgentContinueOptions, AgentEvent, AgentEventHandler, AgentHumanPause, AgentHumanReviewContext, AgentHumanReviewRequest, AgentMessage, AgentModelClient, AgentModelRetryConfig, AgentModelRequest, AgentModelResponse, AgentRunOptions, AgentRunRecord, AgentRunResult, AgentRunStatus, AgentRuntimeContext, AgentStepRecord, AgentStepStatus, AgentTool, AgentToolCall, AgentToolExecutionConfig, } from "./types.js";
+export type { AgentDevtoolsConfig } from "./devtools.js";
+export type { GatewayAgentClientOptions } from "./adapters/gateway-client.js";
+export type { AgentGatewayErrorBody, AgentGatewayErrorDetails } from "./errors.js";

package/dist/index.js

@@ -1 +1,4 @@
-export * from "@ai-stats/agent-sdk";
+export { createAgent, defineTool } from "./agent.js";
+export { createGatewayAgentClient } from "./adapters/gateway-client.js";
+export { createAgentDevtools } from "./devtools.js";
+export { AgentGatewayError, isAgentGatewayError } from "./errors.js";

package/dist/runtime/loop.d.ts

@@ -0,0 +1,3 @@
+import type { AgentContinueOptions, AgentDefinition, AgentRunOptions, AgentRunResult } from "../types.js";
+export declare function runAgent<TInput, TOutput, TContext>(definition: AgentDefinition<TInput, TOutput, TContext>, options: AgentRunOptions<TInput, TContext>): Promise<AgentRunResult<TOutput, TInput, TContext>>;
+export declare function continueAgent<TInput, TOutput, TContext>(definition: AgentDefinition<TInput, TOutput, TContext>, options: AgentContinueOptions<TInput, TOutput, TContext>): Promise<AgentRunResult<TOutput, TInput, TContext>>;