@phaseo/agent-sdk 0.1.1 → 0.1.2

package/dist/types.d.ts

@@ -0,0 +1,215 @@
+import type { AgentGatewayErrorDetails } from "./errors.js";
+import type { AgentDevtoolsConfig } from "./devtools.js";
+export type AgentToolCall = {
+    id: string;
+    name: string;
+    input: unknown;
+};
+export type AgentMessage = {
+    role: "system" | "user";
+    content: string;
+} | {
+    role: "assistant";
+    content: string;
+    toolCalls?: AgentToolCall[];
+} | {
+    role: "tool";
+    content: string;
+    toolCallId: string;
+    name: string;
+};
+export type AgentTool<TInput = unknown, TOutput = unknown, TContext = unknown> = {
+    id: string;
+    description?: string;
+    parameters?: Record<string, unknown>;
+    timeoutMs?: number;
+    execute: (input: TInput, context: AgentRuntimeContext<TContext>) => Promise<TOutput> | TOutput;
+};
+export type AgentRuntimeContext<TContext = unknown> = {
+    runId: string;
+    agentId: string;
+    stepIndex: number;
+    context: TContext | undefined;
+    signal?: AbortSignal;
+};
+export type AgentModelRequest<TContext = unknown> = {
+    agentId: string;
+    model?: string;
+    instructions?: string;
+    messages: AgentMessage[];
+    tools: Array<Pick<AgentTool, "id" | "description" | "parameters">>;
+    context: TContext | undefined;
+    signal?: AbortSignal;
+};
+export type AgentModelResponse = {
+    message: Extract<AgentMessage, {
+        role: "assistant";
+    }>;
+    usage?: Record<string, unknown>;
+    requestId?: string;
+    nativeResponseId?: string | null;
+    provider?: string;
+    model?: string;
+    responseMeta?: Record<string, unknown>;
+};
+export type AgentModelClient<TContext = unknown> = {
+    generate: (request: AgentModelRequest<TContext>) => Promise<AgentModelResponse>;
+};
+export type AgentModelRetryConfig = {
+    maxRetries?: number;
+    backoffMs?: number;
+};
+export type AgentToolExecutionConfig = {
+    toolConcurrency?: number;
+};
+export type AgentEvent = {
+    type: "run.started" | "run.completed" | "run.failed" | "run.cancelled";
+    runId: string;
+    agentId: string;
+    timestamp: string;
+    status: AgentRunStatus;
+    output?: unknown;
+    error?: string;
+    errorDetails?: AgentGatewayErrorDetails;
+} | {
+    type: "run.resumed";
+    runId: string;
+    agentId: string;
+    timestamp: string;
+    status: AgentRunStatus;
+    previousStatus: AgentRunStatus;
+} | {
+    type: "run.waiting_for_human";
+    runId: string;
+    agentId: string;
+    timestamp: string;
+    status: AgentRunStatus;
+    stepIndex: number;
+    pause: AgentHumanPause;
+} | {
+    type: "step.started" | "step.completed" | "step.cancelled" | "step.failed" | "model.requested" | "model.failed" | "model.completed" | "checkpoint.saved";
+    runId: string;
+    agentId: string;
+    timestamp: string;
+    status: AgentRunStatus;
+    stepIndex: number;
+    attempt?: number;
+    requestId?: string;
+    nativeResponseId?: string | null;
+    provider?: string;
+    model?: string;
+    usage?: Record<string, unknown>;
+    responseMeta?: Record<string, unknown>;
+    error?: string;
+    errorDetails?: AgentGatewayErrorDetails;
+} | {
+    type: "tool.started" | "tool.completed" | "tool.failed";
+    runId: string;
+    agentId: string;
+    timestamp: string;
+    status: AgentRunStatus;
+    stepIndex: number;
+    toolCallId: string;
+    toolName: string;
+    output?: unknown;
+    error?: string;
+};
+export type AgentEventHandler = (event: AgentEvent) => void | Promise<void>;
+export type AgentHumanPause = {
+    reason: string;
+    payload?: unknown;
+    requestedAt: string;
+};
+export type AgentHumanReviewRequest = {
+    reason: string;
+    payload?: unknown;
+};
+export type AgentHumanReviewContext<TInput = unknown, TContext = unknown, TOutput = unknown> = {
+    runId: string;
+    agentId: string;
+    stepIndex: number;
+    input: TInput;
+    context: TContext | undefined;
+    messages: AgentMessage[];
+    response: AgentModelResponse;
+    parsedOutput?: TOutput;
+};
+export type AgentDefinition<TInput = unknown, TOutput = unknown, TContext = unknown> = {
+    id: string;
+    model?: string;
+    preset?: string;
+    instructions?: string;
+    tools?: AgentTool<any, any, TContext>[];
+    maxSteps?: number;
+    modelRetry?: AgentModelRetryConfig;
+    toolExecution?: AgentToolExecutionConfig;
+    parseOutput?: (text: string) => TOutput;
+    humanReview?: (context: AgentHumanReviewContext<TInput, TContext, TOutput>) => AgentHumanReviewRequest | null | Promise<AgentHumanReviewRequest | null>;
+};
+export type AgentRunStatus = "queued" | "running" | "waiting_for_tools" | "waiting_for_human" | "completed" | "failed" | "cancelled";
+export type AgentStepStatus = "pending" | "executing_model" | "executing_tools" | "checkpointed" | "cancelled" | "failed";
+export type AgentRunRecord<TInput = unknown, TContext = unknown, TOutput = unknown> = {
+    id: string;
+    agentId: string;
+    status: AgentRunStatus;
+    input: TInput;
+    context?: TContext;
+    messages: AgentMessage[];
+    result?: TOutput;
+    error?: string;
+    errorDetails?: AgentGatewayErrorDetails;
+    pause?: AgentHumanPause | null;
+    createdAt: string;
+    updatedAt: string;
+    stepCount: number;
+};
+export type AgentStepRecord = {
+    runId: string;
+    index: number;
+    status: AgentStepStatus;
+    requestId?: string;
+    nativeResponseId?: string | null;
+    provider?: string;
+    model?: string;
+    modelAttempts?: number;
+    usage?: Record<string, unknown>;
+    toolCalls?: AgentToolCall[];
+    responseMeta?: Record<string, unknown>;
+    error?: string;
+    errorDetails?: AgentGatewayErrorDetails;
+    createdAt: string;
+    updatedAt: string;
+};
+export type AgentRunOptions<TInput = unknown, TContext = unknown> = {
+    input: TInput;
+    client: AgentModelClient<TContext>;
+    context?: TContext;
+    model?: string;
+    preset?: string;
+    maxSteps?: number;
+    modelRetry?: AgentModelRetryConfig;
+    toolExecution?: AgentToolExecutionConfig;
+    signal?: AbortSignal;
+    onEvent?: AgentEventHandler;
+    devtools?: Partial<AgentDevtoolsConfig>;
+};
+export type AgentContinueOptions<TInput = unknown, TOutput = unknown, TContext = unknown> = {
+    run: AgentRunResult<TOutput, TInput, TContext>;
+    client: AgentModelClient<TContext>;
+    context?: TContext;
+    model?: string;
+    preset?: string;
+    maxSteps?: number;
+    modelRetry?: AgentModelRetryConfig;
+    toolExecution?: AgentToolExecutionConfig;
+    signal?: AbortSignal;
+    humanInput?: string;
+    onEvent?: AgentEventHandler;
+    devtools?: Partial<AgentDevtoolsConfig>;
+};
+export type AgentRunResult<TOutput = unknown, TInput = unknown, TContext = unknown> = {
+    run: AgentRunRecord<TInput, TContext, TOutput>;
+    steps: AgentStepRecord[];
+    output: TOutput | undefined;
+    messages: AgentMessage[];
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/examples/coding-review-agent.ts

@@ -0,0 +1,108 @@
+import {
+	createAgent,
+	createGatewayAgentClient,
+	defineTool,
+} from "@phaseo/agent-sdk";
+
+type CodeReviewPlan = {
+	risk: "low" | "medium" | "high";
+	summary: string;
+	recommendedActions: string[];
+	needsApproval: boolean;
+};
+
+const lookupDiffSummary = defineTool({
+	id: "lookup-diff-summary",
+	description: "Return a short summary of the changed files in one pull request.",
+	async execute(input: { pullRequestId: string }) {
+		return {
+			pullRequestId: input.pullRequestId,
+			files: ["apps/api/src/pipeline/before/index.ts", "apps/web/src/lib/chat/formatRoomError.ts"],
+			summary:
+				"Changes touch request validation and request-detail rendering for gateway diagnostics.",
+		};
+	},
+});
+
+const lookupFailingChecks = defineTool({
+	id: "lookup-failing-checks",
+	description: "Return the failing CI checks for one pull request.",
+	async execute(input: { pullRequestId: string }) {
+		return {
+			pullRequestId: input.pullRequestId,
+			failingChecks: ["web-typecheck"],
+		};
+	},
+});
+
+const codingReviewAgent = createAgent<string, CodeReviewPlan>({
+	id: "coding-review-agent",
+	model: "phaseo/free",
+	instructions:
+		"Use the available tools to inspect the coding task, then return a strict JSON review plan with risk, summary, recommendedActions, and needsApproval.",
+	tools: [lookupDiffSummary, lookupFailingChecks],
+	parseOutput(text: string) {
+		return JSON.parse(text) as CodeReviewPlan;
+	},
+	humanReview: ({ parsedOutput }: { parsedOutput?: CodeReviewPlan }) =>
+		parsedOutput?.needsApproval
+			? {
+					reason: "coding_review_approval_required",
+					payload: parsedOutput,
+			  }
+			: null,
+});
+
+async function main() {
+	const client = createGatewayAgentClient({
+		clientOptions: {
+			apiKey: process.env.PHASEO_API_KEY!,
+		},
+		responseFormat: {
+			type: "json_schema",
+			name: "code_review_plan",
+			schema: {
+				type: "object",
+				properties: {
+					risk: {
+						type: "string",
+						enum: ["low", "medium", "high"],
+					},
+					summary: { type: "string" },
+					recommendedActions: {
+						type: "array",
+						items: { type: "string" },
+						minItems: 1,
+					},
+					needsApproval: { type: "boolean" },
+				},
+				required: ["risk", "summary", "recommendedActions", "needsApproval"],
+				additionalProperties: false,
+			},
+		},
+		plugins: [{ id: "response-healing", mode: "strict" }],
+	});
+
+	const result = await codingReviewAgent.run({
+		input: "Review pull request pr_482 and produce a remediation plan.",
+		client,
+		onEvent(event: { type: string; runId: string }) {
+			console.log(event.type, event.runId);
+		},
+	});
+
+	if (result.run.status === "waiting_for_human") {
+		console.log("Paused for approval:", result.run.pause);
+		const continued = await codingReviewAgent.continueRun({
+			run: result,
+			client,
+			humanInput: "Approved. Finalize the plan.",
+		});
+		console.log(continued.output);
+		return;
+	}
+
+	console.log(result.output);
+}
+
+void main();

package/examples/parallel-tool-agent.ts

@@ -0,0 +1,60 @@
+import { createAgent, createGatewayAgentClient, defineTool } from "@phaseo/agent-sdk";
+
+const fetchDocs = defineTool({
+	id: "fetch-docs",
+	description: "Fetch one internal docs summary by slug.",
+	async execute(input: { slug: string }) {
+		return {
+			slug: input.slug,
+			summary: `Docs summary for ${input.slug}`,
+		};
+	},
+});
+
+const fetchStatus = defineTool({
+	id: "fetch-status",
+	description: "Fetch one status summary by component id.",
+	async execute(input: { component: string }) {
+		return {
+			component: input.component,
+			status: "operational",
+		};
+	},
+});
+
+const fetchIncidents = defineTool({
+	id: "fetch-incidents",
+	description: "Fetch one current incident digest by service id.",
+	async execute(input: { service: string }) {
+		return {
+			service: input.service,
+			openIncidents: 0,
+		};
+	},
+});
+
+const agent = createAgent({
+	id: "parallel-tool-agent",
+	model: "phaseo/free",
+	instructions:
+		"Use the available tools to gather context, then return one concise operational summary.",
+	tools: [fetchDocs, fetchStatus, fetchIncidents],
+	toolExecution: {
+		toolConcurrency: 3,
+	},
+});
+
+const result = await agent.run({
+	input:
+		"Fetch the presets docs, the gateway status component, and the async-jobs incident digest, then summarize the current state.",
+	client: createGatewayAgentClient({
+		clientOptions: {
+			apiKey: process.env.PHASEO_API_KEY!,
+		},
+	}),
+	onEvent(event) {
+		console.log(event.type, event.runId);
+	},
+});
+
+console.log(result.output);

package/examples/research-brief-agent.ts

@@ -0,0 +1,70 @@
+import { createAgent, createGatewayAgentClient } from "@phaseo/agent-sdk";
+
+type ResearchBrief = {
+	topic: string;
+	summary: string;
+	sources: Array<{
+		title: string;
+		url: string;
+	}>;
+};
+
+export const researchBriefAgent = createAgent<string, ResearchBrief>({
+	id: "research-brief-agent",
+	model: "phaseo/free",
+	instructions:
+		"Research the user's topic with web search when needed and return a concise JSON brief with cited sources.",
+	parseOutput(text) {
+		return JSON.parse(text) as ResearchBrief;
+	},
+});
+
+const client = createGatewayAgentClient({
+	clientOptions: {
+		apiKey: process.env.PHASEO_API_KEY!,
+	},
+	responseFormat: {
+		type: "json_schema",
+		name: "research_brief",
+		schema: {
+			type: "object",
+			properties: {
+				topic: { type: "string" },
+				summary: { type: "string" },
+				sources: {
+					type: "array",
+					items: {
+						type: "object",
+						properties: {
+							title: { type: "string" },
+							url: { type: "string" },
+						},
+						required: ["title", "url"],
+						additionalProperties: false,
+					},
+					minItems: 1,
+				},
+			},
+			required: ["topic", "summary", "sources"],
+			additionalProperties: false,
+		},
+	},
+	plugins: [{ id: "response-healing" }],
+	gatewayTools: [{ type: "gateway:web_search", parameters: { max_results: 5 } }] as any,
+	toolChoice: "gateway:web_search" as any,
+	webSearchOptions: {
+		search_context_size: "high",
+	},
+});
+
+export async function runResearchBrief(topic: string) {
+	const result = await researchBriefAgent.run({
+		input: topic,
+		client,
+		onEvent(event) {
+			console.log(event.type, event.runId);
+		},
+	});
+
+	return result.output;
+}

package/examples/support-triage-agent.ts

@@ -0,0 +1,104 @@
+import {
+	AgentGatewayError,
+	createAgent,
+	createGatewayAgentClient,
+} from "@phaseo/agent-sdk";
+
+type SupportTriageDecision = {
+	queue: "billing" | "reliability" | "product" | "security";
+	severity: "low" | "medium" | "high";
+	needsHumanReview: boolean;
+	summary: string;
+};
+
+const supportTriageAgent = createAgent<string, SupportTriageDecision>({
+	id: "support-triage-agent",
+	preset: "support-triage",
+	parseOutput(text: string) {
+		return JSON.parse(text) as SupportTriageDecision;
+	},
+	humanReview: ({ parsedOutput }: { parsedOutput?: SupportTriageDecision }) =>
+		parsedOutput?.needsHumanReview
+			? {
+					reason: "support_triage_review_required",
+					payload: parsedOutput,
+			  }
+			: null,
+});
+
+async function main() {
+	try {
+		const client = createGatewayAgentClient({
+			clientOptions: {
+				apiKey: process.env.PHASEO_API_KEY!,
+			},
+			responseFormat: {
+				type: "json_schema",
+				name: "support_triage_decision",
+				schema: {
+					type: "object",
+					properties: {
+						queue: {
+							type: "string",
+							enum: ["billing", "reliability", "product", "security"],
+						},
+						severity: {
+							type: "string",
+							enum: ["low", "medium", "high"],
+						},
+						needsHumanReview: {
+							type: "boolean",
+						},
+						summary: {
+							type: "string",
+						},
+					},
+					required: ["queue", "severity", "needsHumanReview", "summary"],
+					additionalProperties: false,
+				},
+			},
+			plugins: [{ id: "response-healing", mode: "strict" }],
+		});
+
+		const result = await supportTriageAgent.run({
+			input: "Customer says webhook deliveries failed overnight and asks whether data was lost.",
+			client,
+			modelRetry: {
+				maxRetries: 2,
+				backoffMs: 250,
+			},
+			onEvent(event: { type: string; runId: string }) {
+				console.log(event.type, event.runId);
+			},
+		});
+
+		if (result.run.status === "waiting_for_human") {
+			console.log("Paused for approval:", result.run.pause);
+
+			const continued = await supportTriageAgent.continueRun({
+				run: result,
+				client,
+				humanInput: "Approved. Finalize the triage decision.",
+			});
+
+			console.log(continued.output);
+			return;
+		}
+
+		console.log(result.output);
+	} catch (error) {
+		if (error instanceof AgentGatewayError) {
+			console.error("Gateway request failed", {
+				status: error.status,
+				requestId: error.requestId,
+				generationId: error.generationId,
+				reason: error.reason,
+				providerFailureDiagnostics: error.providerFailureDiagnostics,
+				routingDiagnostics: error.routingDiagnostics,
+			});
+		}
+		throw error;
+	}
+}
+
+void main();

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@phaseo/agent-sdk",
-  "version": "0.1.1",
-  "description": "Phaseo Agent SDK transition package.",
+  "description": "TypeScript SDK for building agentic applications on top of Phaseo Gateway",
+  "version": "0.1.2",
   "type": "module",
+  "private": false,
   "license": "MIT",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -15,16 +16,33 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "examples",
+    "README.md",
+    "SKILL.md"
   ],
+  "sideEffects": false,
   "dependencies": {
-    "@ai-stats/agent-sdk": "0.1.1"
+    "@phaseo/sdk": "2.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "rimraf": "^6.0.0",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.7"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/phaseoteam/Phaseo.git"
+    "url": "https://github.com/phaseoteam/Phaseo",
+    "directory": "packages/sdk/agent-sdk-ts"
   },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "pnpm run clean && node ../sdk-ts/node_modules/typescript/bin/tsc -p tsconfig.build.json",
+    "typecheck": "node ../sdk-ts/node_modules/typescript/bin/tsc -p tsconfig.json --noEmit",
+    "test": "pnpm exec vitest run",
+    "pack:dry": "pnpm publish --dry-run --no-git-checks"
   }
-}
+}