@evandu/super-pi 0.1.131 → 0.1.132

package/dist/client/index.html

@@ -8,8 +8,8 @@
     <link rel="alternate icon" href="/favicon.ico" />
     <link rel="apple-touch-icon" href="/favicon.svg" />
     <title>Super Pi</title>
-    <script type="module" crossorigin src="/assets/index-BApJ3Zbq.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-CXB6U5mz.css">
+    <script type="module" crossorigin src="/assets/index-ChyemF2I.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-D3MEG8uH.css">
   </head>
   <body>
     <div id="root"></div>

package/dist/server/application/feishu-service.d.ts

@@ -0,0 +1,132 @@
+import { FeishuCli } from "../feishu-cli.js";
+/**
+ * The largest request the Feishu endpoint accepts.
+ *
+ * The Markdown of a document rides in the request body, so the cap is generous for a document and
+ * small enough that a runaway paste is refused rather than accepted.
+ */
+export declare const MAX_FEISHU_REQUEST_BYTES: number;
+/**
+ * WHAT THE PANEL NEEDS TO SHOW, in words a person can act on.
+ */
+export type FeishuStatus = {
+    /** Whether the official CLI is on this machine at all. */
+    installed: boolean;
+    version?: string;
+    /** The application the CLI is configured with, when it has one. */
+    appId?: string;
+    /** Whether a person has authorized the CLI to act as them. */
+    userReady: boolean;
+    /** Whether the CLI can act as the application itself. */
+    botReady: boolean;
+    /** The identity the CLI will use by default. */
+    identity?: "user" | "bot";
+    /** Whether the agent can read and write documents right now. */
+    connected: boolean;
+    /** What to do next, in one sentence. */
+    message: string;
+};
+/** The outcome of starting the connect flow. */
+export type FeishuConnectResult = {
+    ok: boolean;
+    /** Which step the person is on: creating an application, or authorizing their account. */
+    step?: "app" | "login";
+    /** The URL to open in a browser. */
+    verificationUri?: string;
+    /** The device code, kept server-side until the person says they are done. */
+    deviceCode?: string;
+    message: string;
+    /** Feishu's own "what to do about it", when there was one. */
+    hint?: string;
+};
+/**
+ * THE FEISHU SERVICE: what an agent can do with the cloud documents of a Feishu enterprise.
+ *
+ * IT OWNS NO CREDENTIAL. The official CLI owns them, in the OS keychain, and this service only
+ * runs commands. That is the whole point of going through the CLI: Super Pi never sees an App
+ * Secret, never sees a user token, and never writes a credential file to disk.
+ */
+export declare class FeishuService {
+    private readonly cli;
+    /** The device code of a login that is waiting for the person to authorize it. */
+    private pendingDeviceCode?;
+    constructor(cli?: FeishuCli);
+    /**
+     * WHAT THE CLI CAN DO RIGHT NOW.
+     *
+     * The three states a person can be in, and what each one means for the agent:
+     *
+     * - The CLI is not installed: nothing works, and the fix is one command.
+     * - The CLI has no application: `config init --new` creates one through a browser confirmation,
+     *   so the developer console is never visited.
+     * - The CLI has an application but no person logged in: the agent can still act as the
+     *   application, but it cannot reach that person's own documents until they authorize it.
+     */
+    status(): Promise<FeishuStatus>;
+    /**
+     * STARTS THE CONNECT FLOW.
+     *
+     * Two steps, and which one runs is decided by what the CLI already has:
+     *
+     * - No application: `config init --new` registers one through a browser confirmation. It BLOCKS
+     *   until the person confirms, so it runs in the background and the URL is taken from its output.
+     * - An application but no person: `auth login --no-wait --json` asks for a device code and hands
+     *   back the URL to open. The code is kept here until the person says they are done.
+     */
+    connect(): Promise<FeishuConnectResult>;
+    /**
+     * FINISHES THE LOGIN, once the person says they authorized it.
+     *
+     * The device code is handed back to the CLI, which completes the exchange and stores the token
+     * in the keychain. Super Pi never sees the token itself.
+     */
+    completeConnect(): Promise<FeishuConnectResult>;
+    /**
+     * READS A DOCUMENT.
+     *
+     * The CLI resolves a knowledge-base link itself, so a `/wiki/` URL is passed through untouched -
+     * and it answers with Markdown, which is the shape a model wants.
+     */
+    read(input: {
+        url: string;
+    }): Promise<{
+        documentId?: string;
+        revisionId?: number;
+        title?: string;
+        url: string;
+        format: "markdown";
+        content: string;
+    }>;
+    /**
+     * WRITES A DOCUMENT.
+     *
+     * THREE MODES, and the difference between them is who decides what survives:
+     *
+     * - `create` makes a new document. Nothing can be lost, because nothing was there.
+     * - `append` adds to the end. Nothing can be lost either.
+     * - `replace` replaces the whole document. This one CAN lose a person's work, so it needs the
+     *   revision the caller read - the same rule the file panel's write lives by, and for the same
+     *   reason: an agent told to "把这份报告改成正式版" would otherwise destroy a hand edit made an
+     *   hour ago, with no refusal and no warning.
+     *
+     * THE REVISION IS THE ETAG. The CLI passes it as the base revision of the edit, and Feishu
+     * refuses the edit when the document has moved on - so the check is enforced by the API rather
+     * than by a comparison Super Pi makes and then has to keep honest.
+     */
+    write(input: {
+        url?: string;
+        content: string;
+        mode?: "create" | "append" | "replace";
+        title?: string;
+        baseRevisionId?: string;
+    }): Promise<{
+        documentId?: string;
+        revisionId?: number;
+        url?: string;
+        mode: "create" | "append" | "replace";
+    }>;
+    /**
+     * THE TOOL CALL, as the extension sends it.
+     */
+    tool(body: unknown): Promise<unknown>;
+}

