@byteplus-iga-pages/agent 0.0.0-stage → 1.0.4

package/dist/types/tools/types.d.ts

@@ -0,0 +1,307 @@
+import type { ZodIssue, ZodType } from "zod";
+import type { IgaErrorInfo } from "../sandbox/index.js";
+export type ToolFramework = "claude-agent-sdk" | "openai-sdk" | "openai-agents-sdk";
+export interface ShellExecInput {
+    command: string;
+    cwd?: string;
+    /** 超时时间，单位为秒。 */
+    timeout?: number;
+}
+export interface FilesReadInput {
+    path: string;
+    startLine?: number;
+    endLine?: number;
+}
+export interface FilesWriteInput {
+    path: string;
+    content: string;
+    append?: boolean;
+}
+export interface FilesListInput {
+    path: string;
+    recursive?: boolean;
+}
+export interface FilesSearchInput {
+    path: string;
+    pattern: string;
+    maxResults?: number;
+}
+export interface FilesFindInput {
+    path: string;
+    glob: string;
+}
+export interface CodeRunInput {
+    language: "python" | "javascript";
+    code: string;
+    /** 超时时间，单位为秒。 */
+    timeout?: number;
+}
+export interface BrowserFetchInput {
+    url: string;
+}
+export interface BrowserScreenshotInput {
+    fullPage?: boolean;
+}
+/** 内置工具的标准入参；模型原始输入仍在执行时校验和转换。 */
+export type ToolInputMap = {
+    shell_exec: ShellExecInput;
+    files_read: FilesReadInput;
+    files_write: FilesWriteInput;
+    files_list: FilesListInput;
+    files_search: FilesSearchInput;
+    files_find: FilesFindInput;
+    code_run: CodeRunInput;
+    browser_fetch: BrowserFetchInput;
+    browser_screenshot: BrowserScreenshotInput;
+};
+export interface ShellConsoleEntry {
+    readonly ps1: string;
+    readonly command: string;
+    readonly output?: string;
+}
+export interface ShellExecOutput {
+    readonly sessionId: string;
+    readonly command: string;
+    readonly output?: string;
+    readonly console?: readonly ShellConsoleEntry[];
+    readonly exitCode?: number;
+}
+export interface FilesReadOutput {
+    readonly content: string;
+    readonly file: string;
+}
+export interface FilesWriteOutput {
+    readonly file: string;
+    readonly bytesWritten?: number;
+}
+export interface FileListEntry {
+    readonly name: string;
+    readonly path: string;
+    readonly isDirectory: boolean;
+    readonly size?: number;
+    readonly modifiedTime?: string;
+    readonly permissions?: string;
+    readonly extension?: string;
+}
+export interface FilesListOutput {
+    readonly path: string;
+    readonly files?: readonly FileListEntry[];
+    readonly totalCount?: number;
+    readonly directoryCount?: number;
+    readonly fileCount?: number;
+}
+export interface FileSearchMatch {
+    readonly file: string;
+    readonly lineNumber: number;
+    readonly lineContent: string;
+    readonly contextBefore?: readonly string[];
+    readonly contextAfter?: readonly string[];
+}
+export interface FilesSearchOutput {
+    readonly path: string;
+    readonly pattern: string;
+    readonly matches?: readonly FileSearchMatch[];
+    readonly matchCount?: number;
+    readonly filesSearched?: number;
+    readonly filesMatched?: number;
+    readonly truncated?: boolean;
+}
+export interface FilesFindOutput {
+    readonly path: string;
+    readonly files?: readonly string[];
+}
+export interface CodeRunOutput {
+    readonly language: "python" | "javascript";
+    readonly outputs?: readonly Readonly<Record<string, unknown>>[];
+    readonly code: string;
+    readonly stdout?: string;
+    readonly stderr?: string;
+    readonly exitCode?: number;
+    readonly traceback?: readonly string[];
+    readonly sessionId?: string;
+}
+export interface BrowserFetchOutput {
+    readonly content: string;
+    readonly url?: string;
+    readonly title?: string;
+    readonly status?: number;
+    readonly loadTimeMs?: number;
+}
+/** 完整截图；长度字段保留给日志和已有调用方。 */
+export interface BrowserScreenshotOutput {
+    readonly base64Image: string;
+    readonly mimeType: "image/png" | "image/jpeg" | "image/webp" | "image/gif";
+    readonly base64ImageLength: number;
+}
+export type ToolOutputMap = {
+    shell_exec: ShellExecOutput;
+    files_read: FilesReadOutput;
+    files_write: FilesWriteOutput;
+    files_list: FilesListOutput;
+    files_search: FilesSearchOutput;
+    files_find: FilesFindOutput;
+    code_run: CodeRunOutput;
+    browser_fetch: BrowserFetchOutput;
+    browser_screenshot: BrowserScreenshotOutput;
+};
+/** 注册表内置的全部工具名，属性访问（tools.files_read）的类型来源。 */
+export type SandboxToolName = keyof ToolInputMap;
+export type ToolDomain = "shell" | "files" | "code" | "browser";
+/**
+ * 工具入参的 JSON Schema。带索引签名，这样能直接赋给 OpenAI 官方 SDK 的
+ * FunctionParameters（Record<string, unknown>）——interface 没有索引签名时
+ * TS 会拒绝这种赋值，调用方就得层层 cast。
+ */
+export interface JsonSchema {
+    readonly type: "object";
+    readonly properties: Record<string, unknown>;
+    readonly required?: readonly string[];
+    readonly additionalProperties?: boolean;
+    readonly [key: string]: unknown;
+}
+export interface ToolError extends IgaErrorInfo {
+    readonly tool: string;
+    /** Original API error or business-failure response body, with credentials redacted. */
+    readonly upstream?: unknown;
+    /** Complete local validation issues, with credentials redacted. */
+    readonly issues?: readonly ZodIssue[];
+}
+/** Tool invocation status. */
+export type ToolResult<Output = unknown> = {
+    readonly status: "success";
+    readonly data: Output;
+} | {
+    readonly status: "error";
+    readonly error: ToolError;
+};
+export interface ToolExecuteOptions {
+    abortSignal?: AbortSignal;
+}
+export type ToolContent = {
+    readonly type: "text";
+    readonly text: string;
+} | {
+    readonly type: "image";
+    readonly data: string;
+    readonly mimeType: string;
+};
+export type OpenAIAgentsImageContent = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    image: string;
+};
+export type OpenAIAgentsInvokeResult<Output> = unknown extends Output ? ToolResult<Output> | OpenAIAgentsImageContent[] : Output extends BrowserScreenshotOutput ? ToolResult<Output> | OpenAIAgentsImageContent[] : ToolResult<Output>;
+export type LangChainImageContent = {
+    type: "text";
+    text: string;
+} | {
+    type: "image_url";
+    image_url: {
+        url: string;
+    };
+};
+export type OpenAIModelMessage = {
+    role: "tool";
+    tool_call_id: string;
+    content: string;
+} | {
+    role: "user";
+    content: LangChainImageContent[];
+};
+export interface ToolDefinition<Input = unknown, Output = unknown> {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: JsonSchema;
+    execute(input: Input, options?: ToolExecuteOptions): Promise<ToolResult<Output>>;
+}
+export interface OpenAIToolDeclaration {
+    readonly type: "function";
+    readonly function: {
+        readonly name: string;
+        readonly description: string;
+        readonly parameters: JsonSchema;
+    };
+}
+export interface OpenAISdkTool<Input = unknown, Output = unknown> extends OpenAIToolDeclaration {
+    execute(input: Input, options?: ToolExecuteOptions): Promise<ToolResult<Output>>;
+    /** Chat Completions: append all tool messages before any returned user image messages. */
+    toModelMessages(result: ToolResult<Output>, toolCallId: string): OpenAIModelMessage[];
+}
+export interface OpenAIAgentsTool<Input = unknown, Output = unknown> {
+    readonly type: "function";
+    readonly name: string;
+    readonly description: string;
+    readonly strict: true;
+    readonly parameters: JsonSchema;
+    execute(input: Input, options?: ToolExecuteOptions): Promise<ToolResult<Output>>;
+    invoke(contextOrInput: unknown, input?: unknown, details?: {
+        readonly signal?: AbortSignal;
+    }): Promise<OpenAIAgentsInvokeResult<Output>>;
+    needsApproval(input?: unknown): Promise<false>;
+    isEnabled(input?: unknown): Promise<true>;
+}
+export interface ClaudeAgentSdkTool<Input = unknown, Output = unknown> extends ClaudeMcpTool {
+    execute(input: Input, options?: ToolExecuteOptions): Promise<ToolResult<Output>>;
+}
+export interface ClaudeMcpToolResult {
+    /** MCP CallToolResult permits protocol extension fields. */
+    readonly [key: string]: unknown;
+    readonly content: ToolContent[];
+    readonly isError?: boolean;
+}
+export interface ClaudeMcpTool {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: Record<string, ZodType<unknown>>;
+    handler(input: Record<string, unknown>, extra?: unknown): Promise<ClaudeMcpToolResult>;
+    readonly _meta?: {
+        readonly "anthropic/alwaysLoad": true;
+    };
+}
+export interface ClaudeMcpConfigOptions {
+    alwaysLoad?: boolean;
+    /** Select the tools to register and include in allowedTools. */
+    names?: readonly string[];
+}
+/** Claude integration configuration; does not create or register a server. */
+export interface ClaudeMcpConfig {
+    readonly name: string;
+    readonly tools: ClaudeMcpTool[];
+    /** Suggested Claude Agent pre-approval list; not an MCP server option. */
+    readonly allowedTools: string[];
+}
+export type FrameworkTool<T extends ToolFramework | undefined = undefined, Input = unknown, Output = unknown> = T extends undefined ? ToolDefinition<Input, Output> : T extends "openai-sdk" ? OpenAISdkTool<Input, Output> : T extends "openai-agents-sdk" ? OpenAIAgentsTool<Input, Output> : T extends "claude-agent-sdk" ? ClaudeAgentSdkTool<Input, Output> : never;
+type NamedTools<T extends ToolFramework | undefined> = {
+    [K in SandboxToolName]: FrameworkTool<T, ToolInputMap[K], ToolOutputMap[K]>;
+};
+type ToolInputLookup = ToolInputMap & Record<string, unknown>;
+type ToolOutputLookup = ToolOutputMap & Record<string, unknown>;
+/**
+ * getTools() 的返回值：属性访问 + get() 两形态。
+ *
+ * - tools.files_read / tools.get("files_read")：按名称推导 execute 的输入和输出；
+ * - tools.get(name: string)：动态工具保留 unknown 输入和输出，入参由运行时校验。
+ * 两种形态未知名都抛错并列出合法名。
+ */
+export interface Tools<T extends ToolFramework | undefined = undefined> extends NamedTools<T> {
+    all(): FrameworkTool<T>[];
+    get<K extends string>(name: K): FrameworkTool<T, ToolInputLookup[K], ToolOutputLookup[K]>;
+    files(): FrameworkTool<T>[];
+    shell(): FrameworkTool<T>[];
+    code(): FrameworkTool<T>[];
+    browser(): FrameworkTool<T>[];
+    definitions(names?: readonly string[]): ToolDefinition[];
+}
+/** 通用工具集，每个工具提供 inputSchema 和 execute()。 */
+export type PortableTools = Tools<undefined>;
+/** OpenAI SDK 工具声明及执行入口。 */
+export type OpenAISdkTools = Tools<"openai-sdk">;
+/** 可交给 OpenAI Agents SDK 的工具集。 */
+export type OpenAIAgentsTools = Tools<"openai-agents-sdk">;
+/** Native Claude MCP tools, with direct execution and bundle registration. */
+export interface ClaudeAgentTools extends Tools<"claude-agent-sdk"> {
+    toMcpConfig(name?: string, options?: ClaudeMcpConfigOptions): ClaudeMcpConfig;
+}
+export {};

