@ai-wayfinding/client 0.1.1

package/README.md

@@ -0,0 +1,90 @@
+# Journey agent client
+
+The `wayfinding` command gives an agent access to one encrypted journey after a person approves it. It also runs a Model Context Protocol (MCP) server over standard input and output. Agents can read, add items, and comment; **they cannot change journey membership or access**. Read-only agents cannot write.
+
+## Install
+
+Node.js 22 or newer is required. Download both packages from the [latest release](https://github.com/AI-Wayfinding/journey/releases/latest), then install them together:
+
+```sh
+R=https://github.com/AI-Wayfinding/journey/releases/latest/download
+curl -fsSLO "$R/ai-wayfinding-core.tgz"
+curl -fsSLO "$R/ai-wayfinding-client.tgz"
+npm install -g ./ai-wayfinding-core.tgz ./ai-wayfinding-client.tgz
+wayfinding --help
+```
+
+Downloading first works even where npm is set to refuse installs from a URL.
+
+### Build from this repository
+
+The packages are not on npm. From a clone of this repository:
+
+```sh
+npm ci
+npm run build -w packages/core
+npm run build -w packages/client
+npm pack -w packages/core
+npm pack -w packages/client
+# Install both local tarballs together. The client needs the unpublished core package.
+npm install -g ./ai-wayfinding-core-*.tgz ./ai-wayfinding-client-*.tgz
+wayfinding --help
+```
+
+If a global install is not wanted, run `node packages/client/dist/cli.js --help` from the clone after building. A GitHub URL is not a reliable npm install target for one package inside this workspace; installing the root does not install the client binary. The two local tarballs are the supported install path for now. The client uses the MCP SDK version 1.30.1; no other direct runtime dependency is added.
+
+## Connect to a journey
+
+```sh
+wayfinding connect <journey-id> --scope read
+wayfinding connect <journey-id> --scope readwrite --remember
+```
+
+The journey server defaults to `https://app.wayfinding.support`; use `--server https://your-server` if needed. The command creates a new age encryption identity and signing key **in memory**, asks the server for approval, and prints a link and a six-digit code. Open the link in your browser, check that the code matches, choose the approved access and time, then confirm with your passkey. The command waits until approval, expiry, or lockout. Approval is valid for at most 8 hours without remembering, or 90 days when remembered. The person must choose remembered access in the approval screen before keys are saved; the client refuses expired keys.
+
+Without `--remember`, the one-shot `connect` command does not save keys. It closes the connection when it exits. Start `wayfinding mcp --connect <journey-id>` to keep an in-memory connection for that MCP process, or pass `--journey <journey-id>` to an individual CLI command to ask for fresh approval on each invocation. There is no background daemon and no invisible persistent login.
+
+With `--remember`, agent keys go to macOS Keychain (`security`) or Linux Secret Service (`secret-tool`). Unlock/install that service first. If the OS keychain is unavailable or the platform is unsupported, the command refuses instead of storing unencrypted keys. Windows users can use `--key-folder <path>` with a passphrase; there is no Windows Credential Manager adapter. On every OS, `--key-folder <path> --remember` stores an age-passphrase-encrypted `agent.age` in a private folder (0700 folder, 0600 file on Unix). Set `WAYFINDING_PASSPHRASE` or enter it at the terminal when prompted; the passphrase is never stored. Do not choose a shared folder.
+
+`wayfinding disconnect` removes the remembered keys and the local cache. When using `--key-folder`, pass the **same folder** to both connect and disconnect. Server-side membership remains until the person removes the agent or the approval expires.
+
+## Work with an approved journey
+
+```sh
+wayfinding status
+wayfinding list --type resource
+wayfinding search "journey words"
+wayfinding show <item-id>
+wayfinding add --type resource --title "A useful link" --body "Notes" --tags reading,guide
+wayfinding import ./notes.md
+wayfinding import ./markdown-folder
+wayfinding comment <item-id> "A follow-up"
+wayfinding comments <item-id>
+```
+
+Markdown imports retain simple front matter fields `title`, `type` (or `itemType`), `tags` (comma-separated or inline array), `created`, `resourceKind`, and `sharedFrom`; the remaining Markdown is the body. Files must have `.md` extensions. The agent is always marked as the author, regardless of input front matter. For a directory, Markdown files are read recursively.
+
+Each read checks the full signed journey membership log. Before a write, the client checks that log again, confirms this agent is still an active read-write member and that its version meets the journey minimum, then encrypts the item or comment locally. Server requests are signed with the method, path and query, body digest, timestamp, and fresh nonce. If access ends, the client says so and stops. Keys and decrypted items remain in memory for the process lifetime.
+
+### Optional encrypted-data cache
+
+A remembered session uses a local cache by default. An in-memory connection uses no cache by default. Pass `--cache` to enable it for a one-shot command or `--no-cache` to disable it. Under the OS cache directory (macOS: `~/Library/Caches`; Linux: `$XDG_CACHE_HOME` or `~/.cache`; Windows: `%LOCALAPPDATA%`), the client stores **only ciphertext envelopes and the head of a freshly verified signed log**. The journey key, secret signing key, item titles, and item bodies never go to this cache. On Unix, cache folders are 0700 and files 0600. The client refreshes records by sequence number but verifies the full signed log again before every use. Disable the cache on a shared device.
+
+## Connect an MCP tool host
+
+The MCP server exposes `add`, `import`, `list`, `search`, `show`, `comment`, `comments`, `status`, and `connect_status`. Tool descriptions explain that the person approves access. Standard output is reserved for MCP messages; approval instructions go to standard error. With a remembered connection, use this command without `--connect`. With an in-memory connection, give the journey ID:
+
+```json
+{
+  "mcpServers": {
+    "wayfinding": {
+      "command": "wayfinding",
+      "args": ["mcp", "--connect", "YOUR_JOURNEY_ID"]
+    }
+  }
+}
+```
+
+For Claude Desktop, add the `mcpServers.wayfinding` entry to its MCP configuration. For Claude Code, use `claude mcp add wayfinding -- wayfinding mcp --connect YOUR_JOURNEY_ID`. For Codex, use `codex mcp add wayfinding -- wayfinding mcp --connect YOUR_JOURNEY_ID`. Use the absolute path to the built `cli.js` with `node` if `wayfinding` is not on the host's PATH. When the MCP process begins, the person sees the link and code in the host's standard-error log; approve it before the MCP connection finishes. Some hosts hide stderr: run `wayfinding connect <journey-id> --remember` in a terminal first, then configure `wayfinding mcp` without `--connect`.
+
+The person manages other members and any key rotation in the browser. An agent cannot approve itself, change someone's scope, add or remove members, or rotate journey keys. If the person previously rotated the journey key, the current approval API may not provide this agent the old epoch wraps needed to verify *all* earlier history; this client stops with a missing-key message rather than writing without verification.

package/dist/cache.d.ts

@@ -0,0 +1,15 @@
+import type { Envelope } from '@ai-wayfinding/core';
+export interface CipherRow {
+    seq: number;
+    entry: string;
+}
+export interface CipherCache {
+    seq: number;
+    hash: string;
+    log: CipherRow[];
+    records: Envelope[];
+}
+/** Only copy ciphertext envelopes and the head of a fully verified signed log. */
+export declare function writeCache(root: string, journeyId: string, cache: CipherCache): Promise<string>;
+export declare function readCache(root: string, journeyId: string): Promise<CipherCache | null>;
+export declare function forgetCache(root: string, journeyId: string): Promise<void>;

package/dist/cache.js

@@ -0,0 +1,45 @@
+import { chmod, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isId } from '@ai-wayfinding/core';
+function directory(root) { return join(root, 'ai-wayfinding', 'journeys'); }
+function location(root, journeyId) {
+    if (!isId(journeyId))
+        throw new Error('Invalid journey ID');
+    return join(directory(root), journeyId + '.json');
+}
+/** Only copy ciphertext envelopes and the head of a fully verified signed log. */
+export async function writeCache(root, journeyId, cache) {
+    const path = location(root, journeyId), dir = directory(root);
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    await chmod(join(root, 'ai-wayfinding'), 0o700);
+    await chmod(dir, 0o700);
+    const safe = { seq: cache.seq, hash: cache.hash, log: cache.log.map(row => ({ seq: row.seq, entry: row.entry })), records: cache.records.map(row => ({ outside: { v: 1, id: row.outside.id, journey: row.outside.journey, seq: row.outside.seq, epoch: row.outside.epoch, size: row.outside.size, createdAt: row.outside.createdAt }, nonce: row.nonce, ciphertext: row.ciphertext })) };
+    const temp = join(dir, '.' + crypto.randomUUID());
+    try {
+        await writeFile(temp, JSON.stringify(safe), { mode: 0o600, flag: 'wx' });
+        await rename(temp, path);
+        await chmod(path, 0o600);
+    }
+    finally {
+        await rm(temp, { force: true });
+    }
+    return path;
+}
+export async function readCache(root, journeyId) {
+    let value;
+    try {
+        value = JSON.parse(await readFile(location(root, journeyId), 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+    if (!value || typeof value !== 'object')
+        throw new Error('Invalid journey cache');
+    const row = value;
+    if (!Number.isSafeInteger(row.seq) || typeof row.hash !== 'string' || !Array.isArray(row.log) || !Array.isArray(row.records))
+        throw new Error('Invalid journey cache');
+    return row;
+}
+export async function forgetCache(root, journeyId) { await rm(location(root, journeyId), { force: true }); }

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function main(args?: string[]): Promise<void>;

package/dist/cli.js

@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+import { homedir } from 'node:os';
+import { stdin, stderr } from 'node:process';
+import { join } from 'node:path';
+import { connectJourney } from './connection.js';
+import { importMarkdown } from './import.js';
+import { JourneyClient } from './journey.js';
+import { runMcp } from './mcp.js';
+import { forgetRemembered, loadRemembered } from './storage.js';
+const help = `wayfinding — read and write an approved journey
+
+wayfinding connect <journey-id> [--name "Agent name"] [--scope read|readwrite] [--remember] [--server https://app.wayfinding.support] [--key-folder PATH]
+wayfinding disconnect [--key-folder PATH]
+wayfinding add --type TYPE --title TITLE --body TEXT [--tags a,b]
+wayfinding import <file-or-folder>
+wayfinding list [--type TYPE]
+wayfinding search <text>
+wayfinding show <id>
+wayfinding comment <id> <text>
+wayfinding comments <id>
+wayfinding status
+wayfinding mcp [--connect <journey-id>] [--name "Agent name"]
+
+Use --journey <journey-id> with any one-shot command to ask for approval each time without remembering keys.
+Use --cache to store only encrypted journey records and a verified log head; --no-cache turns it off.
+Keys never go into the local cache. An agent cannot change journey membership or access.`;
+const valueFlags = new Set(['--scope', '--name', '--server', '--key-folder', '--journey', '--connect', '--type', '--title', '--body', '--tags']);
+const boolFlags = new Set(['--remember', '--cache', '--no-cache', '--help']);
+function parse(args) {
+    const command = args[0] ?? '--help', flags = {}, positional = [];
+    for (let index = 1; index < args.length; index++) {
+        const part = args[index];
+        if (valueFlags.has(part)) {
+            if (args[index + 1] === undefined || args[index + 1].startsWith('--'))
+                throw new Error(part + ' needs a value.');
+            flags[part] = args[++index];
+        }
+        else if (boolFlags.has(part))
+            flags[part] = true;
+        else if (part.startsWith('-'))
+            throw new Error('Unknown option: ' + part);
+        else
+            positional.push(part);
+    }
+    return { command, positional, flags };
+}
+function flag(flags, key) { return typeof flags[key] === 'string' ? flags[key] : undefined; }
+async function passphrase(folder) {
+    if (!folder)
+        return undefined;
+    if (process.env.WAYFINDING_PASSPHRASE)
+        return process.env.WAYFINDING_PASSPHRASE;
+    if (!stdin.isTTY || !stdin.setRawMode)
+        throw new Error('A passphrase is required for --key-folder. Set WAYFINDING_PASSPHRASE or run from a terminal to enter it.');
+    stderr.write('Passphrase for the journey key folder: ');
+    return new Promise((resolve, reject) => {
+        let value = '';
+        const finish = (error) => {
+            stdin.removeListener('data', onData);
+            stdin.setRawMode(false);
+            stdin.pause();
+            stderr.write('\n');
+            if (error)
+                reject(error);
+            else if (!value)
+                reject(new Error('A journey key-folder passphrase cannot be empty.'));
+            else
+                resolve(value);
+        };
+        const onData = (chunk) => {
+            for (const byte of chunk) {
+                if (byte === 3) {
+                    finish(new Error('Cancelled.'));
+                    return;
+                }
+                if (byte === 13 || byte === 10) {
+                    finish();
+                    return;
+                }
+                if (byte === 127 || byte === 8)
+                    value = value.slice(0, -1);
+                else
+                    value += String.fromCharCode(byte);
+            }
+        };
+        stdin.setRawMode(true);
+        stdin.resume();
+        stdin.on('data', onData);
+    });
+}
+function cacheFolder() {
+    if (process.platform === 'win32')
+        return join(process.env.LOCALAPPDATA ?? join(homedir(), 'AppData', 'Local'), 'wayfinding', 'journeys');
+    if (process.platform === 'darwin')
+        return join(homedir(), 'Library', 'Caches', 'wayfinding', 'journeys');
+    return join(process.env.XDG_CACHE_HOME ?? join(homedir(), '.cache'), 'wayfinding', 'journeys');
+}
+export async function main(args = process.argv.slice(2)) {
+    const { command, positional, flags } = parse(args);
+    if (command === '--help' || command === 'help' || flags['--help']) {
+        console.log(help);
+        return;
+    }
+    const keyFolder = flag(flags, '--key-folder');
+    if (command === 'disconnect') {
+        await forgetRemembered({ folder: keyFolder });
+        const { rm } = await import('node:fs/promises');
+        await rm(cacheFolder(), { recursive: true, force: true });
+        console.log('Remembered journey keys and the local cache have been removed.');
+        return;
+    }
+    const secret = await passphrase(keyFolder);
+    const server = flag(flags, '--server'), scope = flag(flags, '--scope');
+    if (scope && scope !== 'read' && scope !== 'readwrite')
+        throw new Error('Use --scope read or --scope readwrite.');
+    const connect = async (journeyId, mcp = false) => connectJourney(journeyId, { server, scope: scope, name: flag(flags, '--name'), remember: !!flags['--remember'], keyFolder, passphrase: secret, onApproval: (url, code) => { (mcp ? console.error : console.log)('Open this link, check the code matches, and approve access to this journey: ' + url + '\nSix-digit code: ' + code); } });
+    if (command === 'connect') {
+        const journeyId = positional[0];
+        if (!journeyId)
+            throw new Error('Give the journey ID to connect.');
+        const { client } = await connect(journeyId);
+        client.close();
+        console.log(flags['--remember'] ? 'This journey is connected and the keys are remembered.' : 'Journey access was approved. No keys were saved; use wayfinding mcp --connect <journey-id> for an in-memory agent session, or --journey on each command.');
+        return;
+    }
+    let held;
+    const getClient = async () => {
+        if (held)
+            return held;
+        const oneShot = command === 'mcp' ? flag(flags, '--connect') : flag(flags, '--journey');
+        if (oneShot) {
+            held = (await connect(oneShot, command === 'mcp')).client;
+        }
+        else {
+            const session = await loadRemembered({ folder: keyFolder, passphrase: secret });
+            if (!session)
+                throw new Error('No remembered journey connection. Use wayfinding connect <journey-id> --remember, or --journey <journey-id> to ask for approval for this command. For an in-memory MCP session, use wayfinding mcp --connect <journey-id>.');
+            held = new JourneyClient(session, flags['--no-cache'] ? {} : { cacheRoot: cacheFolder() });
+        }
+        if ((flags['--cache'] || flags['--no-cache']) && held) {
+            // Cache is chosen when the client is constructed; ephemeral sessions default to no cache.
+            if (flags['--cache'] && oneShot)
+                held = new JourneyClient(held.session, { cacheRoot: cacheFolder() });
+            if (flags['--no-cache'] && oneShot)
+                held = new JourneyClient(held.session);
+        }
+        return held;
+    };
+    if (command === 'mcp') {
+        await runMcp(getClient);
+        return;
+    }
+    try {
+        const client = await getClient();
+        let result;
+        switch (command) {
+            case 'add': {
+                const type = flag(flags, '--type'), title = flag(flags, '--title'), body = flag(flags, '--body');
+                if (!type || !title || !body)
+                    throw new Error('Add needs --type, --title and --body.');
+                result = await client.add({ type, title, body, tags: flag(flags, '--tags')?.split(',').map(tag => tag.trim()).filter(Boolean) ?? [] });
+                break;
+            }
+            case 'import':
+                if (!positional[0])
+                    throw new Error('Give a Markdown file or folder to import.');
+                result = await importMarkdown(client, positional[0]);
+                break;
+            case 'list':
+                result = await client.list(flag(flags, '--type'));
+                break;
+            case 'search':
+                if (!positional[0])
+                    throw new Error('Give words to search for in the journey.');
+                result = await client.search(positional.join(' '));
+                break;
+            case 'show':
+                if (!positional[0])
+                    throw new Error('Give the journey item ID to show.');
+                result = await client.show(positional[0]);
+                break;
+            case 'comment':
+                if (!positional[0] || !positional[1])
+                    throw new Error('Give the journey item ID and comment text.');
+                result = await client.comment(positional[0], positional.slice(1).join(' '));
+                break;
+            case 'comments':
+                if (!positional[0])
+                    throw new Error('Give the journey item ID to read comments.');
+                result = await client.comments(positional[0]);
+                break;
+            case 'status':
+                result = await client.status();
+                break;
+            default: throw new Error('Unknown journey command: ' + command + '. Try wayfinding --help.');
+        }
+        console.log(JSON.stringify(result, null, 2));
+    }
+    finally {
+        held?.close();
+    }
+}
+main().catch(error => { console.error(error instanceof Error ? error.message : String(error)); process.exitCode = 1; });

package/dist/connection.d.ts

@@ -0,0 +1,19 @@
+import { JourneyClient } from './journey.js';
+import type { RememberedAgent } from './storage.js';
+export interface ConnectOptions {
+    server?: string;
+    scope?: 'read' | 'readwrite';
+    name?: string;
+    remember?: boolean;
+    keyFolder?: string;
+    passphrase?: string;
+    fetch?: typeof fetch;
+    pollMs?: number;
+    onApproval?: (url: string, code: string) => void;
+}
+export interface Connection {
+    client: JourneyClient;
+    session: RememberedAgent;
+}
+export declare const DEFAULT_SERVER = "https://app.wayfinding.support";
+export declare function connectJourney(journeyId: string, options?: ConnectOptions): Promise<Connection>;

package/dist/connection.js

@@ -0,0 +1,51 @@
+import { createAgeIdentity, createSigningIdentity, validAgentName } from '@ai-wayfinding/core';
+import { JourneyClient } from './journey.js';
+import { saveRemembered } from './storage.js';
+export const DEFAULT_SERVER = 'https://app.wayfinding.support';
+const sleep = (milliseconds) => new Promise(resolve => setTimeout(resolve, milliseconds));
+export async function connectJourney(journeyId, options = {}) {
+    const server = (options.server ?? DEFAULT_SERVER).replace(/\/$/, '');
+    const origin = new URL(server);
+    if (origin.protocol !== 'https:' && !(origin.protocol === 'http:' && (origin.hostname === 'localhost' || origin.hostname === '127.0.0.1')))
+        throw new Error('The journey server must use HTTPS (except on this computer).');
+    if (options.keyFolder && !options.remember)
+        throw new Error('--key-folder needs --remember.');
+    if (options.name !== undefined && !validAgentName(options.name))
+        throw new Error('Agent name must be trimmed, 1–60 characters and contain no control characters.');
+    const identity = await createAgeIdentity(), signing = await createSigningIdentity();
+    const response = await (options.fetch ?? fetch)(server + '/v1/agent-sessions', { method: 'POST', headers: { 'Content-Type': 'application/json', Origin: origin.origin, 'X-Wayfinding': '1' }, body: JSON.stringify({ journeyId, agentPublicKey: { recipient: identity.recipient, signingKey: signing.publicKey }, requestedScope: options.scope ?? 'read', remembered: options.remember === true, ...(options.name === undefined ? {} : { name: options.name }) }) });
+    if (!response.ok)
+        throw new Error('Could not ask to join this journey (' + response.status + ').');
+    const created = await response.json();
+    options.onApproval?.(created.approvalUrl, created.code);
+    let approved;
+    for (;;) {
+        await sleep(options.pollMs ?? 3000);
+        const polled = await (options.fetch ?? fetch)(server + '/v1/agent-sessions/' + encodeURIComponent(created.id));
+        if (!polled.ok)
+            throw new Error('Could not check journey approval (' + polled.status + ').');
+        approved = await polled.json();
+        if (approved.status === 'approved')
+            break;
+        if (approved.status !== 'pending')
+            throw new Error(approved.status === 'locked' ? 'Too many wrong approval codes. Ask for a new journey connection.' : 'Journey approval expired or was refused. Connect again.');
+    }
+    if (options.remember && !approved.remembered)
+        throw new Error('The person did not approve remembered journey access.');
+    if (!Number.isFinite(approved.expiresAt) || approved.expiresAt <= Date.now() || approved.expiresAt > Date.now() + (options.remember ? 90 * 86_400_000 : 8 * 3_600_000) + 60_000)
+        throw new Error('Invalid journey access expiry. Connect again.');
+    const session = { server, journeyId, sessionId: created.id, principal: approved.principal, identity: identity.identity, recipient: identity.recipient, signingPrivateKey: signing.privateKey, signingKey: signing.publicKey, scope: approved.scope, expiresAt: approved.expiresAt };
+    const client = new JourneyClient(session, { fetch: options.fetch });
+    try {
+        await client.status();
+    }
+    catch (error) {
+        client.close();
+        throw error;
+    }
+    if (options.remember) {
+        const store = options.keyFolder ? { folder: options.keyFolder, passphrase: options.passphrase } : {};
+        await saveRemembered(session, store);
+    }
+    return { client, session };
+}

package/dist/import.d.ts

@@ -0,0 +1,3 @@
+import type { JourneyClient } from './journey.js';
+/** Read only the simple fields shared by Markdown front matter and journey items. */
+export declare function importMarkdown(client: Pick<JourneyClient, 'add'>, path: string): Promise<unknown[]>;

package/dist/import.js

@@ -0,0 +1,46 @@
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { join, basename } from 'node:path';
+/** Read only the simple fields shared by Markdown front matter and journey items. */
+export async function importMarkdown(client, path) {
+    const files = [];
+    async function collect(name) {
+        if ((await stat(name)).isDirectory()) {
+            for (const entry of await readdir(name, { withFileTypes: true })) {
+                if (entry.isFile() || entry.isDirectory())
+                    await collect(join(name, entry.name));
+            }
+        }
+        else if (/\.md$/i.test(name))
+            files.push(name);
+    }
+    await collect(path);
+    if (files.length === 0)
+        throw new Error('No Markdown files found to import into this journey.');
+    const results = [];
+    for (const file of files.sort()) {
+        const markdown = await readFile(file, 'utf8');
+        const front = {};
+        let body = markdown;
+        const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(markdown);
+        if (match) {
+            body = markdown.slice(match[0].length);
+            for (const line of match[1].split(/\r?\n/)) {
+                const pair = /^([A-Za-z][A-Za-z0-9]*):\s*(.*?)\s*$/.exec(line);
+                if (pair)
+                    front[pair[1]] = pair[2].replace(/^(['"])(.*)\1$/, '$2');
+            }
+        }
+        const title = front.title || basename(file).replace(/\.md$/i, '');
+        const type = front.itemType || front.type || 'resource';
+        const tags = front.tags ? (front.tags.startsWith('[') ? front.tags.slice(1, -1) : front.tags).split(',').map(tag => tag.trim().replace(/^['"]|['"]$/g, '')).filter(Boolean) : [];
+        const item = { type, title, body, tags };
+        if (front.created)
+            item.created = front.created;
+        if (front.resourceKind)
+            item.resourceKind = front.resourceKind;
+        if (front.sharedFrom)
+            item.sharedFrom = front.sharedFrom;
+        results.push(await client.add(item));
+    }
+    return results;
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { connectJourney } from './connection.js';
+export type { ConnectOptions, Connection } from './connection.js';
+export { JourneyClient } from './journey.js';
+export type { AddInput, ItemView, JourneyOptions } from './journey.js';
+export { createWayfindingServer } from './mcp.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { connectJourney } from './connection.js';
+export { JourneyClient } from './journey.js';
+export { createWayfindingServer } from './mcp.js';

package/dist/journey.d.ts

@@ -0,0 +1,45 @@
+import type { CommentBody, ItemBody } from '@ai-wayfinding/core';
+import type { RememberedAgent } from './storage.js';
+export interface AddInput {
+    type: string;
+    title: string;
+    body: string;
+    tags: string[];
+    created?: string;
+    resourceKind?: string;
+    sharedFrom?: string;
+}
+export interface JourneyOptions {
+    fetch?: typeof fetch;
+    cacheRoot?: string;
+}
+export interface ItemView {
+    item: ItemBody;
+    comments: CommentBody[];
+}
+export declare class JourneyClient {
+    readonly session: RememberedAgent;
+    private readonly options;
+    private readonly fetcher;
+    private readonly keys;
+    constructor(session: RememberedAgent, options?: JourneyOptions);
+    private request;
+    private verified;
+    private records;
+    private writable;
+    private write;
+    add(input: AddInput): Promise<ItemBody>;
+    list(type?: string): Promise<ItemBody[]>;
+    search(text: string): Promise<ItemBody[]>;
+    show(id: string): Promise<ItemView>;
+    comments(id: string): Promise<CommentBody[]>;
+    comment(id: string, text: string): Promise<CommentBody>;
+    status(): Promise<{
+        journeyId: string;
+        principal: string;
+        scope: 'read' | 'readwrite';
+        expiresAt: number;
+        seq: number;
+    }>;
+    close(): void;
+}

package/dist/journey.js

@@ -0,0 +1,195 @@
+import { CLIENT_VERSION, meetsMinClientVersion, newId, open, parseRecord, seal, unwrapJourneyKey, verifyLog } from '@ai-wayfinding/core';
+import { readCache, writeCache } from './cache.js';
+import { signedHeaders } from './signing.js';
+const historyError = 'This journey history could not be verified. Stop and ask a member for help.';
+function decode(value) { return JSON.parse(Buffer.from(value, 'base64url').toString('utf8')); }
+export class JourneyClient {
+    session;
+    options;
+    fetcher;
+    keys = new Map();
+    constructor(session, options = {}) {
+        this.session = session;
+        this.options = options;
+        this.fetcher = options.fetch ?? fetch;
+    }
+    async request(path, method = 'GET', data) {
+        if (this.session.expiresAt <= Date.now())
+            throw new Error('Your journey agent access has expired. Connect again.');
+        const body = data === undefined ? '' : JSON.stringify(data);
+        const route = '/v1' + path;
+        const headers = await signedHeaders(this.session.signingPrivateKey, method, route, body);
+        const result = await this.fetcher(this.session.server + route, { method, headers: { ...headers, 'X-Agent-Session': this.session.sessionId, ...(data === undefined ? {} : { 'Content-Type': 'application/json', Origin: new URL(this.session.server).origin, 'X-Wayfinding': '1' }) }, ...(data === undefined ? {} : { body }) });
+        if (!result.ok) {
+            if (result.status === 403 || result.status === 401)
+                throw new Error('Access to this journey has ended');
+            const error = await result.json().catch(() => null);
+            const code = error && typeof error === 'object' && 'error' in error && error.error && typeof error.error === 'object' && 'code' in error.error ? String(error.error.code) : String(result.status);
+            throw new Error('Journey request failed (' + code + ').');
+        }
+        return result.json();
+    }
+    async verified() {
+        // Never trust a cache head without decrypting and verifying the entire signed chain.
+        const cached = this.options.cacheRoot ? await readCache(this.options.cacheRoot, this.session.journeyId).catch(() => null) : null;
+        const log = cached?.log ? [...cached.log] : [];
+        for (;;) {
+            const after = log.length ? '?after=' + (log.at(-1).seq) : '';
+            const page = (await this.request(`/journeys/${this.session.journeyId}/log${after}`)).log;
+            if (!Array.isArray(page))
+                throw new Error(historyError);
+            log.push(...page);
+            if (log.length > 100_000)
+                throw new Error('Journey history is too large.');
+            if (page.length < 1000)
+                break;
+        }
+        const response = await this.request(`/journeys/${this.session.journeyId}/wraps/me`);
+        const epochs = new Map();
+        for (const wrap of response.wraps) {
+            if (!Number.isSafeInteger(wrap.epoch) || wrap.epoch < 1)
+                throw new Error(historyError);
+            const key = this.keys.get(wrap.epoch) ?? await unwrapJourneyKey({ epoch: wrap.epoch, recipient: this.session.principal, ciphertext: wrap.wrap }, this.session.identity);
+            this.keys.set(wrap.epoch, key);
+            epochs.set(wrap.epoch, key);
+        }
+        const entries = [];
+        for (const row of log) {
+            const envelope = decode(row.entry);
+            if (row.seq !== entries.length || envelope.outside?.journey !== this.session.journeyId)
+                throw new Error(historyError);
+            const key = epochs.get(envelope.outside.epoch);
+            if (!key)
+                throw new Error('Missing a key for the journey history. Ask a member to approve access again.');
+            const record = await open(envelope, key).catch(() => { throw new Error(historyError); });
+            if (record.type !== 'membership' || record.typeVersion !== 1)
+                throw new Error(historyError);
+            const wrapped = record.body.entry;
+            const entry = typeof wrapped === 'string' ? JSON.parse(wrapped) : record.body;
+            entries.push(entry);
+        }
+        const checked = await verifyLog(entries);
+        if (!checked.ok || checked.state.journey !== this.session.journeyId)
+            throw new Error(historyError);
+        const mine = checked.state.members[this.session.principal]?.member;
+        if (!mine || mine.kind !== 'agent' || mine.signingKey !== this.session.signingKey || mine.recipient !== this.session.recipient || mine.expiresAt && Date.parse(mine.expiresAt) <= Date.now())
+            throw new Error('Access to this journey has ended');
+        if (!meetsMinClientVersion(CLIENT_VERSION, checked.state.minClientVersion))
+            throw new Error('This journey needs a newer client version. Update wayfinding before writing.');
+        if (!epochs.has(checked.state.currentEpoch))
+            throw new Error('The journey key changed. Ask a member to reconnect this agent.');
+        if (this.options.cacheRoot && (!cached || cached.seq !== checked.state.lastSeq || cached.hash !== checked.state.lastHash))
+            await writeCache(this.options.cacheRoot, this.session.journeyId, { seq: checked.state.lastSeq, hash: checked.state.lastHash, log, records: cached?.records ?? [] });
+        return { state: checked.state, epochs, log };
+    }
+    async records(verified) {
+        const cached = this.options.cacheRoot ? await readCache(this.options.cacheRoot, this.session.journeyId).catch(() => null) : null;
+        const envelopes = cached?.records ? [...cached.records] : [];
+        let after = envelopes.at(-1)?.outside.seq ?? 0;
+        for (;;) {
+            const page = (await this.request(`/journeys/${this.session.journeyId}/records?after=${after}&limit=100`)).records;
+            if (!Array.isArray(page))
+                throw new Error('Invalid journey records.');
+            for (const envelope of page) {
+                if (envelope.outside?.seq !== after + 1 || envelope.outside.journey !== this.session.journeyId)
+                    throw new Error('Invalid journey records.');
+                after = envelope.outside.seq;
+                envelopes.push(envelope);
+            }
+            if (envelopes.length > 100_000)
+                throw new Error('Too many journey records.');
+            if (page.length < 100)
+                break;
+        }
+        const records = [];
+        for (const envelope of envelopes) {
+            const key = verified.epochs.get(envelope.outside.epoch);
+            if (!key || envelope.outside.epoch > verified.state.currentEpoch)
+                throw new Error('Missing a key for the journey records.');
+            const record = await open(envelope, key);
+            parseRecord(record);
+            records.push(record);
+        }
+        if (this.options.cacheRoot)
+            await writeCache(this.options.cacheRoot, this.session.journeyId, { seq: verified.state.lastSeq, hash: verified.state.lastHash, log: verified.log, records: envelopes });
+        return records;
+    }
+    async writable() {
+        const verified = await this.verified();
+        if (verified.state.members[this.session.principal]?.member.scope !== 'readwrite')
+            throw new Error('This journey is read-only for this agent. Ask a person to approve write access.');
+        return verified;
+    }
+    async write(record, verified) {
+        if (parseRecord(record).kind !== 'known')
+            throw new Error('Unknown journey record type.');
+        const { seq, epoch } = await this.request(`/journeys/${this.session.journeyId}/seq`, 'POST', {});
+        if (epoch !== verified.state.currentEpoch)
+            throw new Error('The journey key changed. Reload before writing.');
+        const key = verified.epochs.get(epoch);
+        const envelope = await seal(record, { id: newId(), journey: this.session.journeyId, seq, epoch, createdAt: new Date().toISOString() }, key);
+        await this.request(`/journeys/${this.session.journeyId}/records`, 'POST', { envelope });
+    }
+    async add(input) {
+        const verified = await this.writable();
+        const item = { id: newId(), itemType: input.type, title: input.title, body: input.body, tags: [...input.tags], author: this.session.principal, authoredBy: 'agent', created: input.created ?? new Date().toISOString(), ...(input.resourceKind ? { resourceKind: input.resourceKind } : {}), ...(input.sharedFrom ? { sharedFrom: input.sharedFrom } : {}) };
+        await this.write({ type: 'item', typeVersion: 1, body: item }, verified);
+        return item;
+    }
+    async list(type) {
+        const records = await this.records(await this.verified());
+        const roots = new Map(), items = new Map(), deleted = new Set();
+        for (const record of records) {
+            if (record.type === 'item') {
+                const item = record.body;
+                const root = item.replaces ? roots.get(item.replaces) : item.id;
+                if (root) {
+                    roots.set(item.id, root);
+                    items.set(root, item);
+                }
+            }
+            else if (record.type === 'delete')
+                deleted.add(String(record.body.target));
+        }
+        return [...items.entries()].filter(([id, item]) => !deleted.has(id) && (!type || type === item.itemType)).map(([, item]) => item);
+    }
+    async search(text) { const needle = text.toLocaleLowerCase(); return (await this.list()).filter(item => [item.title, item.body, item.itemType, ...item.tags].some(value => value.toLocaleLowerCase().includes(needle))); }
+    async show(id) {
+        const records = await this.records(await this.verified());
+        const roots = new Map(), items = new Map(), comments = [], deleted = new Set();
+        for (const record of records) {
+            if (record.type === 'item') {
+                const item = record.body, root = item.replaces ? roots.get(item.replaces) : item.id;
+                if (root) {
+                    roots.set(item.id, root);
+                    items.set(root, item);
+                }
+            }
+            if (record.type === 'comment')
+                comments.push(record.body);
+            if (record.type === 'delete')
+                deleted.add(String(record.body.target));
+        }
+        const root = roots.get(id), item = root && !deleted.has(root) ? items.get(root) : undefined;
+        if (!item)
+            throw new Error('No journey item has that ID.');
+        return { item, comments: comments.filter(comment => roots.get(comment.item) === root) };
+    }
+    async comments(id) { return (await this.show(id)).comments; }
+    async comment(id, text) {
+        const verified = await this.writable();
+        const records = await this.records(verified);
+        const root = records.find(record => record.type === 'item' && record.body.id === id);
+        if (!root)
+            throw new Error('No journey item has that ID.');
+        const comment = { id: newId(), item: id, onVersion: id, author: this.session.principal, authoredBy: 'agent', at: new Date().toISOString(), body: text };
+        await this.write({ type: 'comment', typeVersion: 1, body: comment }, verified);
+        return comment;
+    }
+    async status() {
+        const { state } = await this.verified();
+        return { journeyId: this.session.journeyId, principal: this.session.principal, scope: state.members[this.session.principal].member.scope, expiresAt: this.session.expiresAt, seq: state.lastSeq };
+    }
+    close() { for (const value of this.keys.values())
+        value.key.fill(0); this.keys.clear(); }
+}

package/dist/mcp.d.ts

@@ -0,0 +1,4 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { JourneyClient } from './journey.js';
+export declare function createWayfindingServer(getClient: () => Promise<JourneyClient>): Server;
+export declare function runMcp(getClient: () => Promise<JourneyClient>): Promise<void>;

package/dist/mcp.js

@@ -0,0 +1,82 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { importMarkdown } from './import.js';
+const text = { type: 'string' };
+const schema = (properties, required = []) => ({ type: 'object', properties, required, additionalProperties: false });
+const tools = [
+    { name: 'add', description: 'Add an item to the journey. The person must approve read-write access first; the agent cannot change membership or access.', inputSchema: schema({ type: text, title: text, body: text, tags: { type: 'array', items: text } }, ['type', 'title', 'body']) },
+    { name: 'import', description: 'Add Markdown files from this computer to the journey. The person must approve read-write access first.', inputSchema: schema({ path: text }, ['path']) },
+    { name: 'list', description: 'List decrypted journey items, optionally by type. The person must approve access first.', inputSchema: schema({ type: text }) },
+    { name: 'search', description: 'Find words in decrypted journey item titles, tags, and bodies. The person must approve access first.', inputSchema: schema({ text: text }) },
+    { name: 'show', description: 'Read one journey item by its ID. The person must approve access first.', inputSchema: schema({ id: text }, ['id']) },
+    { name: 'comment', description: 'Add a comment to a journey item. The person must approve read-write access first.', inputSchema: schema({ id: text, text: text }, ['id', 'text']) },
+    { name: 'comments', description: 'Read comments for a journey item. The person must approve access first.', inputSchema: schema({ id: text }, ['id']) },
+    { name: 'status', description: 'Check this journey and your approved scope.', inputSchema: schema({}) },
+    { name: 'connect_status', description: 'Check whether a person has approved this agent for a journey. No journey access is granted by this tool.', inputSchema: schema({}) }
+];
+function field(args, name) {
+    if (typeof args[name] !== 'string' || !args[name])
+        throw new Error(name + ' must be text.');
+    return args[name];
+}
+export function createWayfindingServer(getClient) {
+    const server = new Server({ name: 'wayfinding', version: '0.1.0' }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const args = request.params.arguments ?? {};
+        try {
+            let result;
+            if (request.params.name === 'connect_status') {
+                try {
+                    const client = await getClient();
+                    result = await client.status();
+                }
+                catch (error) {
+                    result = { connected: false, message: error instanceof Error ? error.message : String(error) };
+                }
+            }
+            else {
+                const client = await getClient();
+                switch (request.params.name) {
+                    case 'add': {
+                        if (args.tags !== undefined && (!Array.isArray(args.tags) || !args.tags.every(tag => typeof tag === 'string')))
+                            throw new Error('Journey tags must be text.');
+                        result = await client.add({ type: field(args, 'type'), title: field(args, 'title'), body: field(args, 'body'), tags: args.tags === undefined ? [] : [...args.tags] });
+                        break;
+                    }
+                    case 'import':
+                        result = await importMarkdown(client, field(args, 'path'));
+                        break;
+                    case 'list':
+                        result = await client.list(typeof args.type === 'string' ? args.type : undefined);
+                        break;
+                    case 'search':
+                        result = await client.search(field(args, 'text'));
+                        break;
+                    case 'show':
+                        result = await client.show(field(args, 'id'));
+                        break;
+                    case 'comment':
+                        result = await client.comment(field(args, 'id'), field(args, 'text'));
+                        break;
+                    case 'comments':
+                        result = await client.comments(field(args, 'id'));
+                        break;
+                    case 'status':
+                        result = await client.status();
+                        break;
+                    default: throw new Error('Unknown journey tool: ' + request.params.name);
+                }
+            }
+            return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+        }
+        catch (error) {
+            return { isError: true, content: [{ type: 'text', text: error instanceof Error ? error.message : String(error) }] };
+        }
+    });
+    return server;
+}
+export async function runMcp(getClient) {
+    await createWayfindingServer(getClient).connect(new StdioServerTransport());
+}

package/dist/signing.d.ts

@@ -0,0 +1,8 @@
+import type { SigningIdentity } from '@ai-wayfinding/core';
+export interface AgentHeaders {
+    'X-Agent-Timestamp': string;
+    'X-Agent-Nonce': string;
+    'X-Agent-Signature': string;
+}
+/** Sign the exact bytes sent to the server, including the path and query string. */
+export declare function signedHeaders(privateKey: SigningIdentity['privateKey'], method: string, path: string, body: string, timestamp?: string, nonce?: `${string}-${string}-${string}-${string}-${string}`): Promise<AgentHeaders>;

package/dist/signing.js

@@ -0,0 +1,8 @@
+import { importSigningKey } from '@ai-wayfinding/core';
+/** Sign the exact bytes sent to the server, including the path and query string. */
+export async function signedHeaders(privateKey, method, path, body, timestamp = String(Date.now()), nonce = crypto.randomUUID()) {
+    const hash = Buffer.from(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(body))).toString('base64url');
+    const message = [method.toUpperCase(), path, hash, timestamp, nonce].join('\n');
+    const signature = await crypto.subtle.sign('Ed25519', await importSigningKey(privateKey), new TextEncoder().encode(message));
+    return { 'X-Agent-Timestamp': timestamp, 'X-Agent-Nonce': nonce, 'X-Agent-Signature': Buffer.from(signature).toString('base64url') };
+}

package/dist/storage.d.ts

@@ -0,0 +1,23 @@
+export interface RememberedAgent {
+    server: string;
+    journeyId: string;
+    sessionId: string;
+    principal: string;
+    identity: string;
+    recipient: string;
+    signingPrivateKey: string;
+    signingKey: string;
+    scope: 'read' | 'readwrite';
+    expiresAt: number;
+}
+export type CommandRunner = (command: string, args: string[], input?: string) => Promise<string>;
+export interface StoreOptions {
+    folder?: string;
+    passphrase?: string;
+    platform?: NodeJS.Platform;
+    run?: CommandRunner;
+}
+export declare const runCommand: CommandRunner;
+export declare function saveRemembered(value: RememberedAgent, options?: StoreOptions): Promise<void>;
+export declare function loadRemembered(options?: StoreOptions): Promise<RememberedAgent | null>;
+export declare function forgetRemembered(options?: StoreOptions): Promise<void>;

package/dist/storage.js

@@ -0,0 +1,129 @@
+import * as age from 'age-encryption';
+import { spawn } from 'node:child_process';
+import { chmod, mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+const service = 'ai-wayfinding-journey-agent';
+const account = 'remembered-session';
+const location = (folder) => join(folder, 'agent.age');
+export const runCommand = (command, args, input) => new Promise((resolve, reject) => {
+    const child = spawn(command, args, { stdio: ['pipe', 'pipe', 'pipe'] });
+    let output = '', error = '';
+    child.stdout.setEncoding('utf8').on('data', (chunk) => { output += chunk; if (output.length > 1_000_000)
+        child.kill(); });
+    child.stderr.setEncoding('utf8').on('data', (chunk) => { error += chunk; if (error.length > 1_000_000)
+        child.kill(); });
+    child.on('error', reject);
+    child.on('close', code => code === 0 ? resolve(output.trim()) : reject(new Error(command + ' could not access the OS keychain. ' + (error.includes('not found') ? 'Install or unlock it.' : 'Check that it is available and unlocked.'))));
+    child.stdin.end(input);
+});
+function validate(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('Invalid saved journey keys. Disconnect and connect again.');
+    const row = value;
+    for (const key of ['server', 'journeyId', 'sessionId', 'principal', 'identity', 'recipient', 'signingPrivateKey', 'signingKey'])
+        if (typeof row[key] !== 'string' || !row[key])
+            throw new Error('Invalid saved journey keys. Disconnect and connect again.');
+    if (row.scope !== 'read' && row.scope !== 'readwrite' || typeof row.expiresAt !== 'number' || !Number.isFinite(row.expiresAt))
+        throw new Error('Invalid saved journey keys. Disconnect and connect again.');
+    if (row.expiresAt <= Date.now())
+        throw new Error('Your journey agent access has expired. Disconnect and connect again.');
+    return { server: row.server, journeyId: row.journeyId, sessionId: row.sessionId, principal: row.principal, identity: row.identity, recipient: row.recipient, signingPrivateKey: row.signingPrivateKey, signingKey: row.signingKey, scope: row.scope, expiresAt: row.expiresAt };
+}
+function supported(options) {
+    const platform = options.platform ?? process.platform;
+    if (platform !== 'darwin' && platform !== 'linux')
+        throw new Error('Remembered journey keys are not supported on this OS. Use --key-folder with a passphrase instead.');
+    return { platform, run: options.run ?? runCommand };
+}
+async function privateFolder(folder) {
+    await mkdir(folder, { recursive: true, mode: 0o700 });
+    const info = await stat(folder);
+    if (!info.isDirectory())
+        throw new Error('Key folder must be a directory');
+    await chmod(folder, 0o700);
+}
+function requirePassphrase(options) {
+    if (!options.passphrase)
+        throw new Error('A passphrase is required for the journey key folder. Set WAYFINDING_PASSPHRASE or use the prompt.');
+    return options.passphrase;
+}
+export async function saveRemembered(value, options = {}) {
+    if (value.expiresAt <= Date.now())
+        throw new Error('Your journey agent access has expired.');
+    if (value.expiresAt > Date.now() + 90 * 86_400_000 + 60_000)
+        throw new Error('Remembered journey access cannot last more than 90 days.');
+    const json = JSON.stringify(validate(value));
+    if (options.folder) {
+        await privateFolder(options.folder);
+        const cipher = new age.Encrypter();
+        cipher.setPassphrase(requirePassphrase(options));
+        const bytes = await cipher.encrypt(new TextEncoder().encode(json));
+        const temp = join(options.folder, '.agent-' + crypto.randomUUID());
+        try {
+            await writeFile(temp, bytes, { mode: 0o600, flag: 'wx' });
+            await rename(temp, location(options.folder));
+            await chmod(location(options.folder), 0o600);
+        }
+        finally {
+            await rm(temp, { force: true });
+        }
+        return;
+    }
+    const { platform, run } = supported(options);
+    if (platform === 'linux') {
+        await run('secret-tool', ['store', '--label=Wayfinding journey agent', 'service', service, 'account', account], json);
+        return;
+    }
+    // security add-generic-password accepts passwords only in argv. Its interactive mode reads
+    // a base64url-encoded command from stdin instead, keeping the key out of the process list.
+    const encoded = Buffer.from(json).toString('base64url');
+    // security -i runs until EOF; "quit" is not a command and exits 1 even after a successful write.
+    await run('security', ['-i'], 'add-generic-password -U -s "' + service + '" -a "' + account + '" -w "' + encoded + '"\n');
+}
+export async function loadRemembered(options = {}) {
+    let raw;
+    if (options.folder) {
+        let bytes;
+        try {
+            bytes = await readFile(location(options.folder));
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return null;
+            throw error;
+        }
+        const decipher = new age.Decrypter();
+        decipher.addPassphrase(requirePassphrase(options));
+        raw = new TextDecoder().decode(await decipher.decrypt(bytes));
+    }
+    else {
+        const { platform, run } = supported(options);
+        try {
+            raw = platform === 'darwin' ? Buffer.from(await run('security', ['find-generic-password', '-s', service, '-a', account, '-w']), 'base64url').toString() : await run('secret-tool', ['lookup', 'service', service, 'account', account]);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (!raw)
+        return null;
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        throw new Error('Invalid saved journey keys. Disconnect and connect again.');
+    }
+    return validate(value);
+}
+export async function forgetRemembered(options = {}) {
+    if (options.folder) {
+        await rm(location(options.folder), { force: true });
+        return;
+    }
+    const { platform, run } = supported(options);
+    try {
+        await (platform === 'darwin' ? run('security', ['delete-generic-password', '-s', service, '-a', account]) : run('secret-tool', ['clear', 'service', service, 'account', account]));
+    }
+    catch { /* No saved key. */ }
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@ai-wayfinding/client",
+  "version": "0.1.1",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "wayfinding": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:integration": "vitest run test/integration.test.ts",
+    "test:mcp": "vitest run test/integration.test.ts -t MCP"
+  },
+  "dependencies": {
+    "@ai-wayfinding/core": "0.1.1",
+    "@modelcontextprotocol/sdk": "^1.30.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0",
+    "wrangler": "^4.138.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AI-Wayfinding/journey.git",
+    "directory": "packages/client"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}