package/dist/server/application/feishu-service.js

@@ -0,0 +1,264 @@
+import { FeishuCli, FeishuCliError, errorHint, errorMessage } from "../feishu-cli.js";
+/**
+ * The largest request the Feishu endpoint accepts.
+ *
+ * The Markdown of a document rides in the request body, so the cap is generous for a document and
+ * small enough that a runaway paste is refused rather than accepted.
+ */
+export const MAX_FEISHU_REQUEST_BYTES = 4 * 1024 * 1024;
+/**
+ * THE FEISHU SERVICE: what an agent can do with the cloud documents of a Feishu enterprise.
+ *
+ * IT OWNS NO CREDENTIAL. The official CLI owns them, in the OS keychain, and this service only
+ * runs commands. That is the whole point of going through the CLI: Super Pi never sees an App
+ * Secret, never sees a user token, and never writes a credential file to disk.
+ */
+export class FeishuService {
+    cli;
+    /** The device code of a login that is waiting for the person to authorize it. */
+    pendingDeviceCode;
+    constructor(cli = new FeishuCli()) {
+        this.cli = cli;
+    }
+    /**
+     * WHAT THE CLI CAN DO RIGHT NOW.
+     *
+     * The three states a person can be in, and what each one means for the agent:
+     *
+     * - The CLI is not installed: nothing works, and the fix is one command.
+     * - The CLI has no application: `config init --new` creates one through a browser confirmation,
+     *   so the developer console is never visited.
+     * - The CLI has an application but no person logged in: the agent can still act as the
+     *   application, but it cannot reach that person's own documents until they authorize it.
+     */
+    async status() {
+        const status = await this.cli.status();
+        if (!status.installed) {
+            return {
+                installed: false,
+                userReady: false,
+                botReady: false,
+                connected: false,
+                message: "没有检测到官方飞书 CLI（lark-cli）。请先在终端运行 npm i -g @larksuite/cli 装上它，再回到这里点「连接飞书账号」。如果已经装了但 Super Pi 找不到（两边的 PATH 不一样），用环境变量 SUPER_PI_FEISHU_CLI 指向它的完整路径再重启 Super Pi。",
+            };
+        }
+        if (!status.appId) {
+            return {
+                installed: true,
+                ...(status.version ? { version: status.version } : {}),
+                userReady: false,
+                botReady: false,
+                connected: false,
+                message: "飞书 CLI 已就绪，但还没有应用。点「连接飞书账号」，它会给你一个浏览器链接，确认之后应用就建好了——不用去开发者后台注册。",
+            };
+        }
+        if (!status.userReady) {
+            return {
+                installed: true,
+                ...(status.version ? { version: status.version } : {}),
+                appId: status.appId,
+                userReady: false,
+                botReady: status.botReady,
+                connected: false,
+                ...(status.identity ? { identity: status.identity } : {}),
+                message: "应用已配置，但还没有登录你的账号。点「连接飞书账号」用浏览器授权，授权之后 Agent 就能以你的身份读写你自己的文档，不用逐篇加协作者。",
+            };
+        }
+        return {
+            installed: true,
+            ...(status.version ? { version: status.version } : {}),
+            appId: status.appId,
+            userReady: true,
+            botReady: status.botReady,
+            connected: true,
+            identity: status.identity ?? "user",
+            message: "已连接：Agent 会以你的身份读写飞书云文档。",
+        };
+    }
+    /**
+     * STARTS THE CONNECT FLOW.
+     *
+     * Two steps, and which one runs is decided by what the CLI already has:
+     *
+     * - No application: `config init --new` registers one through a browser confirmation. It BLOCKS
+     *   until the person confirms, so it runs in the background and the URL is taken from its output.
+     * - An application but no person: `auth login --no-wait --json` asks for a device code and hands
+     *   back the URL to open. The code is kept here until the person says they are done.
+     */
+    async connect() {
+        const status = await this.status();
+        if (!status.installed) {
+            return { ok: false, message: status.message };
+        }
+        if (!status.appId) {
+            const verificationUri = await this.cli.startAppCreation();
+            return {
+                ok: true,
+                step: "app",
+                ...(verificationUri ? { verificationUri } : {}),
+                message: verificationUri
+                    ? "在浏览器里打开这个链接确认一下，应用就建好了（CLI 会把应用和凭据存进系统钥匙串）。确认完点「我已完成」。"
+                    : "CLI 没有打印出链接。请在终端里运行 lark-cli config init --new，按提示扫码确认，然后回到这里点「连接飞书账号」。",
+            };
+        }
+        try {
+            const login = await this.cli.beginLogin();
+            this.pendingDeviceCode = login.deviceCode;
+            return {
+                ok: true,
+                step: "login",
+                ...(login.verificationUri ? { verificationUri: login.verificationUri } : {}),
+                deviceCode: login.deviceCode,
+                message: login.verificationUri
+                    ? "在浏览器里打开这个链接，用你的飞书账号确认授权，然后点「我已完成」。"
+                    : "CLI 已经发起设备码授权。请在浏览器里确认，然后点「我已完成」。",
+            };
+        }
+        catch (error) {
+            return { ok: false, message: messageOf(error), ...(hintOf(error) ? { hint: hintOf(error) } : {}) };
+        }
+    }
+    /**
+     * FINISHES THE LOGIN, once the person says they authorized it.
+     *
+     * The device code is handed back to the CLI, which completes the exchange and stores the token
+     * in the keychain. Super Pi never sees the token itself.
+     */
+    async completeConnect() {
+        if (!this.pendingDeviceCode) {
+            return { ok: false, message: "没有待完成的登录。点「连接飞书账号」重新开始。" };
+        }
+        const deviceCode = this.pendingDeviceCode;
+        this.pendingDeviceCode = undefined;
+        try {
+            const envelope = await this.cli.completeLogin(deviceCode);
+            if (envelope.ok === false) {
+                return { ok: false, message: errorMessage(envelope), ...(errorHint(envelope) ? { hint: errorHint(envelope) } : {}) };
+            }
+            return { ok: true, message: "已连接。现在 Agent 能以你的身份读写飞书云文档了。" };
+        }
+        catch (error) {
+            return { ok: false, message: messageOf(error), ...(hintOf(error) ? { hint: hintOf(error) } : {}) };
+        }
+    }
+    /**
+     * READS A DOCUMENT.
+     *
+     * The CLI resolves a knowledge-base link itself, so a `/wiki/` URL is passed through untouched -
+     * and it answers with Markdown, which is the shape a model wants.
+     */
+    async read(input) {
+        const document = await this.cli.fetchDocument(input.url);
+        return {
+            ...(document.documentId ? { documentId: document.documentId } : {}),
+            ...(document.revisionId !== undefined ? { revisionId: document.revisionId } : {}),
+            ...(document.title ? { title: document.title } : {}),
+            url: input.url,
+            format: "markdown",
+            content: document.content,
+        };
+    }
+    /**
+     * WRITES A DOCUMENT.
+     *
+     * THREE MODES, and the difference between them is who decides what survives:
+     *
+     * - `create` makes a new document. Nothing can be lost, because nothing was there.
+     * - `append` adds to the end. Nothing can be lost either.
+     * - `replace` replaces the whole document. This one CAN lose a person's work, so it needs the
+     *   revision the caller read - the same rule the file panel's write lives by, and for the same
+     *   reason: an agent told to "把这份报告改成正式版" would otherwise destroy a hand edit made an
+     *   hour ago, with no refusal and no warning.
+     *
+     * THE REVISION IS THE ETAG. The CLI passes it as the base revision of the edit, and Feishu
+     * refuses the edit when the document has moved on - so the check is enforced by the API rather
+     * than by a comparison Super Pi makes and then has to keep honest.
+     */
+    async write(input) {
+        const mode = input.mode ?? (input.url ? "append" : "create");
+        const content = String(input.content ?? "");
+        if (!content.trim())
+            throw new Error("要写入的内容是空的。");
+        if (mode === "create") {
+            const title = input.title?.trim() || titleFromMarkdown(content);
+            const created = await this.cli.createDocument(title, content);
+            return {
+                ...(created.documentId ? { documentId: created.documentId } : {}),
+                ...(created.revisionId !== undefined ? { revisionId: created.revisionId } : {}),
+                ...(created.url ? { url: created.url } : {}),
+                mode,
+            };
+        }
+        if (!input.url)
+            throw new Error("追加或覆盖需要给出文档链接或 token。");
+        if (mode === "replace") {
+            if (!input.baseRevisionId) {
+                throw new Error("覆盖前需要确认文档版本：先用 feishu_doc_read 读一次这篇文档，把它返回的 revisionId 作为 baseRevisionId 传入。覆盖会清空整篇文档，必须先看过。");
+            }
+            const revision = Number(input.baseRevisionId);
+            if (!Number.isFinite(revision)) {
+                throw new Error(`baseRevisionId 不是有效的版本号：${input.baseRevisionId}`);
+            }
+            const updated = await this.cli.updateDocument(input.url, "overwrite", content, revision);
+            return {
+                ...(updated.revisionId !== undefined ? { revisionId: updated.revisionId } : {}),
+                url: input.url,
+                mode,
+            };
+        }
+        const updated = await this.cli.updateDocument(input.url, "append", content);
+        return {
+            ...(updated.revisionId !== undefined ? { revisionId: updated.revisionId } : {}),
+            url: input.url,
+            mode,
+        };
+    }
+    /**
+     * THE TOOL CALL, as the extension sends it.
+     */
+    async tool(body) {
+        const request = (body ?? {});
+        const action = String(request.action ?? "read");
+        if (action === "read") {
+            return this.read({ url: String(request.url ?? "") });
+        }
+        if (action === "write") {
+            const mode = request.mode === "create" || request.mode === "append" || request.mode === "replace" ? request.mode : undefined;
+            return this.write({
+                ...(request.url ? { url: String(request.url) } : {}),
+                content: String(request.content ?? ""),
+                ...(mode ? { mode } : {}),
+                ...(request.title ? { title: String(request.title) } : {}),
+                ...(request.baseRevisionId ? { baseRevisionId: String(request.baseRevisionId) } : {}),
+            });
+        }
+        throw new Error(`未知的飞书工具操作：${action}`);
+    }
+}
+/** The message of a failure, whatever shape the failure has. */
+function messageOf(error) {
+    if (error instanceof FeishuCliError)
+        return error.message;
+    if (error instanceof Error)
+        return error.message;
+    return String(error);
+}
+/** The hint of a failure, when it carries one. */
+function hintOf(error) {
+    return error instanceof FeishuCliError ? error.hint : undefined;
+}
+/**
+ * A TITLE FROM THE CONTENT, for a document created without one.
+ *
+ * The first heading is what a person would have called it, and a generated title is better than
+ * "未命名文档" only when there is something to take.
+ */
+function titleFromMarkdown(content) {
+    for (const line of content.split("\n")) {
+        const heading = /^#{1,6}\s+(.+?)\s*$/.exec(line.trim());
+        if (heading?.[1])
+            return heading[1].slice(0, 800);
+    }
+    const firstLine = content.split("\n").map((line) => line.trim()).find((line) => line.length > 0);
+    return (firstLine ? firstLine.slice(0, 800) : "未命名文档");
+}