package/package.json

@@ -1,6 +1,138 @@
 {
   "name": "@byteplus-iga-pages/agent",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.4",
+  "description": "Server-only Agent SDK for BytePlus IGA Pages",
+  "license": "SEE LICENSE IN LICENSE",
+  "sideEffects": false,
+  "type": "commonjs",
+  "typesVersions": {
+    "*": {
+      "store": [
+        "dist/types/store/index.d.ts"
+      ],
+      "store/host": [
+        "dist/types/store/host.d.ts"
+      ],
+      "store/openai": [
+        "dist/types/store/openai.d.ts"
+      ],
+      "store/langgraph": [
+        "dist/types/store/langgraph.d.ts"
+      ],
+      "store/claude": [
+        "dist/types/store/claude.d.ts"
+      ],
+      "sandbox": [
+        "dist/types/sandbox/index.d.ts"
+      ],
+      "sandbox/host": [
+        "dist/types/sandbox/host.d.ts"
+      ],
+      "tools": [
+        "dist/types/tools/index.d.ts"
+      ],
+      "tools/openai": [
+        "dist/types/tools/openai.d.ts"
+      ],
+      "tools/openai-agents": [
+        "dist/types/tools/openai-agents.d.ts"
+      ],
+      "tools/claude": [
+        "dist/types/tools/claude.d.ts"
+      ],
+      "tools/langchain": [
+        "dist/types/tools/langchain.d.ts"
+      ]
+    }
+  },
+  "exports": {
+    "./store": {
+      "types": "./dist/types/store/index.d.ts",
+      "import": "./dist/esm/store/index.js",
+      "require": "./dist/cjs/store/index.js"
+    },
+    "./store/host": {
+      "types": "./dist/types/store/host.d.ts",
+      "import": "./dist/esm/store/host.js",
+      "require": "./dist/cjs/store/host.js"
+    },
+    "./store/openai": {
+      "types": "./dist/types/store/openai.d.ts",
+      "import": "./dist/esm/store/openai.js",
+      "require": "./dist/cjs/store/openai.js"
+    },
+    "./store/langgraph": {
+      "types": "./dist/types/store/langgraph.d.ts",
+      "import": "./dist/esm/store/langgraph.js",
+      "require": "./dist/cjs/store/langgraph.js"
+    },
+    "./store/claude": {
+      "types": "./dist/types/store/claude.d.ts",
+      "import": "./dist/esm/store/claude.js",
+      "require": "./dist/cjs/store/claude.js"
+    },
+    "./sandbox": {
+      "types": "./dist/types/sandbox/index.d.ts",
+      "import": "./dist/esm/sandbox/index.js",
+      "require": "./dist/cjs/sandbox/index.js"
+    },
+    "./sandbox/host": {
+      "types": "./dist/types/sandbox/host.d.ts",
+      "import": "./dist/esm/sandbox/host.js",
+      "require": "./dist/cjs/sandbox/host.js"
+    },
+    "./tools": {
+      "types": "./dist/types/tools/index.d.ts",
+      "import": "./dist/esm/tools/index.js",
+      "require": "./dist/cjs/tools/index.js"
+    },
+    "./tools/openai": {
+      "types": "./dist/types/tools/openai.d.ts",
+      "import": "./dist/esm/tools/openai.js",
+      "require": "./dist/cjs/tools/openai.js"
+    },
+    "./tools/openai-agents": {
+      "types": "./dist/types/tools/openai-agents.d.ts",
+      "import": "./dist/esm/tools/openai-agents.js",
+      "require": "./dist/cjs/tools/openai-agents.js"
+    },
+    "./tools/claude": {
+      "types": "./dist/types/tools/claude.d.ts",
+      "import": "./dist/esm/tools/claude.js",
+      "require": "./dist/cjs/tools/claude.js"
+    },
+    "./tools/langchain": {
+      "types": "./dist/types/tools/langchain.d.ts",
+      "import": "./dist/esm/tools/langchain.js",
+      "require": "./dist/cjs/tools/langchain.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@agent-infra/sandbox": "^1.0.17",
+    "@supabase/supabase-js": "2.106.2",
+    "axios": "^1.20.0",
+    "zod": "^3.25.76"
+  },
+  "peerDependencies": {
+    "@anthropic-ai/claude-agent-sdk": ">=0.2.113 <0.4",
+    "@langchain/core": ">=0.3 <2",
+    "@langchain/langgraph-checkpoint": "^1.1.4"
+  },
+  "peerDependenciesMeta": {
+    "@anthropic-ai/claude-agent-sdk": {
+      "optional": true
+    },
+    "@langchain/core": {
+      "optional": true
+    },
+    "@langchain/langgraph-checkpoint": {
+      "optional": true
+    }
+  }
+}