@kobinflow/canvas-agent 0.6.0

package/dist/agent/codex-protocol.d.ts

@@ -0,0 +1,335 @@
+import type { JsonRecord } from "../utils/value.js";
+export type CodexThread = JsonRecord & {
+    id: string;
+    cwd: string;
+    turns?: CodexTurn[];
+};
+export type CodexTurn = JsonRecord & {
+    id: string;
+    error?: CodexTurnError | null;
+    durationMs?: number | null;
+};
+export type CodexTurnError = JsonRecord & {
+    message: string;
+};
+export type CodexItem = JsonRecord & {
+    id: string;
+    type: string;
+    text?: string;
+};
+export type CodexPlanStep = {
+    step: string;
+    status: "pending" | "inProgress" | "completed";
+};
+export type CodexPlanUpdate = {
+    threadId: string;
+    turnId: string;
+    explanation?: string | null;
+    plan: CodexPlanStep[];
+    turnStatus?: string;
+};
+export type CodexMcpStartupStatus = {
+    threadId: string | null;
+    name: string;
+    status: "starting" | "ready" | "failed" | "cancelled";
+    error: string | null;
+    failureReason: "reauthenticationRequired" | null;
+};
+export type CodexMcpServerStatus = {
+    name: string;
+    authStatus: "unsupported" | "notLoggedIn" | "bearerToken" | "oAuth";
+} & JsonRecord;
+export type CodexReasoningEffort = "minimal" | "low" | "medium" | "high" | "xhigh" | "max" | "ultra";
+export type CodexModel = JsonRecord & {
+    id: string;
+    model: string;
+    displayName: string;
+    defaultReasoningEffort: CodexReasoningEffort;
+    supportedReasoningEfforts: Array<{
+        reasoningEffort: CodexReasoningEffort;
+        description?: string;
+    }>;
+    isDefault?: boolean;
+};
+export type CodexSkillScope = "user" | "repo" | "system" | "admin";
+export type CodexSkillInterface = JsonRecord & {
+    displayName?: string | null;
+    shortDescription?: string | null;
+    iconSmall?: string | null;
+    iconLarge?: string | null;
+    iconSmallUrl?: string | null;
+    iconLargeUrl?: string | null;
+    brandColor?: string | null;
+    defaultPrompt?: string | null;
+};
+export type CodexSkillMetadata = JsonRecord & {
+    name: string;
+    description: string;
+    shortDescription?: string | null;
+    interface?: CodexSkillInterface | null;
+    dependencies?: JsonRecord | null;
+    path: string;
+    scope: CodexSkillScope;
+    enabled: boolean;
+};
+export type CodexSkillError = {
+    path: string;
+    message: string;
+};
+export type CodexSkillsListEntry = {
+    cwd: string;
+    skills: CodexSkillMetadata[];
+    errors: CodexSkillError[];
+};
+export type CodexSkillSelector = {
+    name: string;
+    path: string;
+};
+export type CodexTurnInput = {
+    type: "text";
+    text: string;
+    text_elements: [];
+} | {
+    type: "localImage";
+    path: string;
+} | ({
+    type: "skill";
+} & CodexSkillSelector);
+type ThreadOptions = {
+    approvalPolicy: "never" | "on-request";
+    sandbox: "read-only" | "workspace-write" | "danger-full-access";
+    config: JsonRecord;
+    cwd?: string;
+    developerInstructions?: string;
+    ephemeral?: boolean;
+};
+type CodexRequestSpec = {
+    initialize: {
+        params: {
+            clientInfo: {
+                name: string;
+                title: string;
+                version: string;
+            };
+            capabilities: {
+                experimentalApi: boolean;
+                requestAttestation: boolean;
+            };
+        };
+        result: JsonRecord;
+    };
+    "thread/start": {
+        params: ThreadOptions & {
+            threadSource: "user";
+        };
+        result: {
+            thread: CodexThread;
+        };
+    };
+    "thread/resume": {
+        params: ThreadOptions & {
+            threadId: string;
+        };
+        result: {
+            thread: CodexThread;
+        };
+    };
+    "thread/fork": {
+        params: ThreadOptions & {
+            threadId: string;
+            threadSource: "user";
+        };
+        result: {
+            thread: CodexThread;
+        };
+    };
+    "thread/list": {
+        params: {
+            limit: number;
+            sortKey: "updated_at";
+            sortDirection: "desc";
+            sourceKinds: Array<"cli" | "vscode" | "appServer" | "exec">;
+            cwd: string;
+            searchTerm?: string;
+        };
+        result: {
+            data: CodexThread[];
+            nextCursor: string | null;
+            backwardsCursor: string | null;
+        };
+    };
+    "thread/read": {
+        params: {
+            threadId: string;
+            includeTurns: boolean;
+        };
+        result: {
+            thread: CodexThread;
+        };
+    };
+    "thread/archive": {
+        params: {
+            threadId: string;
+        };
+        result: Record<string, never>;
+    };
+    "thread/unsubscribe": {
+        params: {
+            threadId: string;
+        };
+        result: {
+            status: "notLoaded" | "notSubscribed" | "unsubscribed";
+        };
+    };
+    "model/list": {
+        params: {
+            limit: number;
+            includeHidden: boolean;
+        };
+        result: {
+            data: CodexModel[];
+            nextCursor: string | null;
+        };
+    };
+    "mcpServerStatus/list": {
+        params: {
+            cursor?: string | null;
+            limit?: number | null;
+            detail?: "full" | "toolsAndAuthOnly" | null;
+            threadId?: string | null;
+        };
+        result: {
+            data: CodexMcpServerStatus[];
+            nextCursor: string | null;
+        };
+    };
+    "skills/list": {
+        params: {
+            cwds: string[];
+            forceReload?: boolean;
+        };
+        result: {
+            data: CodexSkillsListEntry[];
+        };
+    };
+    "skills/config/write": {
+        params: {
+            path?: string | null;
+            name?: string | null;
+            enabled: boolean;
+        };
+        result: {
+            effectiveEnabled: boolean;
+        };
+    };
+    "turn/start": {
+        params: {
+            threadId: string;
+            input: CodexTurnInput[];
+            approvalPolicy: "never" | "on-request";
+            sandboxPolicy: {
+                type: "readOnly";
+                networkAccess: boolean;
+            } | {
+                type: "workspaceWrite";
+                networkAccess: boolean;
+            } | {
+                type: "dangerFullAccess";
+            };
+            model?: string;
+            effort?: CodexReasoningEffort;
+            outputSchema?: JsonRecord;
+        };
+        result: {
+            turn: CodexTurn;
+        };
+    };
+    "turn/interrupt": {
+        params: {
+            threadId: string;
+            turnId: string;
+        };
+        result: Record<string, never>;
+    };
+};
+export type CodexRequestMethod = keyof CodexRequestSpec;
+export type CodexRequestParams<Method extends CodexRequestMethod> = CodexRequestSpec[Method]["params"];
+export type CodexRequestResult<Method extends CodexRequestMethod> = CodexRequestSpec[Method]["result"];
+type TokenUsageBreakdown = {
+    inputTokens: number;
+    cachedInputTokens: number;
+    outputTokens: number;
+    reasoningOutputTokens: number;
+};
+type CodexNotificationSpec = {
+    "thread/started": {
+        thread: CodexThread;
+    };
+    "turn/started": {
+        threadId?: string;
+        turn: CodexTurn;
+    };
+    "turn/completed": {
+        threadId?: string;
+        turn: CodexTurn;
+    };
+    "turn/plan/updated": {
+        threadId?: string;
+        turnId: string;
+        explanation?: string | null;
+        plan: CodexPlanStep[];
+    };
+    "item/started": {
+        threadId: string;
+        turnId: string;
+        item: CodexItem;
+    };
+    "item/completed": {
+        threadId: string;
+        turnId: string;
+        item: CodexItem;
+    };
+    "item/agentMessage/delta": {
+        threadId: string;
+        turnId: string;
+        itemId: string;
+        delta: string;
+    };
+    "item/plan/delta": {
+        threadId: string;
+        turnId: string;
+        itemId: string;
+        delta: string;
+    };
+    "item/reasoning/summaryTextDelta": {
+        threadId: string;
+        turnId: string;
+        itemId: string;
+        delta: string;
+        summaryIndex: number;
+    };
+    "item/commandExecution/outputDelta": {
+        threadId: string;
+        turnId: string;
+        itemId: string;
+        delta: string;
+    };
+    "thread/tokenUsage/updated": {
+        threadId: string;
+        turnId: string;
+        tokenUsage: {
+            last: TokenUsageBreakdown;
+        };
+    };
+    "mcpServer/startupStatus/updated": CodexMcpStartupStatus;
+    "skills/changed": Record<string, never>;
+    error: {
+        threadId: string;
+        turnId: string;
+        error: CodexTurnError;
+        willRetry: boolean;
+    };
+};
+export type CodexNotificationMethod = keyof CodexNotificationSpec;
+export type CodexNotificationParams<Method extends CodexNotificationMethod> = CodexNotificationSpec[Method];
+export {};