package/dist/server/application/scheduled-task-service.d.ts

@@ -0,0 +1,164 @@
+import type { EventBroadcaster } from "../server-context.js";
+import type { Store } from "../store.js";
+import { describeSchedule, type ScheduledTask, type ScheduleSpec } from "../scheduled-tasks.js";
+import type { ModelSelection } from "../types.js";
+import type { ConversationService } from "./conversation-service.js";
+import type { RunService } from "./run-service.js";
+/** The constructor's last parameter: the only seams this service admits. */
+export type ScheduledTaskServiceOptions = {
+    /**
+     * The TEST SEAM for the clock: how often the sweep runs. Production never passes this and gets the
+     * fifteen-second sweep; a test passes a few milliseconds and waits for real time instead of
+     * faking timers - the same role `sessionFactory` plays in `PiRpcRuntime`.
+     */
+    sweepIntervalMs?: number;
+};
+/** What a caller wants a task to be. Everything but the id and the bookkeeping is optional. */
+export type ScheduledTaskInput = {
+    name?: string;
+    prompt?: string;
+    schedule?: unknown;
+    workspaceId?: string;
+    model?: ModelSelection | null;
+    agentId?: string | null;
+    enabled?: boolean;
+};
+/**
+ * THE SCHEDULED TASKS SERVICE: the list, the clock, and the runs.
+ *
+ * WHAT LIVES HERE, AND WHY NOT IN THE STORE. The store owns the record and the disk; this owns the
+ * clock and the act of running. Keeping the two apart is what lets the store stay a thing that can be
+ * opened, repaired and closed without a timer running behind it - and it is why a scheduled task
+ * survives a restart as a RECORD while the thing that fires it is built fresh from that record.
+ */
+export declare class ScheduledTaskService {
+    private readonly store;
+    private readonly runService;
+    private readonly conversationService;
+    private readonly broadcaster;
+    /** The runs currently in flight, by task id. A task in here is not fired again. */
+    private readonly inFlight;
+    private timer?;
+    private stopped;
+    constructor(store: Store, runService: RunService, conversationService: ConversationService, broadcaster: EventBroadcaster, options?: ScheduledTaskServiceOptions);
+    private readonly sweepIntervalMs;
+    /**
+     * Starts the clock.
+     *
+     * `unref()` so the sweep never holds the process open: the shutdown sequence closes the server and
+     * the store, and a pending interval would keep the process alive after that, which is the difference
+     * between a server that exits and one that has to be killed.
+     */
+    start(): void;
+    /**
+     * Stops the clock and waits for whatever is running.
+     *
+     * The in-flight runs are NOT aborted: a task that is halfway through its answer is a real answer in
+     * a real conversation, and killing it because the server is shutting down would throw that work
+     * away. The sweep stops, the runs finish, and the next start picks the schedule up from what is on
+     * disk.
+     */
+    stop(): Promise<void>;
+    /** Every task on record, newest first. */
+    list(): ScheduledTask[];
+    /** The tasks of ONE workspace, which is what the panel shows. */
+    listForWorkspace(workspaceId: string | undefined): ScheduledTask[];
+    /**
+     * The task, if it belongs to THIS workspace - and a plain "not found" if it does not.
+     *
+     * WHY THE OWNERSHIP CHECK IS HERE, IN THE SERVICE. A task is a thing that RUNS in a workspace: it
+     * opens its conversation there, uses that workspace's defaults and its tools. A caller in another
+     * workspace cannot even list these tasks - `listForWorkspace` is the scoped read - so it must not
+     * be able to change or delete them either. Before this, `update` and `delete` acted on an id alone:
+     * a task created from workspace B could be rewritten and then deleted by a conversation in
+     * workspace A, and it STILL RAN in B, so A's prompt executed inside B with B's model and B's tools
+     * - an invisible cross-workspace write (measured by scripts/scheduled-task-scope.test.mjs, ledger
+     * TEST-026).
+     *
+     * THE REFUSAL DOES NOT SAY WHERE IT IS. "Not found" is the whole answer: a caller must not be able
+     * to learn that a task exists in a workspace it cannot see.
+     */
+    requireForWorkspace(id: string, workspaceId: string): ScheduledTask;
+    /**
+     * Creates a task.
+     *
+     * `createdBy` is recorded because the two kinds are not the same thing to a reader: a task the user
+     * asked for and a task an agent invented look identical in the list, and the difference is exactly
+     * what a person wants to know before they delete it.
+     */
+    create(input: ScheduledTaskInput, createdBy: "user" | "agent"): Promise<ScheduledTask>;
+    /**
+     * Changes a task.
+     *
+     * EVERY CHANGE RECOMPUTES `nextRunAt`, because a task whose prompt was edited an hour before its
+     * slot must not fire at the old slot with the old schedule - and a task whose schedule was edited
+     * must not keep the old next time. The one exception is a manual trigger, which is not a change at
+     * all: it runs the task once and leaves the clock where it was.
+     */
+    update(id: string, input: ScheduledTaskInput): Promise<ScheduledTask>;
+    /** Turns a task on or off. */
+    setEnabled(id: string, enabled: boolean): Promise<ScheduledTask>;
+    /** Removes a task. Its conversation stays: it holds the answers the task produced. */
+    remove(id: string): Promise<void>;
+    /**
+     * Runs a task NOW, once.
+     *
+     * The clock is untouched: a manual run does not make the next scheduled run earlier or later, and it
+     * does not count as the task having fired. This is the difference between 「先试一次」 and 「改一下周期」,
+     * and conflating them would make 「先试一次」 silently rewrite the user's schedule.
+     *
+     * THE ACK RETURNS BEFORE THE RUN FINISHES. The run itself takes as long as a model turn takes -
+     * seconds, usually, sometimes minutes - and a command that waited for it would hold the socket's
+     * whole command chain hostage for that long. The outcome is not lost: it lands in `lastRunStatus`
+     * and arrives at the panel through the ordinary state broadcast, where a person reads it.
+     */
+    trigger(id: string): Promise<void>;
+    /**
+     * The sweep: every task whose moment has come runs once.
+     *
+     * The tasks that are due are collected BEFORE any of them runs, and each one advances its own
+     * `nextRunAt` before it runs - so a task that takes three minutes cannot be fired again by the next
+     * sweep, and two sweeps can never both pick up the same task.
+     */
+    private sweep;
+    /**
+     * THE ACTUAL RUN, for both the clock and the button.
+     *
+     * The task gets its OWN conversation, created on the first run, and the prompt is sent into it
+     * verbatim as a user message - the same path a person's own message takes. That sameness is the point:
+     * a scheduled task has no special powers, so it cannot do anything a message could not, and it gets
+     * the same model, the same tools, the same memory.
+     */
+    private fire;
+    /** The body of a run: get a conversation, put the prompt into it, remember how it went. */
+    private runTask;
+    /**
+     * The conversation the task runs in, created the first time it is needed.
+     *
+     * LAZY, so that creating a task does not create a conversation nobody has spoken in. The name says
+     * what the conversation is, because it appears in the conversation list like any other and the user
+     * has to be able to tell it apart from their own work.
+     */
+    private ensureConversation;
+    /**
+     * Puts the task's model and agent on its conversation.
+     *
+     * EVERY RUN, not only the first: the user can change the model in the panel, and the next run is the
+     * one that has to use it. A failure here is the task's failure - a model that Pi no longer offers
+     * cannot be silently ignored, because the run would then happen on some other model and the panel
+     * would say it succeeded.
+     */
+    private applyConfiguration;
+    /** Writes down how the run went, and tells the panel. */
+    private record;
+    /** The task, or a refusal in words the reader can act on. */
+    private require;
+}
+/**
+ * The schedule in words, for the text an agent reads back after creating a task.
+ *
+ * Exported from here rather than from `scheduled-tasks.ts` so that the HTTP layer and the WS layer
+ * say the same thing about one schedule.
+ */
+export { describeSchedule };
+export type { ScheduledTask, ScheduleSpec };