qcanvas-local-agent 0.1.0

package/README.md

@@ -0,0 +1,36 @@
+# qcanvas-local-agent
+
+QCanvas 「本机 Agent」：在你自己的电脑上运行一个本地桥接服务，让 QCanvas 网页画布可以调用**本机登录的 Codex / Claude** 来读写画布。
+
+## 一条命令启动
+
+```bash
+npx -y qcanvas-local-agent
+```
+
+启动后会打印本地地址（默认 `http://127.0.0.1:17372`）和一个连接令牌（Connect token）。在 QCanvas 网页里切到「本机模式」，把地址和令牌填进去即可连接。
+
+> 需要 Node.js（建议 22 或更新版本）。首次运行会自动下载依赖（含 Codex，可选 Claude）。
+
+## 登录 AI（每台电脑一次）
+
+本机 Agent 驱动的是你本机的 CLI，需各自登录：
+
+- **Codex**：`npx -y @openai/codex login --device-auth`
+- **Claude**（可选）：随包安装的 Claude Code，`claude auth login`
+
+## 可配置的环境变量
+
+| 变量 | 说明 | 默认 |
+|------|------|------|
+| `QCANVAS_LOCAL_AGENT_PORT` | 监听端口 | `17372` |
+| `QCANVAS_LOCAL_AGENT_HOST` | 监听地址 | `127.0.0.1` |
+| `QCANVAS_LOCAL_AGENT_TOKEN` | 连接令牌（不设则随机生成） | 随机 |
+| `QCANVAS_CLAUDE_COMMAND` | Claude 可执行文件路径（默认自动定位随包安装的版本，找不到再用 PATH 的 `claude`） | 自动 |
+
+配置持久化在 `~/.qcanvas/qcanvas-local-agent.json`。
+
+## 说明
+
+- 所有对画布的写操作都会由浏览器二次确认后才真正应用。
+- 令牌仅用于本机 `127.0.0.1` 回环连接的鉴权。

package/dist/agents.d.ts

@@ -0,0 +1,90 @@
+import type { AgentAttachment, AgentEmit } from "./types.js";
+type Json = Record<string, unknown>;
+type CodexRunOptions = {
+    threadId?: string;
+    cwd?: string;
+};
+type ClaudeRunOptions = {
+    threadId?: string;
+    cwd?: string;
+    /** claude CLI 命令，默认 "claude"；不在 PATH 时可传完整路径。 */
+    command?: string;
+    /** 保存的会话 id 失效时是否允许自动改开新会话（仅当 threadId 非用户显式指定时开启）。 */
+    allowFreshFallback?: boolean;
+    /** 每当得知本轮实际使用的 session id 时回调（init/result 事件都会触发）。 */
+    onThread?: (threadId: string) => void;
+};
+export type LocalAgentDescriptor = {
+    id: string;
+    label: string;
+    /** 是否支持服务端会话列表管理（列出/恢复/归档）。 */
+    threads: boolean;
+};
+export declare const LOCAL_AGENTS: LocalAgentDescriptor[];
+export declare function isLocalAgentId(value: unknown): value is string;
+type AgentHistoryMessage = {
+    id: string;
+    role: "user" | "assistant" | "tool" | "error";
+    title?: string;
+    text: string;
+    detail?: unknown;
+    streamId?: string;
+};
+export declare function withAgentPrompt(prompt: string): string;
+export declare function runCodexTurn(prompt: string, emit: AgentEmit, attachments?: AgentAttachment[], options?: CodexRunOptions): Promise<void>;
+export declare function startCodexThread(emit: AgentEmit, cwd?: string): Promise<Json>;
+export declare function resumeCodexThread(emit: AgentEmit, threadId: string, cwd?: string): Promise<{
+    thread: {};
+    messages: AgentHistoryMessage[];
+}>;
+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;
+}>;
+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: AgentHistoryMessage[];
+}>;
+export declare function verifyCodexThreadWorkspace(emit: AgentEmit, threadId: string, cwd: string): Promise<void>;
+export declare function archiveCodexThread(emit: AgentEmit, threadId: string, cwd?: string): Promise<void>;
+export declare function runClaudeTurn(prompt: string, emit: AgentEmit, attachments?: AgentAttachment[], options?: ClaudeRunOptions): Promise<void>;
+export declare function summarizeCodexThread(thread: unknown): {
+    id: string;
+    sessionId: string;
+    preview: string;
+    name: string | null;
+    cwd: string;
+    status: string;
+    source: unknown;
+    threadSource: unknown;
+    createdAt: number;
+    updatedAt: number;
+};
+export {};