@appsoftwareltd/etherpk-mcp 0.37.0 → 0.39.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/main.js CHANGED
@@ -820,7 +820,7 @@ function looksLikeAgentSetupCode(value) {
820
820
  }
821
821
  var package_default = {
822
822
  name: "@appsoftwareltd/etherpk-mcp",
823
- version: "0.37.0",
823
+ version: "0.39.0",
824
824
  license: "Elastic-2.0",
825
825
  description: "EtherPK Headless Client: an MCP server over a synced knowledge graph, run beside the agent on the user's own machine.",
826
826
  type: "module",
@@ -3217,7 +3217,7 @@ async function upgradeToAgentToken(opts) {
3217
3217
  },
3218
3218
  keychain: inKeychain(stored) ? keychain : null
3219
3219
  });
3220
- say(`etherpk-mcp: replaced the access token for ${current.syncServer} with an agent token for this computer, kept in ${where}. An agent token can do only what an agent needs, and the old token has been revoked.`);
3220
+ say(`etherpk-mcp: replaced the access token for ${current.syncServer} with an agent token for this device, kept in ${where}. An agent token can do only what an agent needs, and the old token has been revoked.`);
3221
3221
  return {
3222
3222
  ...current,
3223
3223
  pat: agentToken
@@ -8307,7 +8307,11 @@ async function setupSemantic(io) {
8307
8307
  io.say(`Downloading ${file.name} (${Math.max(1, Math.round(file.bytes / 1e6))} MB) from ${new URL(file.url).host}…`);
8308
8308
  await download(io.fetch ?? fetch, file, path);
8309
8309
  }
8310
- io.say(`Semantic search is set up. Model: ${MODEL.id} (${MODEL.dims} dimensions) in ${status.modelDir}.`);
8310
+ io.say("Semantic search is set up.");
8311
+ io.say("");
8312
+ io.say(`Next, serve embeds the passages of each graph it serves, in the background. This can take a few minutes on a large graph. A serve that is already running starts within half a minute, otherwise the next serve starts it. Until it finishes, a semantic search answers from the passages embedded so far and marks its results incomplete. To see progress, run: ${io.command ?? "etherpk-mcp"} semantic status`);
8313
+ io.say("");
8314
+ io.say(`Model: ${MODEL.id} (${MODEL.dims} dimensions), in ${status.modelDir}.`);
8311
8315
  return semanticSetupStatus(io.env, files);
8312
8316
  }
8313
8317
  async function npmInstall(args, cwd, say) {
@@ -8369,7 +8373,7 @@ var SemanticUnavailable = class extends Error {
8369
8373
  this.name = "SemanticUnavailable";
8370
8374
  }
8371
8375
  };
8372
- var SETUP_HINT = "run `npx @appsoftwareltd/etherpk-mcp semantic setup` on this computer once (it installs a ~300 MB runtime and a 23 MB model into the cache directory) - the next semantic search will use it, no restart needed.";
8376
+ var SETUP_HINT = "run `npx @appsoftwareltd/etherpk-mcp semantic setup` on this device once (it installs a ~300 MB runtime and a 23 MB model into the cache directory) - the next semantic search will use it, no restart needed.";
8373
8377
  /** The thread count `serve` uses: the option, else the environment, else the conservative default. */