package/dist/agent/codex-protocol.js

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

package/dist/agent/codex.d.ts

@@ -0,0 +1,178 @@
+import { z } from "zod";
+import type { CanvasSnapshot } from "../canvas/types.js";
+import { type JsonRecord } from "../utils/value.js";
+import type { CodexReasoningEffort, CodexSkillMetadata, CodexSkillSelector, CodexSkillsListEntry } from "./codex-protocol.js";
+import type { AgentAttachment, AgentEmit, AgentPermissionMode } from "./types.js";
+type CodexRunOptions = {
+    threadId?: string;
+    cwd?: string;
+    permissionMode?: AgentPermissionMode;
+    model?: string;
+    effort?: CodexReasoningEffort;
+    skill?: CodexSkillSelector;
+    messageText?: string;
+    appEmit?: AgentEmit;
+    onStart?: () => void;
+    onThread?: (threadId: string) => void;
+    onTurn?: (turnId: string) => void;
+    onFinish?: () => void;
+};
+type CodexSkillDraftInput = {
+    model?: string;
+    effort?: CodexReasoningEffort;
+} & ({
+    source: "conversation";
+    threadId: string;
+} | {
+    source: "canvas";
+    snapshot: CanvasSnapshot;
+});
+declare const skillDraftSchema: z.ZodEffects<z.ZodObject<{
+    name: z.ZodString;
+    displayName: z.ZodString;
+    description: z.ZodEffects<z.ZodString, string, string>;
+    instructions: z.ZodString;
+    shortDescription: z.ZodEffects<z.ZodString, string, string>;
+    defaultPrompt: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    name: string;
+    displayName: string;
+    description: string;
+    instructions: string;
+    shortDescription: string;
+    defaultPrompt: string;
+}, {
+    name: string;
+    displayName: string;
+    description: string;
+    instructions: string;
+    shortDescription: string;
+    defaultPrompt: string;
+}>, {
+    name: string;
+    displayName: string;
+    description: string;
+    instructions: string;
+    shortDescription: string;
+    defaultPrompt: string;
+}, {
+    name: string;
+    displayName: string;
+    description: string;
+    instructions: string;
+    shortDescription: string;
+    defaultPrompt: string;
+}>;
+export type AgentSkillDraft = z.infer<typeof skillDraftSchema>;
+export declare class CodexSkillLookupError extends Error {
+    readonly statusCode: 400 | 404 | 409;
+    name: string;
+    constructor(message: string, statusCode: 400 | 404 | 409);
+}
+export { summarizeCodexThread } from "./codex-history.js";
+/** 将 Codex turn 加入串行队列并等待执行完成。 */
+export declare function runCodexTurn(prompt: string, lifecycleEmit: AgentEmit, attachments?: AgentAttachment[], options?: CodexRunOptions): Promise<void>;
+/** 从当前对话或指定网页画布生成可编辑草稿，不写入 Skill 文件。 */
+export declare function generateCodexSkillDraft(emit: AgentEmit, cwd: string, input: CodexSkillDraftInput): Promise<AgentSkillDraft>;
+/** 中断当前线程正在执行的 Codex turn。 */
+export declare function interruptCodexTurn(threadId?: string): Promise<boolean>;
+/** 回复当前 app-server 的待处理权限请求。 */
+export declare function resolveCodexApproval(requestId: string, decision: string): Promise<boolean>;
+/** 创建新的 Codex 线程并记录当前线程 ID。 */
+export declare function startCodexThread(emit: AgentEmit, cwd?: string, permissionMode?: AgentPermissionMode, preheat?: boolean): Promise<import("./codex-protocol.js").CodexThread>;
+/** 恢复指定 Codex 线程并返回聊天历史。 */
+export declare function resumeCodexThread(emit: AgentEmit, threadId: string, cwd?: string, permissionMode?: AgentPermissionMode, preheat?: boolean): Promise<{
+    thread: import("./codex-protocol.js").CodexThread;
+    messages: {
+        id: string;
+        itemId: string;
+        threadId: string;
+        turnId: string;
+        role: "user" | "assistant" | "tool" | "error";
+        title?: string;
+        text: string;
+        detail?: unknown;
+        activityItems?: Record<string, string>;
+    }[];
+    settledTurnIds: string[];
+    historyReady: boolean;
+}>;
+/** 查询当前工作空间中的 Codex 线程。 */
+export declare function listCodexThreads(emit: AgentEmit, options: {
+    cwd: string;
+    searchTerm?: string;
+    limit?: number;
+}): Promise<{
+    data: {
+        id: string;
+        sessionId: string;
+        preview: string;
+        name: string | null;
+        cwd: string;
+        status: string;
+        source: unknown;
+        threadSource: unknown;
+        createdAt: number;
+        updatedAt: number;
+    }[];
+    nextCursor: {} | null;
+    backwardsCursor: {} | null;
+}>;
+/** 查询当前账号可用于新任务的 Codex 模型。 */
+export declare function listCodexModels(emit: AgentEmit): Promise<{
+    data: import("./codex-protocol.js").CodexModel[];
+    nextCursor: string | null;
+}>;
+/** 查询当前工作空间的原生 Skill 列表。 */
+export declare function listCodexSkills(emit: AgentEmit, cwd: string, forceReload?: boolean): Promise<CodexSkillsListEntry>;
+/** 从原生 Skill 列表中解析并校验浏览器提交的选择器。 */
+export declare function resolveCodexSkill(emit: AgentEmit, cwd: string, selector: CodexSkillSelector, requireEnabled?: boolean): Promise<CodexSkillMetadata>;
+/** 修改经过原生列表校验的 Skill 启用状态。 */
+export declare function configureCodexSkill(emit: AgentEmit, cwd: string, selector: CodexSkillSelector, enabled: boolean): Promise<{
+    skill: {
+        enabled: boolean;
+        name: string;
+        description: string;
+        shortDescription?: string | null;
+        interface?: import("./codex-protocol.js").CodexSkillInterface | null;
+        dependencies?: JsonRecord | null;
+        path: string;
+        scope: import("./codex-protocol.js").CodexSkillScope;
+    };
+    effectiveEnabled: boolean;
+}>;
+/** 读取指定 Codex 线程及其聊天历史。 */
+export declare function readCodexThread(emit: AgentEmit, threadId: string, cwd?: string): Promise<{
+    thread: {
+        id: string;
+        sessionId: string;
+        preview: string;
+        name: string | null;
+        cwd: string;
+        status: string;
+        source: unknown;
+        threadSource: unknown;
+        createdAt: number;
+        updatedAt: number;
+    };
+    messages: {
+        id: string;
+        itemId: string;
+        threadId: string;
+        turnId: string;
+        role: "user" | "assistant" | "tool" | "error";
+        title?: string;
+        text: string;
+        detail?: unknown;
+        activityItems?: Record<string, string>;
+    }[];
+    settledTurnIds: string[];
+    historyReady: boolean;
+}>;
+/** 归档指定 Codex 线程。 */
+export declare function archiveCodexThread(emit: AgentEmit, threadId: string, cwd?: string): Promise<void>;
+/** 判断线程异常是否允许自动新建线程后重试。 */
+export declare function isRecoverableThreadError(error: unknown): boolean;
+/** 只保留理解画布流程所需的信息，避免把媒体、外部地址、坐标和本地凭证送入草稿线程。 */
+export declare function canvasSkillSource(snapshot: CanvasSnapshot): JsonRecord;
+export declare function assertDraftHasNoSensitiveValues(draft: AgentSkillDraft, privateValues: string[]): void;