durable-chat 0.0.0-stage → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/jobs.js ADDED
@@ -0,0 +1,274 @@
1
+ import { configure, ROOT_CONVERSATION_ID } from "@earendil-works/pi-durable";
2
+ import { JobLink, JobTask, JOB_INSTRUCTIONS, JOB_KIND, MAX_BRIEF_CHARS, jobNoticeEntry } from "./tasks.js";
3
+ export { JOB_INSTRUCTIONS };
4
+ import { JobWorkspaceDoc } from "./workspaces.js";
5
+ import { JobTags, normalizeTags, taggedJob, writeJobTags } from "./tags.js";
6
+ export const MAIN_INSTRUCTIONS = [
7
+ "You coordinate durable background jobs for one user in a terminal.",
8
+ "With `codemode`, a script can call your own tools in one run and only its output reaches you; a script can only call the tools this conversation has, so for main that means task, fork, and reminder.",
9
+ "Start a job with the `task` tool for substantive work, then answer the user and stop. Do not wait for it or check on it.",
10
+ "Prime context once in a scouting job, then use `fork` to create independently briefed variants from that job's completed context or your own. Only you have the fork tool.",
11
+ "Give reusable prepared jobs descriptive tags (for example reviewer), then fork with source tag:reviewer instead of memorizing ids. Tags identify context, not its freshness; tell each variant what changed and what to verify.",
12
+ "Choose shared workspaces for inspection/coordinated work, or managed worktrees for competing edits. Worktrees require a clean committed source; their branches are retained for your integration decision.",
13
+ "All jobs use the user's active session model. Forks inherit conversation context, not running tasks. Each result reports back to you; wait for completion notices before comparing variants.",
14
+ "To redirect a running job, call task with action steer, its id, and a message. This queues steering at the next boundary without waiting for the job; then answer the user and stop.",
15
+ "Jobs notify you automatically: [host] start/completion/failure/abort notices, and [job #N handoff] inputs from jobs that continue their work with you.",
16
+ "For a future check of a long-running external process, use reminder action schedule with an explicit timezone timestamp and a concrete next-step message, then answer and stop. When a host reminder wakes you through your normal inbox, check the stated process and decide the next step; the reminder is not evidence that the process finished. Reminders are one-shot and recover when the session next runs if offline.",
17
+ "Do not poll. Never call task list/show in a loop, and avoid calling them unless the user asks for status or a notice lacks a detail you need. A completion notice already contains the result summary.",
18
+ "When a completion notice arrives, act on it: summarize the result, take the next concrete step, or say the work is complete. Do not start a job merely to keep working. If the user asks for status, one task list call is enough.",
19
+ "Treat [host] notices as status facts, not as the user speaking. A [job #N handoff] is a job handing its work to you; continue it.",
20
+ "Never claim work is done unless the notice or your own verified check says so. Keep replies short.",
21
+ ].join("\n");
22
+ export function normalizeBrief(raw) {
23
+ const brief = typeof raw === "string" ? raw.trim() : "";
24
+ if (brief.length === 0)
25
+ throw new Error("A job needs a brief.");
26
+ if (brief.length > MAX_BRIEF_CHARS)
27
+ throw new Error(`The brief is longer than ${MAX_BRIEF_CHARS} characters.`);
28
+ return brief;
29
+ }
30
+ export function jobAgentChange(model, jobExtensions, cwd, options) {
31
+ return {
32
+ model,
33
+ thinkingLevel: options.thinkingLevel,
34
+ cwd,
35
+ maxTurns: options.maxTurns,
36
+ instructions: JOB_INSTRUCTIONS,
37
+ extensions: [...jobExtensions],
38
+ tools: null,
39
+ modelTools: null,
40
+ };
41
+ }
42
+ export function jobOptionsOf(config) {
43
+ return { maxTurns: config.jobMaxTurns, thinkingLevel: config.thinkingLevel };
44
+ }
45
+ export function jobCreateOptionsOf(config) {
46
+ return { ...jobOptionsOf(config), autoContinue: config.autoContinue };
47
+ }
48
+ /** Create the job coordinator task and its owned conversation atomically. */
49
+ export async function createJobInCommit(tx, brief, model, jobExtensions, cwd, options) {
50
+ const tags = normalizeTags(options.tags ?? []);
51
+ const taskId = await tx.createTask(JobTask, {
52
+ brief,
53
+ ...(options.notifyMain === true ? { notifyMain: true } : {}),
54
+ autoContinue: options.autoContinue === true,
55
+ ...(options.handoffDepth === undefined ? {} : { handoffDepth: options.handoffDepth }),
56
+ ...(options.handoffFrom === undefined ? {} : { handoffFrom: options.handoffFrom }),
57
+ ...(options.fork === undefined ? {} : { fork: options.fork }),
58
+ ...(options.workspace === undefined ? {} : { workspace: options.workspace }),
59
+ }, { ownership: { kind: "conversation" }, background: true, conversationId: ROOT_CONVERSATION_ID });
60
+ const ownership = { kind: "task", taskId };
61
+ const conversation = options.fork === undefined
62
+ ? await tx.createConversation({ ownership })
63
+ : await tx.forkConversation(options.fork.conversationId, options.fork.entryId, { ownership });
64
+ await configure(tx, conversation.id, jobAgentChange(model, jobExtensions, cwd, options));
65
+ if (options.fork !== undefined) {
66
+ const origin = options.fork;
67
+ const workspace = options.workspace;
68
+ const placement = workspace?.kind === "worktree"
69
+ ? `Managed worktree branch: ${workspace.branch}; base commit: ${workspace.baseCommit}. Keep this branch checked out.`
70
+ : "This is a shared workspace; coordinate edits with main.";
71
+ await tx.appendEntry(conversation.id, {
72
+ kind: "app.context-fork",
73
+ data: { fork: origin, ...(workspace === undefined ? {} : { workspace }) },
74
+ model: [{ role: "user", timestamp: Date.now(), content: `[host] Context inherited from ${origin.jobId === undefined ? "main" : `job #${origin.jobId}`} through entry #${origin.entryId}. Earlier messages are background for the next brief. Assigned directory: ${cwd}. ${placement} Main decides integration.` }],
75
+ });
76
+ }
77
+ const template = {
78
+ model: { provider: model.provider, modelId: model.modelId },
79
+ cwd,
80
+ maxTurns: options.maxTurns,
81
+ thinkingLevel: options.thinkingLevel,
82
+ extensionNames: jobExtensions.map((extension) => extension.name),
83
+ ...(options.workspace === undefined ? {} : { workspace: options.workspace }),
84
+ };
85
+ const link = await tx.doc(JobLink, taskId);
86
+ link.conversationId = Number(conversation.id);
87
+ link.template = template;
88
+ if (options.workspace !== undefined)
89
+ (await tx.doc(JobWorkspaceDoc, conversation.id)).workspace = options.workspace;
90
+ if (tags.length > 0)
91
+ await writeJobTags(tx, taskId, tags);
92
+ return { taskId, conversationId: conversation.id };
93
+ }
94
+ /**
95
+ * Write a native model-visible notice into the main conversation. A write never
96
+ * starts a run; it lands at the next boundary if the conversation is busy.
97
+ */
98
+ export async function announceJobStart(conversation, started, brief, context) {
99
+ await conversation.submit({
100
+ type: "write",
101
+ entry: jobNoticeEntry(`The user started background job #${started.taskId}: "${brief}". It runs in its own conversation. ` +
102
+ `No action is needed now; a completion notice will arrive automatically.`, {
103
+ taskId: Number(started.taskId),
104
+ conversationId: Number(started.conversationId),
105
+ brief,
106
+ phase: "started",
107
+ }),
108
+ }, context);
109
+ }
110
+ /**
111
+ * Apply the session-wide model before scheduling resumes, including continued and legacy jobs.
112
+ *
113
+ * Reconfiguration leaves prepared requests intact. Resuming a request or deferred poll uses its
114
+ * checkpoint model; a new preparation (including an ordinary retry) uses the current selection.
115
+ * A checkpoint for another model must never block startup or the user's model choice.
116
+ * When supplied, install host repository-context support on existing jobs and successor templates too.
117
+ */
118
+ export async function applyStartupJobModel(harness, model, context, repositoryInstructions) {
119
+ let cursor;
120
+ do {
121
+ cursor = await harness.commit(async (tx) => {
122
+ const page = await tx.scanTasks({ kind: JOB_KIND }, 200, cursor);
123
+ // All table reads precede configure/doc writes on the atomic mutation line.
124
+ const owned = [];
125
+ for (const task of page.items)
126
+ owned.push((await tx.scanConversations({ ownerTaskId: task.id }, 2)).items);
127
+ for (let index = 0; index < page.items.length; index++) {
128
+ for (const conversation of owned[index])
129
+ await configure(tx, conversation.id, {
130
+ model,
131
+ ...(repositoryInstructions === undefined ? {} : { extensions: { add: [repositoryInstructions] } }),
132
+ });
133
+ if (page.items[index].state.status !== "terminal") {
134
+ const link = await tx.doc(JobLink, page.items[index].id);
135
+ if (link.template !== undefined) {
136
+ link.template.model = { ...model };
137
+ if (repositoryInstructions !== undefined && !link.template.extensionNames.includes(repositoryInstructions.name)) {
138
+ link.template.extensionNames.push(repositoryInstructions.name);
139
+ }
140
+ }
141
+ }
142
+ }
143
+ return page.next;
144
+ }, context);
145
+ } while (cursor !== undefined);
146
+ }
147
+ /** Apply the session thinking level to every job conversation. New jobs read it from the live job options. */
148
+ export async function applyThinkingLevel(harness, level, context) {
149
+ let cursor;
150
+ do {
151
+ cursor = await harness.commit(async (tx) => {
152
+ const page = await tx.scanTasks({ kind: JOB_KIND }, 200, cursor);
153
+ const owned = [];
154
+ for (const task of page.items)
155
+ owned.push((await tx.scanConversations({ ownerTaskId: task.id }, 2)).items);
156
+ for (let index = 0; index < page.items.length; index++) {
157
+ for (const conversation of owned[index])
158
+ await configure(tx, conversation.id, { thinkingLevel: level });
159
+ }
160
+ return page.next;
161
+ }, context);
162
+ } while (cursor !== undefined);
163
+ }
164
+ export async function scanJobs(harness, context, limit = 200) {
165
+ const page = await harness.commit((tx) => tx.scanTasks({ kind: JOB_KIND }, limit, undefined), context);
166
+ const labels = await harness.snapshot(JobTags, context);
167
+ return page.items.map((record) => taggedJob(record, labels));
168
+ }
169
+ export async function jobRecord(harness, id, context) {
170
+ const record = await harness.getTask(id, context);
171
+ return record === undefined ? undefined : taggedJob(record, await harness.snapshot(JobTags, context));
172
+ }
173
+ export async function jobConversationId(harness, id, context) {
174
+ const page = await harness.commit((tx) => tx.scanConversations({ ownerTaskId: id }, 2), context);
175
+ const found = page.items[0];
176
+ return found === undefined ? undefined : Number(found.id);
177
+ }
178
+ export async function findJobConversation(harness, id, context) {
179
+ const conversationId = await jobConversationId(harness, id, context);
180
+ if (conversationId === undefined)
181
+ return undefined;
182
+ return harness.conversation(conversationId, context);
183
+ }
184
+ export function answerTextOfEntry(entry) {
185
+ const assistant = (entry?.model ?? []).filter((message) => typeof message === "object" && message !== null && message.role === "assistant");
186
+ const text = (assistant.at(-1)?.content ?? [])
187
+ .flatMap((part) => part.type === "text" ? [part.text] : [])
188
+ .join("");
189
+ return text.trim().length === 0 ? undefined : text;
190
+ }
191
+ export async function readAnswer(harness, entryId, context) {
192
+ const entry = await harness.commit((tx) => tx.entry(entryId), context);
193
+ return answerTextOfEntry(entry);
194
+ }
195
+ /** Input to a job conversation: `steer` joins the current run, follow-up queues behind it. */
196
+ export function jobInputDraft(message, steer) {
197
+ return {
198
+ type: "input",
199
+ content: normalizeBrief(message),
200
+ whenBusy: steer ? "steer" : "followUp",
201
+ };
202
+ }
203
+ export async function sendToJob(harness, id, message, context, options = {}) {
204
+ const conversation = await findJobConversation(harness, id, context);
205
+ if (conversation === undefined)
206
+ throw new Error(`Job #${id} has no conversation.`);
207
+ const submission = await conversation.submit(jobInputDraft(message, options.steer === true), context);
208
+ const settled = await submission.wait(context);
209
+ if (settled.status === "done" && settled.type === "input") {
210
+ return { status: "answered", answer: await readAnswer(harness, Number(settled.answer), context) };
211
+ }
212
+ return { status: "unanswered", reason: settled.status === "unanswered" ? String(settled.reason) : "not answered" };
213
+ }
214
+ function messageText(message) {
215
+ const content = message.content;
216
+ if (typeof content === "string")
217
+ return content;
218
+ if (!Array.isArray(content))
219
+ return "";
220
+ return content.flatMap((block) => {
221
+ if (typeof block !== "object" || block === null)
222
+ return [];
223
+ const value = block;
224
+ if (value.type === "text" && typeof value.text === "string")
225
+ return [value.text];
226
+ if (value.type === "toolCall" && typeof value.name === "string")
227
+ return [`[tool ${value.name}]`];
228
+ if (value.type === "image")
229
+ return ["[image]"];
230
+ return [];
231
+ }).join(" ");
232
+ }
233
+ /** Newest `limit` transcript entries of a conversation, oldest first. */
234
+ export async function readLog(harness, conversationId, context, limit = 30) {
235
+ const page = await harness.commit((tx) => tx.scanEntries({ conversationId: conversationId, order: "descending" }, limit, undefined), context);
236
+ return [...page.items].reverse().map((entry) => {
237
+ const messages = Array.isArray(entry.model) ? entry.model : [];
238
+ const text = messages.map((message) => messageText(message)).join(" ").trim();
239
+ return { id: Number(entry.id), kind: entry.kind, text };
240
+ });
241
+ }
242
+ export function formatLog(entries, width = 240) {
243
+ if (entries.length === 0)
244
+ return "(no transcript entries)";
245
+ return entries.map((entry) => {
246
+ const flat = entry.text.replace(/\s+/g, " ").trim();
247
+ const text = flat.length <= width ? flat : `${flat.slice(0, width - 1)}…`;
248
+ return `#${entry.id} ${entry.kind.padEnd(14)} ${text}`;
249
+ }).join("\n");
250
+ }
251
+ /** Manual compaction, joined through the Task and the summary placement (both matter). */
252
+ export async function compactConversation(harness, conversation, instructions, context) {
253
+ const taskId = await conversation.compact(instructions, context);
254
+ const settled = await harness.waitForTask(taskId, context);
255
+ const outcome = settled.state.outcome;
256
+ if (outcome.status !== "completed") {
257
+ throw new Error(`Compaction ended ${outcome.status}: ${outcome.error?.message ?? outcome.reason ?? ""}`.trim());
258
+ }
259
+ const result = outcome.result;
260
+ if (result.submissionId !== undefined) {
261
+ const submission = await harness.submission(result.submissionId, context);
262
+ if (submission === undefined)
263
+ throw new Error("The summary placement is missing.");
264
+ const placed = await submission.wait(context);
265
+ if (placed.status !== "done")
266
+ throw new Error(`The summary was not placed: ${JSON.stringify(placed)}`);
267
+ }
268
+ return {
269
+ taskId: Number(taskId),
270
+ noop: result.entryId === undefined && result.submissionId === undefined,
271
+ ...(result.entryId === undefined ? {} : { entryId: Number(result.entryId) }),
272
+ ...(result.submissionId === undefined ? {} : { submissionId: Number(result.submissionId) }),
273
+ };
274
+ }
package/dist/mcp.js ADDED
@@ -0,0 +1,231 @@
1
+ import { existsSync, readFileSync } from "node:fs";
2
+ import { homedir } from "node:os";
3
+ import { isAbsolute, resolve } from "node:path";
4
+ import { defineExtension, defineTool } from "@earendil-works/pi-durable";
5
+ import { int, map, obj, opt, str, unknown } from "@earendil-works/pi-schema";
6
+ import { McpClient, StdioTransport, StreamableHttpTransport, toLlmContent } from "@earendil-works/pi-mcp";
7
+ export const DEFAULT_MCP_CONFIG = resolve(homedir(), ".pi/agent/mcp.json");
8
+ function expand(value) {
9
+ return value
10
+ .replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_match, name) => process.env[name] ?? "")
11
+ .replace(/^~(?=$|\/)/, homedir());
12
+ }
13
+ function readConfig(path, notes) {
14
+ if (!existsSync(path)) {
15
+ notes.push(`no MCP config at ${path}`);
16
+ return {};
17
+ }
18
+ try {
19
+ const parsed = JSON.parse(readFileSync(path, "utf8"));
20
+ return parsed.mcpServers ?? {};
21
+ }
22
+ catch (error) {
23
+ notes.push(`could not read ${path}: ${error instanceof Error ? error.message : String(error)}`);
24
+ return {};
25
+ }
26
+ }
27
+ /** Read user and project MCP config; a project entry replaces a user entry of the same name. */
28
+ export function readMcpServers(configPath, notes) {
29
+ const primary = configPath ?? process.env.DURABLE_MCP_CONFIG ?? DEFAULT_MCP_CONFIG;
30
+ const servers = {};
31
+ Object.assign(servers, readConfig(resolve(homedir(), ".pi/agent/mcp.json"), notes));
32
+ const projectPath = resolve(process.cwd(), ".pi/mcp.json");
33
+ if (projectPath !== resolve(primary))
34
+ Object.assign(servers, readConfig(projectPath, []));
35
+ if (resolve(primary) !== resolve(homedir(), ".pi/agent/mcp.json") && resolve(primary) !== projectPath) {
36
+ Object.assign(servers, readConfig(primary, notes));
37
+ }
38
+ return servers;
39
+ }
40
+ async function connect(name, entry, notes) {
41
+ const requestTimeoutMs = (entry.timeout ?? 60) * 1000;
42
+ const client = new McpClient({ name: "durable-chat", version: "0.1.0", requestTimeoutMs });
43
+ try {
44
+ if (entry.url !== undefined) {
45
+ const headers = Object.fromEntries(Object.entries(entry.headers ?? {}).map(([key, value]) => [key, expand(value)]));
46
+ await client.connect(new StreamableHttpTransport({ url: expand(entry.url), headers }));
47
+ }
48
+ else if (entry.command !== undefined) {
49
+ const expandedCwd = entry.cwd === undefined ? undefined : expand(entry.cwd);
50
+ const cwd = expandedCwd === undefined ? undefined : resolve(isAbsolute(expandedCwd) ? expandedCwd : process.cwd(), "");
51
+ await client.connect(new StdioTransport({
52
+ command: expand(entry.command),
53
+ args: (entry.args ?? []).map(expand),
54
+ ...(cwd === undefined ? {} : { cwd }),
55
+ env: Object.fromEntries(Object.entries(entry.env ?? {}).map(([key, value]) => [key, expand(value)])),
56
+ inheritEnv: true,
57
+ stderr: "pipe",
58
+ onStderr: (chunk) => {
59
+ const text = chunk.trim();
60
+ if (text.length > 0)
61
+ notes.push(`[${name}] ${text.slice(0, 300)}`);
62
+ },
63
+ }));
64
+ }
65
+ else {
66
+ notes.push(`MCP server ${name} has no url or command`);
67
+ return undefined;
68
+ }
69
+ return client;
70
+ }
71
+ catch (error) {
72
+ notes.push(`MCP server ${name} failed to connect: ${error instanceof Error ? error.message : String(error)}`);
73
+ await client.close().catch(() => undefined);
74
+ return undefined;
75
+ }
76
+ }
77
+ function llmOutput(result) {
78
+ const blocks = toLlmContent(result).map((block) => block.type === "text"
79
+ ? { type: "text", text: block.text }
80
+ : { type: "image", data: block.data, mimeType: block.mimeType });
81
+ return blocks.length > 0 ? blocks : [{ type: "text", text: JSON.stringify(result.structuredContent ?? null) }];
82
+ }
83
+ function errorText(error) {
84
+ return error instanceof Error ? error.message : String(error);
85
+ }
86
+ function serverToolName(toolName) {
87
+ return `mcp__${toolName.replace(/[^A-Za-z0-9_]/g, "_")}`;
88
+ }
89
+ /** Three tools that cover the whole Substrate surface without offering 249 separate schemas. */
90
+ function substrateGateway(client, timeoutMs) {
91
+ const call = async (name, args) => client.callTool(name, args, { timeoutMs });
92
+ const search = defineTool({
93
+ name: "substrate_search",
94
+ description: "Search the Substrate MCP tool catalog. Start here when you need Substrate state or an operation.",
95
+ parameters: obj({ query: str({ minLength: 1 }), limit: opt(int({ minimum: 1, maximum: 50 })) }),
96
+ replay: "safe",
97
+ execute: async (args) => {
98
+ try {
99
+ const result = await call("search_tool", { query: args.query, limit: args.limit ?? 12 });
100
+ return { output: llmOutput(result), ...(result.isError === true ? { isError: true } : {}) };
101
+ }
102
+ catch (error) {
103
+ return { output: [{ type: "text", text: `Substrate search failed: ${errorText(error)}` }], isError: true };
104
+ }
105
+ },
106
+ });
107
+ const describe = defineTool({
108
+ name: "substrate_describe",
109
+ description: "Return the input schema and description of one Substrate MCP tool by exact name.",
110
+ parameters: obj({ name: str({ minLength: 1 }) }),
111
+ replay: "safe",
112
+ execute: async (args) => {
113
+ try {
114
+ const result = await call("get_tool", { name: args.name });
115
+ return { output: llmOutput(result), ...(result.isError === true ? { isError: true } : {}) };
116
+ }
117
+ catch (error) {
118
+ return { output: [{ type: "text", text: `Substrate describe failed: ${errorText(error)}` }], isError: true };
119
+ }
120
+ },
121
+ });
122
+ const invoke = defineTool({
123
+ name: "substrate_call",
124
+ description: "Invoke one Substrate MCP tool by exact name with a JSON args object. Describe it first.",
125
+ parameters: obj({ name: str({ minLength: 1 }), args: opt(map(unknown())) }),
126
+ replay: "unsafe",
127
+ execute: async (args) => {
128
+ try {
129
+ const result = await call(args.name, (args.args ?? {}));
130
+ return { output: llmOutput(result), ...(result.isError === true ? { isError: true } : {}) };
131
+ }
132
+ catch (error) {
133
+ return { output: [{ type: "text", text: `Substrate call failed: ${errorText(error)}` }], isError: true };
134
+ }
135
+ },
136
+ });
137
+ return [search, describe, invoke];
138
+ }
139
+ function directTools(client, server, tools, timeoutMs) {
140
+ return tools.map((tool) => defineTool({
141
+ name: serverToolName(`${server}__${tool.name}`),
142
+ description: tool.description ?? `${server} MCP tool ${tool.name}`,
143
+ parameters: tool.inputSchema,
144
+ replay: "unsafe",
145
+ execute: async (args) => {
146
+ try {
147
+ const result = await client.callTool(tool.name, args, { timeoutMs });
148
+ return { output: llmOutput(result), ...(result.isError === true ? { isError: true } : {}) };
149
+ }
150
+ catch (error) {
151
+ return { output: [{ type: "text", text: `${server}/${tool.name} failed: ${errorText(error)}` }], isError: true };
152
+ }
153
+ },
154
+ }));
155
+ }
156
+ /**
157
+ * Connect the selected MCP servers once per process and expose them as extensions.
158
+ * Substrate gets a three-tool gateway; other servers expose selected tools directly.
159
+ */
160
+ export async function connectMcp(options = {}) {
161
+ const notes = [];
162
+ const servers = options.servers ?? (process.env.DURABLE_MCP_SERVERS ?? "substrate").split(",").map((name) => name.trim()).filter(Boolean);
163
+ const wantedTools = options.tools ?? (process.env.DURABLE_MCP_TOOLS ?? "").split(",").map((name) => name.trim()).filter(Boolean);
164
+ const configured = readMcpServers(options.configPath, notes);
165
+ const clients = [];
166
+ const extensions = [];
167
+ for (const name of servers) {
168
+ const entry = configured[name];
169
+ const extensionName = `durable-chat.mcp.${name}`;
170
+ if (entry === undefined) {
171
+ notes.push(`MCP server ${name} is not configured`);
172
+ extensions.push(unavailableExtension(extensionName, name, "not configured"));
173
+ continue;
174
+ }
175
+ if (entry.enabled === false) {
176
+ notes.push(`MCP server ${name} is disabled`);
177
+ extensions.push(unavailableExtension(extensionName, name, "disabled"));
178
+ continue;
179
+ }
180
+ const client = await connect(name, entry, notes);
181
+ if (client === undefined) {
182
+ extensions.push(unavailableExtension(extensionName, name, "connection failed"));
183
+ continue;
184
+ }
185
+ clients.push(client);
186
+ const timeoutMs = (entry.timeout ?? 60) * 1000;
187
+ let tools = [];
188
+ try {
189
+ tools = await client.listTools({ timeoutMs });
190
+ }
191
+ catch (error) {
192
+ notes.push(`MCP server ${name} listed no tools: ${errorText(error)}`);
193
+ }
194
+ const isSubstrate = name === "substrate" && tools.some((tool) => tool.name === "search_tool");
195
+ let registrations;
196
+ if (isSubstrate) {
197
+ registrations = substrateGateway(client, timeoutMs);
198
+ const extras = wantedTools.length === 0
199
+ ? []
200
+ : tools.filter((tool) => wantedTools.includes(tool.name) && tool.name !== "search_tool" && tool.name !== "get_tool");
201
+ registrations.push(...directTools(client, name, extras, timeoutMs));
202
+ }
203
+ else {
204
+ const selected = wantedTools.length === 0 ? tools.slice(0, 20) : tools.filter((tool) => wantedTools.includes(tool.name));
205
+ registrations = directTools(client, name, selected, timeoutMs);
206
+ }
207
+ extensions.push(defineExtension({ name: extensionName, tools: registrations }));
208
+ }
209
+ return {
210
+ extensions,
211
+ notes,
212
+ async close() {
213
+ await Promise.allSettled(clients.map((client) => client.close()));
214
+ },
215
+ };
216
+ }
217
+ function unavailableExtension(name, server, reason) {
218
+ return defineExtension({
219
+ name,
220
+ tools: [defineTool({
221
+ name: `mcp_${server}_unavailable`,
222
+ description: `The ${server} MCP server is unavailable: ${reason}.`,
223
+ parameters: obj({}),
224
+ replay: "safe",
225
+ execute: async () => ({
226
+ isError: true,
227
+ output: [{ type: "text", text: `${server} MCP is unavailable: ${reason}.` }],
228
+ }),
229
+ })],
230
+ });
231
+ }
package/dist/models.js ADDED
@@ -0,0 +1,64 @@
1
+ /** Providers that build their own catalog need a model name; the offline one has a fixed ID. */
2
+ export function defaultModelId(entry) {
3
+ return entry.model ?? (entry.kind === "openai-codex" ? "gpt-6.1-sol" : entry.kind === "faux" ? "faux-1" : "model");
4
+ }
5
+ /** Catalog browsing never refreshes OAuth or sends a generation request. */
6
+ export async function modelChoices(config, models, current, signal) {
7
+ // The active entry comes first, then the other configured providers in config order.
8
+ const entries = [...config.providers.filter((entry) => entry.name === current.provider), ...config.providers.filter((entry) => entry.name !== current.provider)];
9
+ let warning;
10
+ const items = [];
11
+ for (const entry of entries) {
12
+ // The active entry follows the resolved config, so a caller that copies the config still applies.
13
+ const values = entry === config.active
14
+ ? { name: entry.name, kind: entry.kind, model: config.model, baseUrl: config.baseUrl, apiKey: config.apiKey, contextWindow: config.contextWindow, maxTokens: config.maxTokens }
15
+ : entry;
16
+ const entryItems = models.getModels(entry.name).map((model) => choice(values, model.id, model.name, model.contextWindow, model.maxTokens));
17
+ // Only the active provider is contacted for its dynamic list; the others show their configured model.
18
+ if (values.kind === "local" && entry === config.active) {
19
+ try {
20
+ const url = new URL(values.baseUrl);
21
+ url.pathname = `${url.pathname.replace(/\/+$/, "")}/models`;
22
+ const response = await fetch(url, {
23
+ signal: AbortSignal.any([AbortSignal.timeout(5000), ...(signal === undefined ? [] : [signal])]),
24
+ ...(values.apiKey === undefined ? {} : { headers: { Authorization: `Bearer ${values.apiKey}` } }),
25
+ redirect: "error",
26
+ });
27
+ if (!response.ok)
28
+ throw new Error(`HTTP ${response.status}`);
29
+ const body = await response.json();
30
+ const data = body !== null && typeof body === "object" && "data" in body ? body.data : undefined;
31
+ if (!Array.isArray(data))
32
+ throw new Error("expected an OpenAI-compatible model list");
33
+ entryItems.push(...data.flatMap((model) => {
34
+ const id = model !== null && typeof model === "object" && "id" in model ? model.id : undefined;
35
+ return typeof id === "string" && id.trim().length > 0 && !/[\u0000-\u001f\u007f]/.test(id)
36
+ ? [choice(values, id.trim(), id.trim(), values.contextWindow, values.maxTokens)] : [];
37
+ }));
38
+ }
39
+ catch (error) {
40
+ if (signal?.aborted)
41
+ throw error;
42
+ const reason = error instanceof SyntaxError ? "invalid model-list JSON" : error instanceof Error ? error.message : String(error);
43
+ warning = `Local model discovery failed (${reason}); showing the configured model.`;
44
+ }
45
+ }
46
+ const unique = [...new Map(entryItems.map((model) => [model.id, model])).values()];
47
+ unique.sort((a, b) => Number(b.lookup === `${current.provider}/${current.modelId}`) - Number(a.lookup === `${current.provider}/${current.modelId}`) || a.id.localeCompare(b.id));
48
+ items.push(...unique);
49
+ }
50
+ items.sort((a, b) => Number(b.lookup === `${current.provider}/${current.modelId}`) - Number(a.lookup === `${current.provider}/${current.modelId}`));
51
+ return { items, ...(warning === undefined ? {} : { warning }) };
52
+ }
53
+ function choice(values, id, name, contextWindow, maxTokens) {
54
+ return { provider: values.name, id, name, contextWindow, maxTokens, lookup: `${values.name}/${id}` };
55
+ }
56
+ export function selectModel(input, choices) {
57
+ const value = input.trim();
58
+ const model = choices.find((choice) => choice.lookup === value)
59
+ ?? choices.find((choice) => choice.id === value)
60
+ ?? (/^[1-9][0-9]*$/.test(value) ? choices[Number(value) - 1] : undefined);
61
+ if (model === undefined)
62
+ throw new Error("Choose a listed model by number or exact model ID.");
63
+ return model;
64
+ }
package/dist/reboot.js ADDED
@@ -0,0 +1,70 @@
1
+ import { closeSync, lstatSync, mkdirSync, mkdtempSync, openSync, renameSync } from "node:fs";
2
+ import { basename, join, resolve } from "node:path";
3
+ import { DatabaseSync } from "node:sqlite";
4
+ import { defineDoc } from "@earendil-works/pi-durable";
5
+ export const RebootArchive = defineDoc({
6
+ kind: "durable-chat.reboot-archive", version: 1, scope: "session",
7
+ initial: () => ({ path: null }), checkpointWhen: () => false,
8
+ });
9
+ const SIDECARS = ["-wal", "-shm", "-journal"];
10
+ const exists = (path) => lstatSync(path, { throwIfNoEntry: false }) !== undefined;
11
+ function closeJournals(storePath) {
12
+ const db = new DatabaseSync(storePath);
13
+ try {
14
+ db.exec("PRAGMA busy_timeout = 0");
15
+ const checkpoint = db.prepare("PRAGMA wal_checkpoint(TRUNCATE)").get();
16
+ if (checkpoint?.busy !== 0)
17
+ throw new Error("Cannot replace state while another SQLite connection holds the database; close it first.");
18
+ // DELETE mode also requires other WAL connections to release their locks, even idle readers.
19
+ const journal = db.prepare("PRAGMA journal_mode = DELETE").get();
20
+ if (journal?.journal_mode !== "delete")
21
+ throw new Error("Cannot safely close the database journals for state replacement.");
22
+ }
23
+ finally {
24
+ db.close();
25
+ }
26
+ for (const suffix of SIDECARS) {
27
+ if (exists(`${storePath}${suffix}`))
28
+ throw new Error(`Cannot replace state with a remaining SQLite sidecar: ${storePath}${suffix}`);
29
+ }
30
+ }
31
+ /** Caller holds the store lock and has closed its runtime. A failed opener must close its connections. */
32
+ export async function rebootClosedStore(path, openFresh, operation = "Reboot") {
33
+ const storePath = resolve(path);
34
+ const stat = lstatSync(storePath);
35
+ if (!stat.isFile() || stat.nlink !== 1)
36
+ throw new Error("State replacement requires a regular database file without symlinks or additional hard links.");
37
+ closeJournals(storePath);
38
+ const createdAt = new Date().toISOString();
39
+ // Exclusive directory creation avoids overwriting an archive, including same-millisecond reboots.
40
+ const directory = mkdtempSync(`${storePath}.reboot-${createdAt.replaceAll(":", "-")}-`);
41
+ const archivePath = join(directory, basename(storePath));
42
+ renameSync(storePath, archivePath);
43
+ try {
44
+ closeSync(openSync(storePath, "wx", stat.mode & 0o777));
45
+ return await openFresh(archivePath);
46
+ }
47
+ catch (error) {
48
+ const failed = join(directory, "failed-fresh");
49
+ try {
50
+ // Refuse to move a replacement that still has an open SQLite connection.
51
+ if (exists(storePath))
52
+ closeJournals(storePath);
53
+ else if (SIDECARS.some((suffix) => exists(`${storePath}${suffix}`)))
54
+ throw new Error("Replacement has orphaned SQLite sidecars.");
55
+ // Preserve even a partially initialized replacement; never delete state during recovery.
56
+ for (const suffix of ["", ...SIDECARS]) {
57
+ const file = `${storePath}${suffix}`;
58
+ if (!exists(file))
59
+ continue;
60
+ mkdirSync(failed, { recursive: true, mode: 0o700 });
61
+ renameSync(file, join(failed, basename(file)));
62
+ }
63
+ renameSync(archivePath, storePath);
64
+ }
65
+ catch (recoveryError) {
66
+ throw new AggregateError([error, recoveryError], `${operation} and recovery failed. Preserved state is at ${archivePath}; replacement files may be at ${storePath} or ${failed}.`);
67
+ }
68
+ throw new Error(`${operation} failed; original state restored at ${storePath}. Replacement files, if any, were retained at ${failed}.`, { cause: error });
69
+ }
70
+ }