8374
8378
  function semanticThreads(env, requested) {
8375
8379
  if (requested !== void 0) return Math.max(1, Math.floor(requested));
@@ -8383,7 +8387,7 @@ function semanticThreads(env, requested) {
8383
8387
  */
8384
8388
  async function loadEmbeddingModel(env, options = {}) {
8385
8389
  const status = await semanticSetupStatus(env);
8386
- if (!status.runtime || !status.model) throw new SemanticUnavailable(`Semantic search is not set up on this computer: ${SETUP_HINT}`);
8390
+ if (!status.runtime || !status.model) throw new SemanticUnavailable(`Semantic search is not set up on this device: ${SETUP_HINT}`);
8387
8391
  const require = createRequire(join(status.runtimeDir, "package.json"));
8388
8392
  let ort;
8389
8393
  try {
@@ -13373,11 +13377,11 @@ function offlineSince(connection, now = Date.now()) {
13373
13377
  /** The note an answer carries while its copy is offline; null while connected and on a folder, which has no connection. */
13374
13378
  function offlineNotice(connection, now = Date.now()) {
13375
13379
  if (connection?.state !== "offline") return null;
13376
- return `This computer's copy of the graph has been ${offlineSince(connection, now)}. This answer comes from that copy: it can lack edits made elsewhere since then, and a page or task it does not find may only be newer than the copy. Tell the user before relying on it. The copy catches up when the connection returns.`;
13380
+ return `This device's copy of the graph has been ${offlineSince(connection, now)}. This answer comes from that copy: it can lack edits made elsewhere since then, and a page or task it does not find may only be newer than the copy. Tell the user before relying on it. The copy catches up when the connection returns.`;
13377
13381
  }
13378
13382
  /** One line for the host's log. */
13379
13383
  function connectionChangeLine(change) {
13380
- if (change.connection.state === "offline") return "lost the connection to the Sync Server; the tools answer from this computer's copy.";
13384
+ if (change.connection.state === "offline") return "lost the connection to the Sync Server; the tools answer from this device's copy.";
13381
13385
  return change.offlineForMs === null ? "connected to the Sync Server." : `connected to the Sync Server again, after ${durationWords(change.offlineForMs)} offline.`;
13382
13386
  }
13383
13387
  // ../client/src/lib/document/publish/selection.ts
@@ -17398,7 +17402,7 @@ async function setupDiagrams(env, say) {
17398
17402
  }
17399
17403
  const cli = require$2.resolve("playwright-core/cli.js");
17400
17404
  const dir = env.PLAYWRIGHT_BROWSERS_PATH?.trim() || browsersDir(env);
17401
- say(`Installing Chromium into ${dir} (about 170 MB, once per computer - a diagram is rendered by a browser, and this is the one etherpk-mcp drives)…`);
17405
+ say(`Installing Chromium into ${dir} (about 170 MB, once per device - a diagram is rendered by a browser, and this is the one etherpk-mcp drives)…`);
17402
17406
  await new Promise((resolve, reject) => {
17403
17407
  const child = spawn(process.execPath, [
17404
17408
  cli,
@@ -21720,8 +21724,8 @@ async function requireReferencedTask(graph, reference, purpose = "read") {
21720
21724
  * same words and would fail the same way, so it asks for a retry instead.
21721
21725
  */
21722
21726
  function taskNotFoundMessage(connection) {
21723
- if (connection?.state === "offline") return `No task in this computer's copy of the graph has those words, but the copy has been ${offlineSince(connection)}, so the task may be newer than the copy. Tell the user, and try again once graph_info says the copy is connected.`;
21724
- return "No task in the graph has those words now: it was edited or deleted, or the change has not reached this computer yet. Ask the user for a fresh agent instruction.";
21727
+ if (connection?.state === "offline") return `No task in this device's copy of the graph has those words, but the copy has been ${offlineSince(connection)}, so the task may be newer than the copy. Tell the user, and try again once graph_info says the copy is connected.`;
21728
+ return "No task in the graph has those words now: it was edited or deleted, or the change has not reached this device yet. Ask the user for a fresh agent instruction.";
21725
21729
  }
21726
21730
  /**
21727
21731
  * The block's own lines and everything nested under it: in the index's rows, which run in
@@ -21845,7 +21849,7 @@ async function graphInfo(graph) {
21845
21849
  complete: status.embedded >= status.total
21846
21850
  } : {
21847
21851
  state: "not-opened",
21848
- note: "The first search with mode \"semantic\" loads the model - if it is not set up on this computer, that search says so and names the command."
21852
+ note: "The first search with mode \"semantic\" loads the model - if it is not set up on this device, that search says so and names the command."
21849
21853
  },
21850
21854
  assets: { available: graph.assets !== void 0 }
21851
21855
  };
@@ -22090,7 +22094,7 @@ async function publish(graph, args, host) {
22090
22094
  renderer = await openDiagramRenderer(env);
22091
22095
  if (!renderer) {
22092
22096
  const status = await chromiumStatus(env, cmd);
22093
- throw new ToolError("chromium_unavailable", `"${publication.name}" has Mermaid diagrams, which a publish draws with a browser, and none is set up on this computer. Ask the user to run: ${status.setupCommand} (or set ETHERPK_CHROMIUM to a Chromium on this machine). Nothing was published.`);
22097
+ throw new ToolError("chromium_unavailable", `"${publication.name}" has Mermaid diagrams, which a publish draws with a browser, and none is set up on this device. Ask the user to run: ${status.setupCommand} (or set ETHERPK_CHROMIUM to a Chromium on this machine). Nothing was published.`);
22094
22098
  }
22095
22099
  }
22096
22100
  let maps = null;
@@ -22099,7 +22103,7 @@ async function publish(graph, args, host) {
22099
22103
  if (!maps) {
22100
22104
  await renderer?.dispose();
22101
22105
  const status = await chromiumStatus(env, cmd);
22102
- throw new ToolError("chromium_unavailable", `"${publication.name}" has maps, which a publish draws as pictures with a browser, and none is set up on this computer. Ask the user to run: ${status.setupCommand} (or set ETHERPK_CHROMIUM to a Chromium on this machine). Nothing was published.`);
22106
+ throw new ToolError("chromium_unavailable", `"${publication.name}" has maps, which a publish draws as pictures with a browser, and none is set up on this device. Ask the user to run: ${status.setupCommand} (or set ETHERPK_CHROMIUM to a Chromium on this machine). Nothing was published.`);
22103
22107
  }
22104
22108
  }
22105
22109
  let drawings = null;
@@ -22109,7 +22113,7 @@ async function publish(graph, args, host) {
22109
22113
  await renderer?.dispose();
22110
22114
  await maps?.dispose();
22111
22115
  const status = await chromiumStatus(env, cmd);
22112
- throw new ToolError("chromium_unavailable", `"${publication.name}" has drawings, which a publish draws as pictures with a browser, and none is set up on this computer. Ask the user to run: ${status.setupCommand} (or set ETHERPK_CHROMIUM to a Chromium on this machine). Nothing was published.`);
22116
+ throw new ToolError("chromium_unavailable", `"${publication.name}" has drawings, which a publish draws as pictures with a browser, and none is set up on this device. Ask the user to run: ${status.setupCommand} (or set ETHERPK_CHROMIUM to a Chromium on this machine). Nothing was published.`);
22113
22117
  }
22114
22118
  }
22115
22119
  try {
@@ -22871,7 +22875,7 @@ function withOfflineNote(result, connection) {
22871
22875
  function accessEndedError(graph, cmd) {
22872
22876
  const loss = graph.accessLoss();
22873
22877
  if (!loss) return null;
22874
- return loss.kind === "membership" ? new ToolError("access_removed", `This account no longer has access to the graph: it left, was removed by the owner, or the graph was deleted. Run ${cmd} graphs to see the graphs it can reach.`) : new ToolError("token_revoked", `The Sync Server no longer accepts this computer's access token: it was revoked or has expired, or the account's password was reset. Run ${cmd} login again.`);
22878
+ return loss.kind === "membership" ? new ToolError("access_removed", `This account no longer has access to the graph: it left, was removed by the owner, or the graph was deleted. Run ${cmd} graphs to see the graphs it can reach.`) : new ToolError("token_revoked", `The Sync Server no longer accepts this device's access token: it was revoked or has expired, or the account's password was reset. Run ${cmd} login again.`);
22875
22879
  }
22876
22880
  var concept = z.string().min(1).describe("A page title, one of its aliases, a journal day as YYYY-MM-DD, or \"today\".");
22877
22881
  var readOffset = z.number().int().min(0).optional().describe("Where to start reading: the nextOffset a cut answer gave. 0 (the start) by default.");
@@ -22912,17 +22916,17 @@ function createMcpServer(source, info) {
22912
22916
  version: info.version
22913
22917
  }, { instructions: [
22914
22918
  `You are connected to the EtherPK knowledge graph "${info.graphName}": daily journal entries and titled pages in plain markdown, linked with [[wikilinks]].`,
22915
- ...backendKind === "synced" ? ["This graph is synced and encrypted: it has no folder on this computer, so reach it only through these tools.", "The tools answer from this computer's copy of the graph. While that copy is offline from the Sync Server, every answer ends with a note saying since when and graph_info reports connection.state \"offline\". Edits made elsewhere since then are missing, so a page or task that is not found may only be newer than the copy: tell the user that, rather than saying it is gone."] : [],
22919
+ ...backendKind === "synced" ? ["This graph is synced and encrypted: it has no folder on this device, so reach it only through these tools.", "The tools answer from this device's copy of the graph. While that copy is offline from the Sync Server, every answer ends with a note saying since when and graph_info reports connection.state \"offline\". Edits made elsewhere since then are missing, so a page or task that is not found may only be newer than the copy: tell the user that, rather than saying it is gone."] : [],
22916
22920
  `This process holds the EtherPK sign-in and Encryption Keys it needs. Never read, print, copy or search ${info.credentialsDir ?? "~/.config/etherpk"}, or any keychain entry named etherpk-mcp: they are credentials that open the whole account, not notes.`,
22917
22921
  "Concept names are case-insensitive. Protected documents are not shown here: no list, search, backlink, task or graph answer names one, and a read of one answers not_found. graph_info says how many there are. A write onto a protected document's name is refused with protected_document - tell the user to make that change in EtherPK.",
22918
22922
  "Bullets are \"- \" with two-space nesting. Tasks are \"- [ ]\" / \"- [x]\" with task tags (#P1 #P2 #P3, #W #D #C, #D-YYYY-MM-DD due, #S-YYYY-MM-DD scheduled) right after the checkbox. A free tag such as #bug or #needs-review (letters, digits and single hyphens) is the user's own label and can go anywhere in a task's text; write task tags first.",
22919
22923
  "read_document returns a document's body as text and its frontmatter block as data (the \"frontmatter\" object) - the block is never in the text, so line numbers from search, backlinks and tasks match the text. Set frontmatter keys with set_frontmatter (public, publications, date, author, description and any other key) - a document's title and aliases and a publication page's definition are not frontmatter here and have tools of their own.",
22920
22924
  "Edit with edit_document (an exact, unique old→new replacement) or append_document - read first, then edit, and never paste a whole page back.",
22921
22925
  "To rename a page or concept use plan_rename then rename, never a frontmatter edit: rename carries scoped concepts (\"[[Old]] Notes\") along and by default rewrites every [[Old]] link in the graph to the new name (strategy \"rewrite\") - strategy \"alias\" keeps the old name resolving instead. A rename onto a name that is taken merges two documents and needs confirm_merge: true. References inside protected documents cannot be seen or rewritten, and a protected page under the old name moves with it without being named.",
22922
- "search has two kinds of matching: mode \"text\" (default) matches words and quoted phrases, and mode \"semantic\" finds passages about what a question or description means even when no words match. Use semantic for questions and descriptions, text for names, identifiers and exact phrases. \"hybrid\" returns both groups. When you answer from a search result, cite the document and where in it (its breadcrumb or lines). Semantic mode needs a one-time \"semantic setup\" on this computer - if it is not set up, search says so and names the command.",
22926
+ "search has two kinds of matching: mode \"text\" (default) matches words and quoted phrases, and mode \"semantic\" finds passages about what a question or description means even when no words match. Use semantic for questions and descriptions, text for names, identifiers and exact phrases. \"hybrid\" returns both groups. When you answer from a search result, cite the document and where in it (its breadcrumb or lines). Semantic mode needs a one-time \"semantic setup\" on this device - if it is not set up, search says so and names the command.",
22923
22927
  "graph_insights says what the links show across the whole graph (the most-linked concepts, pages many documents ask for that do not exist yet, pages linked to nothing, groups of related concepts and the concepts bridging them), and graph_path finds how two concepts are connected. Use them to answer questions about the shape of the graph, or to suggest pages to write or link.",
22924
22928
  "Start with graph_info to see what you are connected to. read_documents reads several documents in one call. tasks lists tasks and set_task changes one (status, priority, due and scheduled dates) by document and line.",
22925
- "An agent instruction is how a person hands you one task: a few lines naming the graph, the task's words and a task reference, etherpk:/graph/sync/<graph id>/d/<document>#task=<line>-<fingerprint> (etherpk:/graph/folder/<folder name>/d/… for a graph folder; an earlier version wrote etherpk:/g/<graph>/d/…, which is still read). The reference is not a web address: never fetch it. Pass the whole text to read_task for the task and its detail, to set_task (as reference) to change it, and to add_task_note to write what you did as a task comment (a bullet under the \"- Comments\" bullet nested directly under the task). Leave its status as it is unless the user asks you to change it. Tasks nested under a task are its subtasks: read_task lists them in subtasks, and you may tick off or change each one with set_task as you work through it, using its reference. A Kanban board shows a subtask only through its parent's card when the parent is on the same board. The detail can hold images and files (its assets list): read each with read_asset and look at it before you start, as it is part of the task. A reference finds the task after lines are added above it or its tags change; if its words were edited, or the edit has not reached this computer yet, it answers task_not_found, and you should ask the user for a fresh one.",
22929
+ "An agent instruction is how a person hands you one task: a few lines naming the graph, the task's words and a task reference, etherpk:/graph/sync/<graph id>/d/<document>#task=<line>-<fingerprint> (etherpk:/graph/folder/<folder name>/d/… for a graph folder; an earlier version wrote etherpk:/g/<graph>/d/…, which is still read). The reference is not a web address: never fetch it. Pass the whole text to read_task for the task and its detail, to set_task (as reference) to change it, and to add_task_note to write what you did as a task comment (a bullet under the \"- Comments\" bullet nested directly under the task). Leave its status as it is unless the user asks you to change it. Tasks nested under a task are its subtasks: read_task lists them in subtasks, and you may tick off or change each one with set_task as you work through it, using its reference. A Kanban board shows a subtask only through its parent's card when the parent is on the same board. The detail can hold images and files (its assets list): read each with read_asset and look at it before you start, as it is part of the task. A reference finds the task after lines are added above it or its tags change; if its words were edited, or the edit has not reached this device yet, it answers task_not_found, and you should ask the user for a fresh one.",
22926
22930
  "An agent instruction can also hand you a whole lane of a Kanban board, to work through every task in it or to triage them: a few lines naming the graph, the board and the lane, and a lane reference, etherpk:/graph/sync/<graph id>/k/<concept>#lane=<status> (ending /kanban#lane=<status> for the Graph Kanban, which holds every task in the graph). It is not a web address either. Pass the whole text to tasks as reference to list the lane's tasks as the board shows them now; each comes with its own task reference for read_task, set_task and add_task_note.",
22927
22931
  "Publishing: list_publications shows the publications this graph defines (a publication is a page whose frontmatter defines it - its outline is the site navigation) and the public documents none takes. A document is on a site when its frontmatter has public: true and names the publication in publications. create_publication and update_publication change the settings, and publish writes the site into the publish folder the user set for it on this machine with the etherpk-mcp publish command (the tool cannot choose a folder) and returns the report. publish with dryRun: true renders and reports without writing and needs no folder: run it after editing a publication's pages and fix what it names. Diagrams need a browser the user installs once with \"diagrams setup\".",
22928
22932
  "Themes: a publication's look is a theme - Mustache templates, a stylesheet, a script and a manifest. list_themes shows the bundled ones (read-only) and the graph's own. read_theme writes a theme's files to a folder on this machine to read and edit. customise_publication_theme copies a publication's bundled theme into the graph and points the publication at the copy (create_theme copies any theme). write_theme_file, delete_theme_file and import_theme_folder change a graph theme. preview_theme renders a theme to a folder (with screenshots when a browser is set up) to check before publish. For a snippet such as an analytics script, an include slot (update_publication includes, e.g. head) filled by a page may be lighter than a theme copy.",
@@ -22970,7 +22974,7 @@ function createMcpServer(source, info) {
22970
22974
  }, async (args) => run((graph) => readDocuments(graph, args)));
22971
22975
  server.registerTool("search", {
22972
22976
  title: "Search",
22973
- description: `Search every unprotected document. mode "text" (default): words match by prefix, "quoted phrases" match exactly. Documents come most-matches-first with the matching lines. In text mode a term key:value is a property filter on the documents' frontmatter when some document has that key, and keys and values ignore case (key:"two words", -key:value excludes, key:* means the key is set, key:va* matches the start of a value, publication.id:docs reaches a nested key, title: and aliases: match the document's names). Filters alone list every matching document with the values they matched and no hits. mode "semantic": the passages closest in MEANING to the query, best first, each with its text, a similarity 0..1 and where it is (concept, breadcrumb of headings and parent bullets, start and end line) - finds a note that says "self-assessment is due 31 January" for "tax deadline". Line numbers are 0-based in every mode. Passage text is the note's own words with bullet markers and [[ ]] stripped: quote and cite it, but anchor edit_document on text from read_document. Use semantic for questions and descriptions, text for names, identifiers and exact phrases. mode "hybrid" returns both as separate groups. Semantic results carry complete: false while this computer is still embedding the graph (rerun later for more). If semantic mode answers error semantic_unavailable, it is not set up on this computer: tell the user the command in the message. At most 50 documents per call.`,
22977
+ description: `Search every unprotected document. mode "text" (default): words match by prefix, "quoted phrases" match exactly. Documents come most-matches-first with the matching lines. In text mode a term key:value is a property filter on the documents' frontmatter when some document has that key, and keys and values ignore case (key:"two words", -key:value excludes, key:* means the key is set, key:va* matches the start of a value, publication.id:docs reaches a nested key, title: and aliases: match the document's names). Filters alone list every matching document with the values they matched and no hits. mode "semantic": the passages closest in MEANING to the query, best first, each with its text, a similarity 0..1 and where it is (concept, breadcrumb of headings and parent bullets, start and end line) - finds a note that says "self-assessment is due 31 January" for "tax deadline". Line numbers are 0-based in every mode. Passage text is the note's own words with bullet markers and [[ ]] stripped: quote and cite it, but anchor edit_document on text from read_document. Use semantic for questions and descriptions, text for names, identifiers and exact phrases. mode "hybrid" returns both as separate groups. Semantic results carry complete: false while this device is still embedding the graph (rerun later for more). If semantic mode answers error semantic_unavailable, it is not set up on this device: tell the user the command in the message. At most 50 documents per call.`,
22974
22978
  inputSchema: {
22975
22979
  query: z.string().min(1),
22976
22980
  mode: z.enum([
@@ -23294,7 +23298,7 @@ function createMcpServer(source, info) {
23294
23298
  }, async (args) => run((graph) => previewTheme(graph, args, host)));
23295
23299
  server.registerTool("graph_info", {
23296
23300
  title: "Graph info",
23297
- description: "What you are connected to: the graph's name, whether it is a synced graph (on which server, and whether this computer's copy is connected to it now: connection.state and since) or a folder, how many pages and journal entries it has and how many of them are protected (protected documents are counted here and shown nowhere else), the state of semantic search, whether assets are available, the publications with the publish folder set for each on this machine, and whether Mermaid diagrams can be drawn here.",
23301
+ description: "What you are connected to: the graph's name, whether it is a synced graph (on which server, and whether this device's copy is connected to it now: connection.state and since) or a folder, how many pages and journal entries it has and how many of them are protected (protected documents are counted here and shown nowhere else), the state of semantic search, whether assets are available, the publications with the publish folder set for each on this machine, and whether Mermaid diagrams can be drawn here.",
23298
23302
  inputSchema: {}
23299
23303
  }, async () => run(async (graph) => {
23300
23304
  const publishing = await publishingInfo(graph, host);
@@ -30473,11 +30477,13 @@ async function unlockByDeviceApproval(api, io) {
30473
30477
  const request = await beginDeviceApproval(api);
30474
30478
  const where = io.clientUrl ? `open EtherPK at ${io.clientUrl}` : "open EtherPK in a browser";
30475
30479
  io.say("");
30476
- io.say(`To approve this device, ${where} (any page - it need not be a note) on any device where this account's`);
30477
- io.say("Encryption Keys are unlocked. A prompt appears on each of them: choose Show the code on the one you approve");
30478
- io.say("from, and this terminal then shows the same code.");
30480
+ io.say(`To approve this device, ${where} on any other device where your Encryption Keys are unlocked. Any page will do. Each of those devices shows a prompt: choose Show the code on one of them, and this terminal shows the same code.`);
30479
30481
  io.say("");
30480
30482
  io.say("Waiting (up to ten minutes)…");
30483
+ if (io.offersRecoveryCode) {
30484
+ io.say("");
30485
+ io.say("Press r to type your Recovery Code instead.");
30486
+ }
30481
30487
  const abandon = async () => {
30482
30488
  await Promise.race([api.cancelDeviceApproval(request.id).catch(() => {}), new Promise((resolve) => setTimeout(resolve, CANCEL_TIMEOUT_MS).unref())]);
30483
30489
  throw new ApprovalAbandoned();
@@ -30519,6 +30525,30 @@ async function unlockByDeviceApproval(api, io) {
30519
30525
  async function unlockByRecoveryCode(api, code) {
30520
30526
  return openVaultWithRecoveryCode(api, code);
30521
30527
  }
30528
+ // src/login-summary.ts
30529
+ function loginSummary(outcome) {
30530
+ const { syncServer, configPath, keptIn } = outcome;
30531
+ const paragraphs = [`Logged in. This device can now serve your synced graphs on ${syncServer} to agents.`];
30532
+ if (outcome.exchangedAccessToken) paragraphs.push(`The access token you gave has been revoked. This device now holds an Agent Token, limited to the routes an agent needs. If you used that access token anywhere else, create a new one at ${syncServer}/account/tokens.`);
30533
+ if (outcome.replacedEarlierLogin) paragraphs.push(`Replaced this device's earlier login to ${syncServer}. Its old token no longer works.`);
30534
+ paragraphs.push(keptIn === configPath ? `Encryption Keys unlocked and kept in ${configPath} (owner-only). Anyone who can read your files on this device can read this account, as with a signed-in browser. Never let an agent read, print or search that file.` : `Encryption Keys unlocked and kept in ${keptIn}. ${configPath} names only the server. A program you run can still ask ${keptIn} for them, so run only agents you trust with this account.`);
30535
+ if (outcome.otherServers.length > 0) paragraphs.push(`Also logged in to ${outcome.otherServers.join(", ")}, so commands need --sync-server <url> to say which server they mean.`);
30536
+ if (outcome.stoppedHosts > 0) {
30537
+ const graphs = outcome.stoppedHosts === 1 ? "one graph" : `${outcome.stoppedHosts} graphs`;
30538
+ paragraphs.push(`Stopped the background process of ${graphs} served with the previous login. Agents start a new one with this login on their next call.`);
30539
+ }
30540
+ return paragraphs;
30541
+ }
30542
+ /**
30543
+ * The last line of `login`: where the Client explains the rest of agent setup. Built from the
30544
+ * Client the Sync Server declares, since both can be self-hosted; null when it declares none.
30545
+ */
30546
+ function agentSetupLine(clientUrl) {
30547
+ if (!clientUrl) return null;
30548
+ return `Full instructions for setting up agents: ${new URL("/graphs?tab=agents", clientUrl).href}`;
30549
+ }
30550
+ /** Printed when the person presses r during Device Approval: their choice, not a failure. */
30551
+ var SWITCHING_TO_RECOVERY_CODE = "Unlocking with your Recovery Code instead.";
30522
30552
  // ../client/src/lib/storage/fs/directory-adapter.ts
30523
30553
  /** All four, in skeleton-creation order. */
30524
30554
  var SUBDIRS = [
@@ -30727,9 +30757,9 @@ var CMD = /[\\/]_npx[\\/]/.test(process.argv[1] ?? "") ? "npx @appsoftwareltd/et
30727
30757
  var USAGE = `etherpk-mcp - EtherPK Headless Client (an MCP server over one synced graph)
30728
30758
 
30729
30759
  ${CMD} login --sync-server <url> [--code <Agent Setup Code>] [--recovery-code]
30730
- Sign in this computer as a device of your account. Create an Agent Setup Code in EtherPK
30760
+ Sign in this device as one of your account's devices. Create an Agent Setup Code in EtherPK
30731
30761
  (the Graphs page's Agents tab, or a synced graph's Settings > Agents, or <url>/account/tokens) and pass it with --code: it works once, within 10
30732
- minutes, and gets this computer an Agent Token limited to the routes an agent needs. Then
30762
+ minutes, and gets this device an Agent Token limited to the routes an agent needs. Then
30733
30763
  unlock your Encryption Keys by Device Approval: confirm the matching code in EtherPK on
30734
30764
  any device where your Encryption Keys are unlocked, then press y. Press r while waiting,
30735
30765
  or pass --recovery-code, to type your Recovery Code instead (or ETHERPK_RECOVERY_CODE,
@@ -30743,7 +30773,7 @@ var USAGE = `etherpk-mcp - EtherPK Headless Client (an MCP server over one synce
30743
30773
  ${CMD} serve --graph <id or name> [--sync-server <url>] [--no-semantic]
30744
30774
  Serve one synced graph to an agent over stdio. For Claude Code:
30745
30775
  claude mcp add --scope user etherpk -- npx @appsoftwareltd/etherpk-mcp serve --sync-server <url> --graph <id>
30746
- Once "semantic setup" has run on this computer, serve also keeps a search-by-meaning
30776
+ Once "semantic setup" has run on this device, serve also keeps a search-by-meaning
30747
30777
  store of the graph current (the agent's search tool gains mode: semantic) - pass
30748
30778
  --no-semantic to leave it off for this registration.
30749
30779
  Any number of agents can serve the same graph at once. The first one starts the graph's
@@ -30757,7 +30787,7 @@ var USAGE = `etherpk-mcp - EtherPK Headless Client (an MCP server over one synce
30757
30787
  makes them when it opens a folder) - its index is kept under the cache directory, never
30758
30788
  in the folder.
30759
30789
  ${CMD} running
30760
- List the graphs served on this computer: each one's background process, its agents and
30790
+ List the graphs served on this device: each one's background process, its agents and
30761
30791
  its log. A background process stops on its own once no agent has used it for five
30762
30792
  minutes (ETHERPK_MCP_HOST_IDLE_SECONDS sets another time).
30763
30793
  ${CMD} stop [--graph <id or name> [--sync-server <url>] | --folder <path> | --all]
@@ -30770,7 +30800,7 @@ var USAGE = `etherpk-mcp - EtherPK Headless Client (an MCP server over one synce
30770
30800
  ${CMD} semantic setup
30771
30801
  Let the agent search by meaning. Installs a ~300 MB native runtime (onnxruntime-node,
30772
30802
  with your npm) and downloads a 23 MB embedding model into the cache directory, once
30773
- per computer. Nothing leaves this computer when the model runs - notes are never sent
30803
+ per device. Nothing leaves this device when the model runs - notes are never sent
30774
30804
  to a service to be embedded.
30775
30805
  ${CMD} semantic status | remove
30776
30806
  Whether it is set up here, or delete it (logout --all deletes it too).
@@ -30796,7 +30826,7 @@ var USAGE = `etherpk-mcp - EtherPK Headless Client (an MCP server over one synce
30796
30826
  out of public logs.
30797
30827
  ${CMD} diagrams setup
30798
30828
  Let a publish draw Mermaid diagrams, maps and drawings. Downloads a Chromium (about 170 MB) into the
30799
- cache directory with Playwright's installer, once per computer - a publish whose pages hold
30829
+ cache directory with Playwright's installer, once per device - a publish whose pages hold
30800
30830
  diagrams, maps or drawings refuses until this has run. Set ETHERPK_CHROMIUM=<path> to use a browser
30801
30831
  already on this machine instead (NixOS needs this).
30802
30832
  ${CMD} diagrams status
@@ -30979,7 +31009,8 @@ async function login(args) {
30979
31009
  }));
30980
31010
  };
30981
31011
  const vaultKey = await (args["recovery-code"] ? byRecoveryCode() : approveOrFallBack(account, byRecoveryCode)).catch(abandon);
30982
- if (accessTokenKind(token) === "standard") {
31012
+ const exchangedAccessToken = accessTokenKind(token) === "standard";
31013
+ if (exchangedAccessToken) {
30983
31014
  const given = token;
30984
31015
  token = await exchangeForAgentToken({
30985
31016
  syncServer,
@@ -30988,20 +31019,16 @@ async function login(args) {
30988
31019
  }).catch(async (error) => {
30989
31020
  const reason = describeLoginFailure(error, syncServer);
30990
31021
  if (!await tokenStillWorks(syncServer, given)) return fail(`Could not swap the access token for an Agent Token (${reason}), and the access token you gave no longer works. Run login again with an Agent Setup Code.`);
30991
- return fail(`Could not swap the access token for an Agent Token (${reason}). Nothing was kept on this computer: run login again.`);
31022
+ return fail(`Could not swap the access token for an Agent Token (${reason}). Nothing was kept on this device: run login again.`);
30992
31023
  });
30993
- console.log("");
30994
- console.log(`The access token you gave has been revoked. This computer now holds an Agent Token, limited to the routes an agent needs. If you used that access token anywhere else, create a new one at ${syncServer}/account/tokens.`);
30995
31024
  }
31025
+ let replacedEarlierLogin = false;
30996
31026
  if (previous) {
30997
31027
  const before = await loginCredentials(syncServer, previous, keychain()).catch(() => null);
30998
- if (before && before.pat !== token && await revokeHeldToken({
31028
+ replacedEarlierLogin = before !== null && before.pat !== token && await revokeHeldToken({
30999
31029
  syncServer,
31000
31030
  token: before.pat
31001
- })) {
31002
- console.log("");
31003
- console.log(`Revoked the token this computer held for ${syncServer} before this login.`);
31004
- }
31031
+ });
31005
31032
  }
31006
31033
  const where = await saveLogin({
31007
31034
  config,
@@ -31013,17 +31040,19 @@ async function login(args) {
31013
31040
  },
31014
31041
  keychain: keychain()
31015
31042
  });
31016
- console.log("");
31017
- console.log(where === path ? `Encryption Keys unlocked and kept in ${path} (owner-only). Anyone who can read your files on this machine can read this account, as with a signed-in browser. Never let an agent read, print or search that file.` : `Encryption Keys unlocked and kept in ${where}; ${path} names only the server. A program you run can still ask ${where} for them, so run only agents you trust with this account.`);
31018
31043
  const others = Object.keys(config.servers).filter((server) => server !== syncServer);
31019
- if (others.length > 0) {
31020
- console.log("");
31021
- console.log(`Also logged in to ${others.join(", ")} - commands now need --sync-server <url> to say which.`);
31022
- }
31023
31044
  const restarted = await stopHosts(process.env, "a new login for its server", ({ status }) => status.target.kind === "synced" && status.target.server === syncServer);
31024
- if (restarted.length > 0) {
31045
+ for (const paragraph of loginSummary({
31046
+ syncServer,
31047
+ configPath: path,
31048
+ keptIn: where,
31049
+ exchangedAccessToken,
31050
+ replacedEarlierLogin,
31051
+ otherServers: others,
31052
+ stoppedHosts: restarted.length
31053
+ })) {
31025
31054
  console.log("");
31026
- console.log(`Stopped the background process of ${restarted.length === 1 ? "one graph" : `${restarted.length} graphs`} served with the previous login. Agents start a new one with this login on their next call.`);
31055
+ console.log(paragraph);
31027
31056
  }
31028
31057
  console.log("");
31029
31058
  await listGraphs({
@@ -31031,6 +31060,11 @@ async function login(args) {
31031
31060
  pat: token,
31032
31061
  vaultKey: toBase64Url(vaultKey)
31033
31062
  }, others.length > 0);
31063
+ const setup = agentSetupLine(account.clientUrl);
31064
+ if (setup) {
31065
+ console.log("");
31066
+ console.log(setup);
31067
+ }
31034
31068
  }
31035
31069
  /**
31036
31070
  * Device Approval, with the Recovery Code one keypress away: a user who has no unlocked EtherPK
@@ -31054,7 +31088,8 @@ async function approveOrFallBack(account, byRecoveryCode) {
31054
31088
  sleep: (ms) => sleepUnlessAborted(ms, controls.signal),
31055
31089
  codesMatch: () => controls.codesMatch,
31056
31090
  signal: controls.signal,
31057
- clientUrl: account.clientUrl
31091
+ clientUrl: account.clientUrl,
31092
+ offersRecoveryCode: interactive
31058
31093
  };
31059
31094
  const onKey = (chunk) => controls.onKey(chunk.toString("utf8"));
31060
31095
  const onInputEnd = () => controls.onInputClosed();
@@ -31065,11 +31100,8 @@ async function approveOrFallBack(account, byRecoveryCode) {
31065
31100
  ];
31066
31101
  const onSignal = (name) => controls.onSignal(name);
31067
31102
  for (const name of quitSignals) process.once(name, onSignal);
31068
- if (interactive) {
31069
- console.log("");
31070
- console.log("**Press r to type your Recovery Code instead.**");
31071
- stdin.setRawMode(true);
31072
- } else stdin.on("end", onInputEnd);
31103
+ if (interactive) stdin.setRawMode(true);
31104
+ else stdin.on("end", onInputEnd);
31073
31105
  stdin.resume();
31074
31106
  stdin.on("data", onKey);
31075
31107
  let abandoned = false;
@@ -31090,10 +31122,10 @@ async function approveOrFallBack(account, byRecoveryCode) {
31090
31122
  process.exit(controls.exitCode);
31091
31123
  }
31092
31124
  if (!abandoned) throw new Error("unreachable");
31093
- if (controls.mismatched) fail("The codes did not match, so the request was cancelled. Something between this computer and your other device may have interfered. Run login again, or pass --recovery-code.");
31125
+ if (controls.mismatched) fail("The codes did not match, so the request was cancelled. Something between this device and your other device may have interfered. Run login again, or pass --recovery-code.");
31094
31126
  if (controls.inputClosed) fail("Device approval needs someone to confirm the code it shows. Run login in a terminal and press y when the codes match, or pass --recovery-code, or set ETHERPK_RECOVERY_CODE.");
31095
31127
  console.log("");
31096
- console.log("Approval cancelled - unlocking with your Recovery Code instead.");
31128
+ console.log(SWITCHING_TO_RECOVERY_CODE);
31097
31129
  return byRecoveryCode();
31098
31130
  }
31099
31131
  /**
@@ -31142,7 +31174,7 @@ async function openVaultFor(account, login) {
31142
31174
  try {
31143
31175
  return await openAccountVault(account.api, fromBase64Url(login.vaultKey));
31144
31176
  } catch (error) {
31145
- if (error instanceof EnvelopeError) throw new Error(`Your Encryption Keys on ${login.syncServer} were replaced or reset on another device, so the key saved on this computer no longer opens them. Run: ${CMD} login --sync-server ${login.syncServer}`);
31177
+ if (error instanceof EnvelopeError) throw new Error(`Your Encryption Keys on ${login.syncServer} were replaced or reset on another device, so the key saved on this device no longer opens them. Run: ${CMD} login --sync-server ${login.syncServer}`);
31146
31178
  throw error;
31147
31179
  }
31148
31180
  }
@@ -31171,7 +31203,8 @@ async function semanticCommand(what) {
31171
31203
  case "setup":
31172
31204
  await setupSemantic({
31173
31205
  env: process.env,
31174
- say: (line) => console.log(line)
31206
+ say: (line) => console.log(line),
31207
+ command: CMD
31175
31208
  });
31176
31209
  return;
31177
31210
  case "status": {
@@ -31265,9 +31298,9 @@ async function publishCommand(args) {
31265
31298
  return;
31266
31299
  case "refused": return fail(reply.message);
31267
31300
  case "failed":
31268
- if ((dryRun || github) && reply.message === "The request was not understood.") return fail(`etherpk-mcp: this graph is served on this computer by an older etherpk-mcp, which cannot ${dryRun ? "run a dry run" : "publish to a repository"}. Run: ${CMD} stop, then try again.`);
31301
+ if ((dryRun || github) && reply.message === "The request was not understood.") return fail(`etherpk-mcp: this graph is served on this device by an older etherpk-mcp, which cannot ${dryRun ? "run a dry run" : "publish to a repository"}. Run: ${CMD} stop, then try again.`);
31269
31302
  return fail(`etherpk-mcp: ${reply.message}`);
31270
- case "unsupported": return fail(`etherpk-mcp: this graph is served on this computer by etherpk-mcp ${reply.version}, which cannot run a publish for this version (${VERSION}). Run: ${CMD} stop, then publish again.`);
31303
+ case "unsupported": return fail(`etherpk-mcp: this graph is served on this device by etherpk-mcp ${reply.version}, which cannot run a publish for this version (${VERSION}). Run: ${CMD} stop, then publish again.`);
31271
31304
  default: return fail(`etherpk-mcp: the graph's background process gave an answer this version does not know ("${reply.etherpk}").`);
31272
31305
  }
31273
31306
  }
@@ -31503,7 +31536,7 @@ async function serve(args) {
31503
31536
  return unavailable(request, reply.message);
31504
31537
  case "unsupported":
31505
31538
  socket.destroy();
31506
- return unavailable(request, `This graph is served on this computer by etherpk-mcp ${reply.version}, which cannot share it with this version (${VERSION}). Run: ${CMD} stop, then restart your agents.`);
31539
+ return unavailable(request, `This graph is served on this device by etherpk-mcp ${reply.version}, which cannot share it with this version (${VERSION}). Run: ${CMD} stop, then restart your agents.`);
31507
31540
  default:
31508
31541
  socket.destroy();
31509
31542
  return unavailable(request, `The graph's background process gave an answer this version does not know ("${reply.etherpk}"). Run: ${CMD} stop, then restart your agents.`);
@@ -31647,7 +31680,7 @@ async function openSyncedGraph(syncServer, graphId, named) {
31647
31680
  console.error(`etherpk-mcp: could not tidy the cache of graphs this server no longer lists: ${describeError(error)}`);
31648
31681
  return [];
31649
31682
  });
31650
- if (swept.length > 0) console.error(`etherpk-mcp: removed this computer's copy of ${swept.length === 1 ? "a graph" : `${swept.length} graphs`} ${account.serverBaseUrl} no longer lists for you: ${swept.join(", ")}.`);
31683
+ if (swept.length > 0) console.error(`etherpk-mcp: removed this device's copy of ${swept.length === 1 ? "a graph" : `${swept.length} graphs`} ${account.serverBaseUrl} no longer lists for you: ${swept.join(", ")}.`);
31651
31684
  const listed = graphs.find((graph) => graph.id === graphId);
31652
31685
  if (!listed) throw new Error(`No synced graph on ${login.syncServer} is identified by "${graphId}". Run: ${CMD} graphs`);
31653
31686
  const label = await graphLabel(listed, vault).catch(() => null);
@@ -31726,7 +31759,7 @@ async function startSemantic(graph) {
31726
31759
  start();
31727
31760
  return;
31728
31761
  }
31729
- console.error(`etherpk-mcp: semantic search is not set up on this computer (run: ${CMD} semantic setup - this process will notice within half a minute, no restart needed). Search answers by text only until then.`);
31762
+ console.error(`etherpk-mcp: semantic search is not set up on this device (run: ${CMD} semantic setup - this process will notice within half a minute, no restart needed). Search answers by text only until then.`);
31730
31763
  whenSemanticSetUp(process.env, () => {
31731
31764
  console.error("etherpk-mcp: semantic setup found - loading the model and building the store.");
31732
31765
  start();
@@ -31740,7 +31773,7 @@ function describeHostTarget(target) {
31740
31773
  async function runningCommand() {
31741
31774
  const hosts = await runningHosts(process.env);
31742
31775
  if (hosts.length === 0) {
31743
- console.log("No graph is being served on this computer.");
31776
+ console.log("No graph is being served on this device.");
31744
31777
  return;
31745
31778
  }
31746
31779
  for (const { cacheDir, status } of hosts) {
@@ -31774,7 +31807,7 @@ async function stopCommand(args) {
31774
31807
  };
31775
31808
  const stopped = await stopHosts(process.env, "stop was run", which);
31776
31809
  if (stopped.length === 0) {
31777
- console.log(path || wanted ? "That graph is not being served on this computer." : "No graph is being served on this computer.");
31810
+ console.log(path || wanted ? "That graph is not being served on this device." : "No graph is being served on this device.");
31778
31811
  return;
31779
31812
  }
31780
31813
  for (const host of stopped) console.log(`${host.stopped ? "Stopped" : "Could not stop"} the background process of "${host.status.graph.name}" (${describeHostTarget(host.status.target)}, process ${host.status.pid}).`);