@evandu/super-pi 0.1.131 → 0.1.133

package/dist/server/runtime.d.ts

@@ -164,7 +164,11 @@ export interface AnswerInput {
     onToolPreparing?(call: ToolCallPreparing): void;
     /** Called while the primary model is emitting reasoning, so the UI can show live progress. A call means
      *  the model is STILL THINKING - there is no separate flag, because Pi does not send one. */
-    onThinking?(delta: string): void;
+    /** Called while the primary model is emitting reasoning, so the UI can show live progress. A call means
+     *  the model is STILL THINKING - there is no separate flag, because Pi does not send one.
+     *  The handler may be async: the reasoning signal is the same "the model is producing" signal as
+     *  a text delta, and the caller waits for it so the state it writes is ordered with the delta. */
+    onThinking?(delta: string): void | Promise<void>;
     /** Called when the reasoning phase ends - the only signal that it has. */
     onThinkingEnd?(): void;
 }
@@ -517,6 +521,14 @@ export declare function taskExtensionPath(from?: string): string;
  * from `import.meta.dirname` reach the repository root both after `tsc -b` and under `tsx watch`.
  */
 export declare function documentExtensionPath(from?: string): string;
+/**
+ * The Feishu extension's file, resolved the same way the document extension's is.
+ *
+ * Named on both sides of the wire rather than imported by the extension, for the reason every one
+ * of these names is written out twice: `agents/` is loaded by Pi's module loader and `src/` by
+ * tsc, so a relative import across the two would resolve differently under each.
+ */
+export declare function feishuExtensionPath(from?: string): string;
 export declare class PiRpcRuntime implements AgentRuntime {
     private readonly sessionDir;
     /**
@@ -552,6 +564,12 @@ export declare class PiRpcRuntime implements AgentRuntime {
     private readonly options;
     private memory?;
     setMemory(memory: ActiveMemory): void;
+    /**
+     * The memory and knowledge credentials minted for each LIVE session, so they can be released when
+     * the session goes. A credential whose session is gone must not keep working - that is exactly the
+     * shape of a secret with no owner.
+     */
+    private readonly sessionExtensionTokens;
     private knowledge?;
     setKnowledge(knowledge: KnowledgeBase): void;
     private readonly runs;
@@ -642,6 +660,8 @@ export declare class PiRpcRuntime implements AgentRuntime {
     private warnedMissingExtension;
     /** Latches the "the document extension is missing" warning, for the same reason. */
     private warnedMissingDocumentExtension;
+    /** Latches the "the Feishu extension is missing" warning, for the same reason. */
+    private warnedMissingFeishuExtension;
     /** Latches the "Pi's SDK is not installed" warning, for the same reason. */
     private warnedMissingSdk;
     /**
@@ -709,6 +729,7 @@ export declare class PiRpcRuntime implements AgentRuntime {
         questionEndpoint?: string;
         toolsEndpoint?: string;
         documentsEndpoint?: string;
+        scheduledTaskEndpoint?: string;
         uploadsDir?: string;
         sessionFactory?: PiSessionFactory;
         sessionMode?: "sdk" | "oneshot";
@@ -804,6 +825,16 @@ export declare class PiRpcRuntime implements AgentRuntime {
      * runtime with no document endpoint mounts nothing rather than a tool whose every call fails.
      */
     private documentExtensionArgs;
+    /**
+     * The Feishu extension's spawn argument.
+     *
+     * MOUNTED UNCONDITIONALLY, for the same reason the document tools are: the endpoint is the gate,
+     * and the extension registers nothing without it. The credential is NOT the gate - a user who
+     * has not configured an application yet still gets the tools, because the error those tools
+     * return is the one that tells the user what to do, and a tool that is simply absent cannot say
+     * anything at all.
+     */
+    private feishuExtensionArgs;
     /**
      * The five values the extension reads out of its own environment. See `task-tool.ts` for why they are
      * written out on both sides rather than imported.
@@ -820,6 +851,21 @@ export declare class PiRpcRuntime implements AgentRuntime {
      * The TODO ENDPOINT is the one value here that is NOT per-turn derived from disk: it is this server's
      * own address, so it is the same string on every turn and is read once from the constructor's options.
      */
+    /**
+     * THE MEMORY AND KNOWLEDGE CREDENTIALS FOR A NEW SESSION.
+     *
+     * Both extensions read their environment ONCE, when they are loaded, so these are minted where the
+     * session is born - the same place, and for the same reason, as the session's capability. The
+     * one-shot path has always minted them (per turn); the session path minted none, so the memory and
+     * knowledge extensions returned before registering a tool or injecting a prompt, and both features
+     * were missing in production - the SDK session path is the DEFAULT backend, and only the test
+     * scripts take the one-shot path (ledger TEST-039).
+     *
+     * The endpoints are published as global environment variables (index.ts), and they are repeated
+     * here so the extension's contract is stated in one place: an endpoint and a credential travel
+     * together, and the credential is what proves the caller.
+     */
+    private mintSessionExtensionTokens;
     /**
      * The environment Super Pi's extensions read when they are loaded.
      *

package/dist/server/runtime.js

@@ -4,6 +4,7 @@ export { RpcChannel } from "./rpc-channel.js";
 import { randomUUID } from "node:crypto";
 import { KNOWLEDGE_IMPORT_TOOL_NAME, KNOWLEDGE_TOOL_NAME } from "./knowledge.js";
 import { DOCUMENT_READ_TOOL_NAME, DOCUMENT_WRITE_TOOL_NAME } from "./documents.js";
+import { FEISHU_READ_TOOL_NAME, FEISHU_WRITE_TOOL_NAME } from "./feishu-cli.js";
 import { WEB_FETCH_TOOL_NAME, WEB_SEARCH_TOOL_NAME } from "./web.js";
 import { existsSync } from "node:fs";
 import { mkdir, stat } from "node:fs/promises";
@@ -20,7 +21,7 @@ import { describeDeliveredUserMessage, describePiQueue, handleSessionEvent, Turn
 // paths recognise a delivery identically. Re-exported because they were part of this module's surface.
 export { describeDeliveredUserMessage, describePiQueue } from "./pi-session-events.js";
 import { createPiSession, createSdkCatalog, piSdkAvailable, resolveTranscriptFile, superPiExtensionPaths } from "./pi-session.js";
-import { TASK_CONVERSATION_ENV, TASK_DEPTH_ENV, TASK_ENDPOINT_ENV, TASK_EXEC_ENDPOINT_ENV, TASK_ROSTER_ENV, TASK_TOOL_NAME, TODO_ENDPOINT_ENV, TODO_TOOL_NAME, WORKFLOW_ENDPOINT_ENV, WORKFLOW_TOOL_NAME, RUN_ASYNC_TOOL_NAME, rosterPayload, } from "./task-tool.js";
+import { TASK_CONVERSATION_ENV, TASK_DEPTH_ENV, TASK_ENDPOINT_ENV, TASK_EXEC_ENDPOINT_ENV, TASK_ROSTER_ENV, TASK_TOOL_NAME, TODO_ENDPOINT_ENV, TODO_TOOL_NAME, SCHEDULED_TASK_ENDPOINT_ENV, SCHEDULED_TASK_TOOL_NAME, WORKFLOW_ENDPOINT_ENV, WORKFLOW_TOOL_NAME, RUN_ASYNC_TOOL_NAME, rosterPayload, } from "./task-tool.js";
 import { BLOCKING_UI_METHODS, EXTENSION_UI_METHODS, } from "./types.js";
 import { loadConversationImages } from "./upload.js";
 import { describeToolCall, describeToolCallArgs, describeToolCallInProgress, extractPartialResultText, extractToolResultText, readQuestionCall } from "./tool-calls.js";
@@ -248,6 +249,16 @@ export function taskExtensionPath(from = import.meta.dirname) {
 export function documentExtensionPath(from = import.meta.dirname) {
     return resolve(from, "../../agents/super-pi-documents/index.ts");
 }
+/**
+ * The Feishu extension's file, resolved the same way the document extension's is.
+ *
+ * Named on both sides of the wire rather than imported by the extension, for the reason every one
+ * of these names is written out twice: `agents/` is loaded by Pi's module loader and `src/` by
+ * tsc, so a relative import across the two would resolve differently under each.
+ */
+export function feishuExtensionPath(from = import.meta.dirname) {
+    return resolve(from, "../../agents/super-pi-feishu/index.ts");
+}
 /** Bridges a Pi session to Super Pi through Pi's documented JSONL RPC protocol. */
 /**
  * The tool's name as far as the stream has revealed it so far, or an empty string while the model is
@@ -278,6 +289,12 @@ export class PiRpcRuntime {
     options;
     memory;
     setMemory(memory) { this.memory = memory; }
+    /**
+     * The memory and knowledge credentials minted for each LIVE session, so they can be released when
+     * the session goes. A credential whose session is gone must not keep working - that is exactly the
+     * shape of a secret with no owner.
+     */
+    sessionExtensionTokens = new Map();
     knowledge;
     setKnowledge(knowledge) { this.knowledge = knowledge; }
     runs = new Map();
@@ -368,6 +385,8 @@ export class PiRpcRuntime {
     warnedMissingExtension = false;
     /** Latches the "the document extension is missing" warning, for the same reason. */
     warnedMissingDocumentExtension = false;
+    /** Latches the "the Feishu extension is missing" warning, for the same reason. */
+    warnedMissingFeishuExtension = false;
     /** Latches the "Pi's SDK is not installed" warning, for the same reason. */
     warnedMissingSdk = false;
     /**
@@ -453,7 +472,16 @@ export class PiRpcRuntime {
             // ABOUT that session and stop being true with it.
             this.sessionHosts.delete(conversationId);
             this.reportedSessionFiles.delete(conversationId);
-        }, options.sessionFactory ?? createPiSession, (conversationId) => mintCapability(conversationId), () => this.modelEpoch);
+            // The session held these credentials too, so they die with it.
+            const tokens = this.sessionExtensionTokens.get(conversationId);
+            if (tokens) {
+                if (tokens.memoryToken)
+                    this.memory?.release(tokens.memoryToken);
+                if (tokens.knowledgeToken)
+                    this.knowledge?.release(tokens.knowledgeToken);
+                this.sessionExtensionTokens.delete(conversationId);
+            }
+        }, options.sessionFactory ?? createPiSession, (conversationId) => mintCapability(conversationId), () => this.modelEpoch, (conversationId) => this.mintSessionExtensionTokens(conversationId));
     }
     /**
      * The configuration of the session that was built for a conversation, for tests to inspect.
@@ -577,6 +605,28 @@ export class PiRpcRuntime {
         }
         return ["--extension", path];
     }
+    /**
+     * The Feishu extension's spawn argument.
+     *
+     * MOUNTED UNCONDITIONALLY, for the same reason the document tools are: the endpoint is the gate,
+     * and the extension registers nothing without it. The credential is NOT the gate - a user who
+     * has not configured an application yet still gets the tools, because the error those tools
+     * return is the one that tells the user what to do, and a tool that is simply absent cannot say
+     * anything at all.
+     */
+    feishuExtensionArgs() {
+        if (!process.env.SUPER_PI_FEISHU_ENDPOINT)
+            return [];
+        const path = feishuExtensionPath();
+        if (!existsSync(path)) {
+            if (!this.warnedMissingFeishuExtension) {
+                this.warnedMissingFeishuExtension = true;
+                console.warn(`PiRpcRuntime: ${path} does not exist, so the primary agent cannot read or write Feishu cloud documents.`);
+            }
+            return [];
+        }
+        return ["--extension", path];
+    }
     /**
      * The five values the extension reads out of its own environment. See `task-tool.ts` for why they are
      * written out on both sides rather than imported.
@@ -593,6 +643,37 @@ export class PiRpcRuntime {
      * The TODO ENDPOINT is the one value here that is NOT per-turn derived from disk: it is this server's
      * own address, so it is the same string on every turn and is read once from the constructor's options.
      */
+    /**
+     * THE MEMORY AND KNOWLEDGE CREDENTIALS FOR A NEW SESSION.
+     *
+     * Both extensions read their environment ONCE, when they are loaded, so these are minted where the
+     * session is born - the same place, and for the same reason, as the session's capability. The
+     * one-shot path has always minted them (per turn); the session path minted none, so the memory and
+     * knowledge extensions returned before registering a tool or injecting a prompt, and both features
+     * were missing in production - the SDK session path is the DEFAULT backend, and only the test
+     * scripts take the one-shot path (ledger TEST-039).
+     *
+     * The endpoints are published as global environment variables (index.ts), and they are repeated
+     * here so the extension's contract is stated in one place: an endpoint and a credential travel
+     * together, and the credential is what proves the caller.
+     */
+    async mintSessionExtensionTokens(conversationId) {
+        const minted = {};
+        const env = {};
+        if (this.memory && (await this.memory.configuration()).enabled) {
+            minted.memoryToken = this.memory.issue(conversationId);
+            env.SUPER_PI_MEMORY_TOKEN = minted.memoryToken;
+            env.SUPER_PI_MEMORY_ENDPOINT = process.env.SUPER_PI_MEMORY_ENDPOINT ?? "";
+        }
+        if (this.knowledge && this.knowledge.enabled()) {
+            minted.knowledgeToken = this.knowledge.issue(conversationId);
+            env.SUPER_PI_KNOWLEDGE_TOKEN = minted.knowledgeToken;
+            env.SUPER_PI_KNOWLEDGE_ENDPOINT = process.env.SUPER_PI_KNOWLEDGE_ENDPOINT ?? "";
+        }
+        if (minted.memoryToken || minted.knowledgeToken)
+            this.sessionExtensionTokens.set(conversationId, minted);
+        return env;
+    }
     /**
      * The environment Super Pi's extensions read when they are loaded.
      *
@@ -612,6 +693,7 @@ export class PiRpcRuntime {
             [TASK_CONVERSATION_ENV]: conversationId,
             [TASK_DEPTH_ENV]: "0",
             [TODO_ENDPOINT_ENV]: this.options.todoEndpoint ?? "",
+            [SCHEDULED_TASK_ENDPOINT_ENV]: this.options.scheduledTaskEndpoint ?? "",
             [WORKFLOW_ENDPOINT_ENV]: this.options.workflowEndpoint ?? "",
             SUPER_PI_QUESTION_ENDPOINT: this.options.questionEndpoint ?? "",
             SUPER_PI_TOOLS_ENDPOINT: this.options.toolsEndpoint ?? "",
@@ -623,6 +705,11 @@ export class PiRpcRuntime {
             SUPER_PI_DOCUMENTS_ENDPOINT: this.options.documentsEndpoint ?? "",
             SUPER_PI_DOCUMENTS_CONVERSATION: conversationId,
             SUPER_PI_WEB_ENDPOINT: process.env.SUPER_PI_WEB_ENDPOINT ?? "",
+            // The Feishu tools' endpoint and the conversation they act for. The CREDENTIAL is not here:
+            // it is the session's own capability, the same value the task dispatch uses, because a
+            // second credential for one session would be a second thing to rotate and to release.
+            SUPER_PI_FEISHU_ENDPOINT: process.env.SUPER_PI_FEISHU_ENDPOINT ?? "",
+            SUPER_PI_FEISHU_CONVERSATION: conversationId,
         };
     }
     /**
@@ -865,13 +952,10 @@ export class PiRpcRuntime {
                 // pushes the terminal item when Pi settles, and the consumer below reads it. This promise
                 // waits for that signal, and the race with the prompt's own failure is what keeps a turn that
                 // never settles from hanging forever - a hung turn is a conversation that never answers.
-                await Promise.race([
-                    queue.settledSignal,
-                    // The safety net. A session that was aborted, or a Pi that died mid-turn, may never settle,
-                    // and the turn still has to end - otherwise the conversation is stuck on a turn that will
-                    // never produce anything and the next message can never be sent.
-                    new Promise((resolvePromise) => setTimeout(resolvePromise, 5_000)),
-                ]);
+                // `prompt()` only means Pi accepted the request. Do not end this generator on a wall-clock
+                // timeout: the session may still be streaming or executing a tool, and ending here drops
+                // subsequent events while falsely allowing the next prompt onto a busy session.
+                await queue.settledSignal;
                 traceLatency(conversation.id, "session.settled", latencyStartedAt);
                 // THE REVERT BOUNDARY, recorded at the same moment the one-shot path records it: the turn has
                 // settled, so every entry this turn wrote - the user message included - is in the transcript.
@@ -1055,7 +1139,7 @@ export class PiRpcRuntime {
      * because `toolFlags` treats an explicit false as outranking a host extra.
      */
     extensionToolNames() {
-        const names = [TASK_TOOL_NAME, TODO_TOOL_NAME, WORKFLOW_TOOL_NAME, RUN_ASYNC_TOOL_NAME, "question", "tool_register"];
+        const names = [TASK_TOOL_NAME, TODO_TOOL_NAME, WORKFLOW_TOOL_NAME, RUN_ASYNC_TOOL_NAME, SCHEDULED_TASK_TOOL_NAME, "question", "tool_register"];
         if (this.memory)
             names.push("memory", "skill_manage", "session_search");
         if (this.knowledge)
@@ -1067,6 +1151,12 @@ export class PiRpcRuntime {
         // would otherwise get a loaded-but-undeclared tool - broken with no error to explain it.
         if (this.options.documentsEndpoint)
             names.push(DOCUMENT_READ_TOOL_NAME, DOCUMENT_WRITE_TOOL_NAME);
+        // The Feishu tools are named whenever the endpoint is configured, for the same reason the
+        // document tools are: the endpoint is what decides whether the extension registers them, and
+        // an agent that declares `tools: {"*": false, read: true}` would otherwise get a
+        // loaded-but-undeclared tool - broken with no error to explain it.
+        if (process.env.SUPER_PI_FEISHU_ENDPOINT)
+            names.push(FEISHU_READ_TOOL_NAME, FEISHU_WRITE_TOOL_NAME);
         return names;
     }
     /**
@@ -1097,7 +1187,7 @@ export class PiRpcRuntime {
                 if (segment.kind === "text")
                     yield segment.text;
                 else if (segment.kind === "thinking")
-                    input.onThinking?.(segment.text);
+                    await input.onThinking?.(segment.text);
                 else
                     input.onThinkingEnd?.();
             }
@@ -1223,6 +1313,11 @@ export class PiRpcRuntime {
         const webExtension = resolve(import.meta.dirname, "../../agents/super-pi-web/index.ts");
         const webEnabled = !memoryReview && !knowledgeRerank && existsSync(webExtension) && !!process.env.SUPER_PI_WEB_ENDPOINT;
         const webArgs = webEnabled ? ["--extension", webExtension] : [];
+        // The Feishu tools are mounted for every ordinary turn, and NOT for a review or a rerank: a
+        // background reflection has no business reading a company's cloud documents, and a reranker
+        // must not be able to reach the tools it is ranking.
+        const feishuEnabled = !memoryReview && !knowledgeRerank && this.feishuExtensionArgs().length > 0;
+        const feishuArgs = feishuEnabled ? this.feishuExtensionArgs() : [];
         // The document tools are mounted for every ordinary turn, and NOT for a review or a rerank: a
         // background reflection has no business reading a PDF it was not asked about, and a reranker
         // must not be able to reach the tools it is ranking.
@@ -1232,7 +1327,7 @@ export class PiRpcRuntime {
         // conversation, so minting a second one for the same conversation would replace the first and
         // leave the task dispatch holding a token the server has already forgotten. Both the task
         // extension and the document extension therefore share this one value.
-        const oneShotCapability = (extensionArgs.length || documentsEnabled || webEnabled) ? mintCapability(conversation.id) : undefined;
+        const oneShotCapability = (extensionArgs.length || documentsEnabled || webEnabled || feishuEnabled) ? mintCapability(conversation.id) : undefined;
         // BOTH extension tools, or neither. Naming one while the other goes unmentioned would be a lie in a
         // different direction: Pi filters its registry through `--tools`, so an agent that declares
         // `tools: {"*": false, read: true}` gets whichever of the two is on this line and silently not the
@@ -1245,13 +1340,13 @@ export class PiRpcRuntime {
         // allowlist and naming a tool Pi has not registered would change the spawn line for every other
         // mode. The prompt asks for a bare JSON array and nothing else; if the model spends a turn on a
         // tool call anyway the reranker times out and falls back to the lexical order.
-        const agentArgs = memoryReview ? ["--no-extensions", "--no-skills", "--no-mcp", "--no-context-files", "--no-prompt-templates", "--tools", "memory,skill_manage,session_search"] : knowledgeRerank ? ["--no-extensions", "--no-skills", "--no-mcp", "--no-context-files", "--no-prompt-templates"] : await agentSpawnArgs(this.agents.promptDir, agent, { extraAllowedTools: [...(extensionArgs.length ? [TASK_TOOL_NAME, TODO_TOOL_NAME, WORKFLOW_TOOL_NAME, RUN_ASYNC_TOOL_NAME, "question", "tool_register"] : []), ...(memoryEnabled ? ["memory", "skill_manage", "session_search"] : []), ...(knowledgeEnabled ? [KNOWLEDGE_TOOL_NAME, KNOWLEDGE_IMPORT_TOOL_NAME] : []), ...(documentsEnabled ? [DOCUMENT_READ_TOOL_NAME, DOCUMENT_WRITE_TOOL_NAME] : []), ...(webEnabled ? [WEB_SEARCH_TOOL_NAME, WEB_FETCH_TOOL_NAME] : [])] });
+        const agentArgs = memoryReview ? ["--no-extensions", "--no-skills", "--no-mcp", "--no-context-files", "--no-prompt-templates", "--tools", "memory,skill_manage,session_search"] : knowledgeRerank ? ["--no-extensions", "--no-skills", "--no-mcp", "--no-context-files", "--no-prompt-templates"] : await agentSpawnArgs(this.agents.promptDir, agent, { extraAllowedTools: [...(extensionArgs.length ? [TASK_TOOL_NAME, TODO_TOOL_NAME, WORKFLOW_TOOL_NAME, RUN_ASYNC_TOOL_NAME, SCHEDULED_TASK_TOOL_NAME, "question", "tool_register"] : []), ...(memoryEnabled ? ["memory", "skill_manage", "session_search"] : []), ...(knowledgeEnabled ? [KNOWLEDGE_TOOL_NAME, KNOWLEDGE_IMPORT_TOOL_NAME] : []), ...(documentsEnabled ? [DOCUMENT_READ_TOOL_NAME, DOCUMENT_WRITE_TOOL_NAME] : []), ...(webEnabled ? [WEB_SEARCH_TOOL_NAME, WEB_FETCH_TOOL_NAME] : []), ...(feishuEnabled ? [FEISHU_READ_TOOL_NAME, FEISHU_WRITE_TOOL_NAME] : [])] });
         // Refused here, with the reason, rather than handed to the spawn: an ENOENT from `spawn` reads as
         // "the app is broken" and hides the one fact that matters, which is where it looked for Pi.
         if (!this.pi.found)
             throw new Error(this.pi.reason);
         // npm exposes global CLIs as .cmd shims on Windows; Node requires a shell to launch those shims.
-        const child = spawn(shellQuote(this.pi.command), ["--mode", "rpc", "--session-dir", this.sessionDir, "--session-id", conversation.id, ...extensionArgs, ...memoryArgs, ...knowledgeArgs, ...documentArgs, ...webArgs, ...agentArgs], {
+        const child = spawn(shellQuote(this.pi.command), ["--mode", "rpc", "--session-dir", this.sessionDir, "--session-id", conversation.id, ...extensionArgs, ...memoryArgs, ...knowledgeArgs, ...documentArgs, ...webArgs, ...feishuArgs, ...agentArgs], {
             cwd: childCwd,
             stdio: ["pipe", "pipe", "pipe"],
             shell: process.platform === "win32",
@@ -1259,7 +1354,7 @@ export class PiRpcRuntime {
             // every turn would silently replace the child's environment with whatever THIS process has at
             // spawn time. Inheriting is what an omitted `env` already does, so the two paths differ in nothing
             // but the four documented additions.
-            ...((extensionArgs.length || memoryEnabled || knowledgeEnabled || documentsEnabled || webEnabled) ? { env: { ...process.env, ...(oneShotCapability ? await this.oneShotExtensionEnv(conversation.id, oneShotCapability) : {}), ...(memoryEnabled ? {
+            ...((extensionArgs.length || memoryEnabled || knowledgeEnabled || documentsEnabled || webEnabled || feishuEnabled) ? { env: { ...process.env, ...(oneShotCapability ? await this.oneShotExtensionEnv(conversation.id, oneShotCapability) : {}), ...(memoryEnabled ? {
                         SUPER_PI_MEMORY_ENDPOINT: process.env.SUPER_PI_MEMORY_ENDPOINT,
                         SUPER_PI_MEMORY_TOKEN: memoryToken,
                         SUPER_PI_MEMORY_REVIEW: memoryReview ? "1" : "0",

package/dist/server/scheduled-tasks.d.ts

@@ -0,0 +1,101 @@
+import type { ModelSelection } from "./types.js";
+/**
+ * WHEN A SCHEDULED TASK RUNS.
+ *
+ * FOUR SHAPES, AND NOT A CRON EXPRESSION. A cron string would bring a parser, a timezone story and a
+ * daylight-saving story to a panel that runs on the same machine as the server - and the two shapes
+ * people actually ask for are "every N minutes" and "every day at HH:MM". The set is closed on purpose:
+ * a schedule that cannot be expressed here is not a schedule the panel can edit, and the panel is the
+ * only place a user can see what they are agreeing to.
+ *
+ * - `interval`: every N minutes. The interval is anchored on the last run, not on the wall clock, so a
+ *   task that takes four minutes to run does not slowly drift later every cycle.
+ * - `daily`: every day at a local `HH:MM`.
+ * - `weekly`: on the listed weekdays (0 = Sunday) at a local `HH:MM`.
+ * - `once`: at one instant. The task is finished after it fires.
+ *
+ * THE TIME IS LOCAL, not UTC and not a named zone, because the server and the panel are the same
+ * machine for every installation that exists. A "09:00" that means something different in the panel
+ * than in the scheduler would be the worst possible bug in this feature: it would fire at the wrong
+ * hour and look like it had fired at the right one.
+ */
+export type ScheduleSpec = {
+    kind: "interval";
+    everyMinutes: number;
+} | {
+    kind: "daily";
+    time: string;
+} | {
+    kind: "weekly";
+    weekdays: number[];
+    time: string;
+} | {
+    kind: "once";
+    at: number;
+};
+/**
+ * ONE SCHEDULED TASK: a prompt, a model to run it with, and when to run it.
+ *
+ * `conversationId` is the task's OWN conversation, created lazily on the first run. The task never runs
+ * in somebody else's conversation: a scheduled run that landed in the user's working session would
+ * interleave with what they were doing, and would change that session's model out from under it.
+ */
+export type ScheduledTask = {
+    id: string;
+    name: string;
+    /** The instruction, sent VERBATIM as the user message of the task's conversation. */
+    prompt: string;
+    /** The workspace the task belongs to: it decides the working directory and the defaults. */
+    workspaceId: string;
+    /** The task's own conversation, created on the first run. Absent until then. */
+    conversationId?: string;
+    /** Overrides the workspace's default agent. */
+    agentId?: string;
+    /** Overrides the workspace's default model. A `provider`/`modelId` PAIR, never half of one. */
+    model?: ModelSelection;
+    schedule: ScheduleSpec;
+    enabled: boolean;
+    /** When the task fires next, in epoch milliseconds. Absent for a finished one-shot task. */
+    nextRunAt?: number;
+    lastRunAt?: number;
+    lastRunStatus?: "completed" | "failed" | "skipped";
+    lastRunMessage?: string;
+    /** Whether a person or the agent created it. Both are editable by both. */
+    createdBy: "user" | "agent";
+    createdAt: number;
+    updatedAt: number;
+};
+/** The shortest interval a task may ask for. A one-minute floor is what makes a task a task. */
+export declare const MIN_INTERVAL_MINUTES = 1;
+/** The longest interval: a week. Anything longer is a calendar arrangement, not an interval. */
+export declare const MAX_INTERVAL_MINUTES: number;
+/**
+ * Reads a schedule out of whatever a caller sent, or explains why it cannot.
+ *
+ * THE SERVER OWNS THIS, and the extension on the other side of the wire deliberately does NOT have a
+ * copy of it. The extension hands over what the model wrote; this function decides what it means. A
+ * second implementation on the extension side would be a second opinion about the same wire, and the two
+ * would disagree the first time a model wrote a schedule in a shape one of them accepted and the other
+ * did not - with the model's mistake showing up as a server error it cannot explain.
+ */
+export declare function normalizeSchedule(raw: unknown): ScheduleSpec;
+/**
+ * WHEN THE TASK FIRES NEXT, given a moment to look forward from.
+ *
+ * `undefined` means "never again": a one-shot task whose moment has passed.
+ *
+ * The daily and weekly cases walk forward day by day in LOCAL time rather than adding 24 hours, so a
+ * schedule at 09:00 stays at 09:00 across a daylight-saving change instead of drifting to 08:00 or
+ * 10:00 for half the year.
+ */
+export declare function nextRunAt(spec: ScheduleSpec, from: number): number | undefined;
+/**
+ * THE SCHEDULE IN WORDS, for the panel and for the text the agent reads back.
+ *
+ * One implementation for both readers, because two descriptions of one schedule would eventually say
+ * two different things - and the agent's description is what the user is told when the agent says
+ * "I set up a daily task". If the two disagreed, the user would find out from the clock.
+ */
+export declare function describeSchedule(spec: ScheduleSpec): string;
+/** A moment as `YYYY-MM-DD HH:MM`, in local time. */
+export declare function formatMoment(ms: number): string;

package/dist/server/scheduled-tasks.js

@@ -0,0 +1,138 @@
+/** The shortest interval a task may ask for. A one-minute floor is what makes a task a task. */
+export const MIN_INTERVAL_MINUTES = 1;
+/** The longest interval: a week. Anything longer is a calendar arrangement, not an interval. */
+export const MAX_INTERVAL_MINUTES = 60 * 24 * 7;
+/**
+ * Reads a schedule out of whatever a caller sent, or explains why it cannot.
+ *
+ * THE SERVER OWNS THIS, and the extension on the other side of the wire deliberately does NOT have a
+ * copy of it. The extension hands over what the model wrote; this function decides what it means. A
+ * second implementation on the extension side would be a second opinion about the same wire, and the two
+ * would disagree the first time a model wrote a schedule in a shape one of them accepted and the other
+ * did not - with the model's mistake showing up as a server error it cannot explain.
+ */
+export function normalizeSchedule(raw) {
+    if (!raw || typeof raw !== "object")
+        throw new Error("周期必须是一个对象：{\"kind\":\"interval\",\"everyMinutes\":30} 这样写。");
+    const value = raw;
+    const kind = typeof value.kind === "string" ? value.kind.trim() : "";
+    if (kind === "interval") {
+        const everyMinutes = Number(value.everyMinutes);
+        if (!Number.isFinite(everyMinutes) || !Number.isInteger(everyMinutes))
+            throw new Error("每隔 N 分钟需要一个整数分钟数。");
+        if (everyMinutes < MIN_INTERVAL_MINUTES || everyMinutes > MAX_INTERVAL_MINUTES) {
+            throw new Error(`间隔分钟数要在 ${MIN_INTERVAL_MINUTES} 到 ${MAX_INTERVAL_MINUTES} 之间。`);
+        }
+        return { kind: "interval", everyMinutes };
+    }
+    if (kind === "daily")
+        return { kind: "daily", time: normalizeTime(value.time) };
+    if (kind === "weekly") {
+        const weekdays = normalizeWeekdays(value.weekdays);
+        return { kind: "weekly", weekdays, time: normalizeTime(value.time) };
+    }
+    if (kind === "once") {
+        const at = Number(value.at);
+        if (!Number.isFinite(at) || at <= 0)
+            throw new Error("一次性任务需要一个触发时刻（毫秒时间戳）。");
+        return { kind: "once", at };
+    }
+    throw new Error("周期只能是 interval（每隔 N 分钟）、daily（每天）、weekly（每周）或 once（仅一次）。");
+}
+/** `HH:MM`, twenty-four hour, leading zero or not. The only time shape this feature accepts. */
+function normalizeTime(raw) {
+    if (typeof raw !== "string")
+        throw new Error("触发时刻要写成 \"HH:MM\"，比如 \"09:00\"。");
+    const match = /^(\d{1,2}):(\d{2})$/.exec(raw.trim());
+    if (!match)
+        throw new Error("触发时刻要写成 \"HH:MM\"，比如 \"09:00\"。");
+    const hours = Number(match[1]);
+    const minutes = Number(match[2]);
+    if (hours > 23 || minutes > 59)
+        throw new Error("触发时刻不是一个真实的时间。");
+    return `${String(hours).padStart(2, "0")}:${String(minutes).padStart(2, "0")}`;
+}
+/** The weekdays of a weekly schedule, sorted and deduplicated. An empty list means every day. */
+function normalizeWeekdays(raw) {
+    if (!Array.isArray(raw))
+        throw new Error("每周任务需要给出星期几，比如 [1,3] 表示周一和周三。");
+    const days = Array.from(new Set(raw.map((item) => Number(item)).filter((item) => Number.isInteger(item) && item >= 0 && item <= 6)));
+    if (!days.length)
+        throw new Error("每周任务至少要有一天。");
+    return days.sort((a, b) => a - b);
+}
+/**
+ * WHEN THE TASK FIRES NEXT, given a moment to look forward from.
+ *
+ * `undefined` means "never again": a one-shot task whose moment has passed.
+ *
+ * The daily and weekly cases walk forward day by day in LOCAL time rather than adding 24 hours, so a
+ * schedule at 09:00 stays at 09:00 across a daylight-saving change instead of drifting to 08:00 or
+ * 10:00 for half the year.
+ */
+export function nextRunAt(spec, from) {
+    if (spec.kind === "interval")
+        return from + spec.everyMinutes * 60_000;
+    if (spec.kind === "once")
+        return spec.at > from ? spec.at : undefined;
+    if (spec.kind === "daily")
+        return nextDailyAt(spec.time, from);
+    return nextWeeklyAt(spec.weekdays, spec.time, from);
+}
+/** The next moment at `HH:MM` strictly after `from`, in local time. */
+function nextDailyAt(time, from) {
+    const [hours, minutes] = time.split(":").map(Number);
+    const candidate = new Date(from);
+    candidate.setHours(hours, minutes, 0, 0);
+    if (candidate.getTime() <= from)
+        candidate.setDate(candidate.getDate() + 1);
+    return candidate.getTime();
+}
+/**
+ * The next moment at `HH:MM` on one of `weekdays`, strictly after `from`, in local time.
+ *
+ * At most eight days are examined, which covers every weekday list including an empty one: an empty
+ * list means "every day", and the daily case is a special case of it.
+ */
+function nextWeeklyAt(weekdays, time, from) {
+    const days = weekdays.length ? weekdays : [0, 1, 2, 3, 4, 5, 6];
+    const [hours, minutes] = time.split(":").map(Number);
+    for (let offset = 0; offset <= 7; offset += 1) {
+        const candidate = new Date(from);
+        candidate.setDate(candidate.getDate() + offset);
+        candidate.setHours(hours, minutes, 0, 0);
+        if (candidate.getTime() <= from)
+            continue;
+        if (days.includes(candidate.getDay()))
+            return candidate.getTime();
+    }
+    // Unreachable: within eight days every weekday in a full week comes round. The fallback keeps the
+    // function total rather than returning `undefined` for a shape that cannot happen.
+    return nextDailyAt(time, from);
+}
+/**
+ * THE SCHEDULE IN WORDS, for the panel and for the text the agent reads back.
+ *
+ * One implementation for both readers, because two descriptions of one schedule would eventually say
+ * two different things - and the agent's description is what the user is told when the agent says
+ * "I set up a daily task". If the two disagreed, the user would find out from the clock.
+ */
+export function describeSchedule(spec) {
+    if (spec.kind === "interval")
+        return `每隔 ${spec.everyMinutes} 分钟`;
+    if (spec.kind === "daily")
+        return `每天 ${spec.time}`;
+    if (spec.kind === "weekly")
+        return `每周${spec.weekdays.map(weekdayName).join("、")} ${spec.time}`;
+    return `仅一次：${formatMoment(spec.at)}`;
+}
+/** 0 = Sunday, which is what `Date.getDay()` says. */
+function weekdayName(day) {
+    return ["日", "一", "二", "三", "四", "五", "六"][day] ?? "?";
+}
+/** A moment as `YYYY-MM-DD HH:MM`, in local time. */
+export function formatMoment(ms) {
+    const date = new Date(ms);
+    const pad = (value) => String(value).padStart(2, "0");
+    return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}`;
+}

package/dist/server/server-context.d.ts

@@ -42,6 +42,14 @@ export interface ServerContext {
     web?: import("./web.js").WebService;
     /** The agent-facing document tools. Optional so the server can start without them. */
     documentService?: import("./application/document-service.js").DocumentService;
+    /**
+     * THE FEISHU TOOLS.
+     *
+     * Optional because the credential may be missing, not because the feature may be missing: the
+     * service is always constructed, and a call made before the credential is configured is refused
+     * with the message that says what to do - which a missing service could not say.
+     */
+    feishu?: import("./application/feishu-service.js").FeishuService;
     paths: ServerPaths;
     store: Store;
     runtime: AgentRuntime;
@@ -55,6 +63,14 @@ export interface ServerContext {
     catalogService: CatalogService;
     /** The providers a person added through the settings window. */
     providerService: ProviderService;
+    /**
+     * The scheduled tasks and the clock behind them.
+     *
+     * In the context because TWO layers need it: the command handler routes the panel's five commands
+     * into it, and the HTTP layer exposes the agent-facing endpoint that lets a running turn create a
+     * task of its own.
+     */
+    scheduledTaskService?: import("./application/scheduled-task-service.js").ScheduledTaskService;
     execService: ExecService;
     toolRegistry: ToolRegistry;
     toolRunner: ToolRunner;