@tomato414941/foundation 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tomato414941
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/env-name.mjs

@@ -0,0 +1,9 @@
+// A delivered key is exposed to the child process under a variable name. The
+// name must never override how the process itself starts.
+const RESERVED = new Set(['PATH', 'HOME', 'USER', 'LOGNAME', 'SHELL', 'PWD', 'OLDPWD', 'TMPDIR', 'TMP', 'TEMP', 'LANG', 'TERM', 'HOSTNAME', 'IFS', 'PS1', 'PS4', 'ENV', 'BASH_ENV', 'CDPATH', 'EDITOR', 'VISUAL',
+  'NODE_OPTIONS', 'NODE_PATH', 'NODE_EXTRA_CA_CERTS', 'PYTHONPATH', 'PYTHONSTARTUP', 'PYTHONHOME', 'PERL5OPT', 'PERL5LIB', 'RUBYOPT', 'RUBYLIB', 'JAVA_TOOL_OPTIONS', 'GOFLAGS', 'GOPATH', 'GEM_PATH', 'GEM_HOME']);
+const SYSTEM_PREFIX = /^(FOUNDATION_|LD_|DYLD_|LC_|XDG_|GIT_|SSH_)/;
+
+export function validEnvName(value) {
+  return typeof value === 'string' && /^[A-Z][A-Z0-9_]{0,63}$/.test(value) && !RESERVED.has(value) && !SYSTEM_PREFIX.test(value);
+}

package/guide.mjs

@@ -0,0 +1,159 @@
+// Printed by `foundation guide` (and served to MCP clients): the one page an agent reads before using any of this.
+//
+// What Foundation offers is an HTTP API, and that is what this describes. Not every agent can run a
+// command, so nothing here assumes a shell; where one exists there is a small program that adds the one
+// thing HTTP cannot do, and it is described last.
+//
+// This text is read by the agent, not by the owner, so it is English; everything the owner reads
+// (purposes, steps, the dashboard) stays in the owner's language.
+function connectorLines(connectors) {
+  if (!connectors) return ['     GET /v1/connectors lists what this server can obtain itself.'];
+  const lines = [];
+  for (const connector of connectors.filter(item => item.available)) {
+    lines.push('     ' + connector.id + '  ' + (connector.service?.name || '') + ' / ' + connector.access.name + (connector.variables.length ? '  outputs: ' + connector.variables.join(', ') : ''));
+    if (connector.ai) lines.push('       ' + connector.ai);
+  }
+  const unavailable = connectors.filter(item => !item.available);
+  if (unavailable.length) lines.push('     Currently unavailable: ' + unavailable.map(item => item.id).join(', '));
+  return lines;
+}
+
+export function guide(connectors) {
+  return ['Foundation keeps user-controlled values and objects, and runs explicitly requested built-in functions.',
+    'A saved name identifies bytes. It does not select a service, a connection, a function, or an environment variable.',
+    'Storage never invokes a provider: a value saved from a function is an independent snapshot, not a live connection.', '',
+    'Everything below is HTTP with your approved key: Authorization: Bearer fdn_...',
+    'Nothing here needs a shell. With one, use foundation api to attach the key and foundation exec to deliver values',
+    'to a command. api prints responses: use function save options when output should not enter your context.',
+    'Never ask the owner to paste passwords, keys or tokens into chat. Use a storage request or OAuth URL instead.', '',
+    'YOUR KEY',
+    '   Your key is a secret of your own making: 43 URL-safe base64 characters after `fdn_`. Generate one, keep it private,',
+    '   and never print it. If you can write a private file, keep it there; otherwise keep it wherever your secrets go.',
+    '   POST /v1/keys  {"name": "<what to call you>"}   with your key as the bearer.',
+    '     Returns verification_uri and confirmation_code. Give the owner both; they open the URL and type the code.',
+    '     Until they do, every other call answers 401 not_approved. Retry GET /v1/keys/current every few seconds. Do not hammer it.',
+    '   GET /v1/keys/current    your request and what happened at its page; once approved, also who you are (key).',
+    '     Approval also has kind=approve, status=done and result.key_id. A current key, not request completion, authorizes use.',
+    '     Revoking a key stops Foundation access; credentials already obtained must be revoked at their provider.',
+    '   PATCH /v1/keys/current {"name"}    DELETE /v1/keys/current    cancels the request, or revokes your approved key.', '',
+    'WHAT IS KEPT',
+    '   PUT /v1/secrets?name=<name>&secret=true    body: raw bytes, up to 1MB. The same exact name replaces that value.',
+    '     secret=true blocks direct GET by an access key. The owner can read it; authorized delivery can still return it.',
+    '     This is not a boundary against an agent with the approved key. Do not print delivered values into its context.',
+    '   GET /v1/secrets    names, sizes, read permissions and timestamps, not contents.',
+    '   GET /v1/secrets?prefix=<literal prefix>   optional case-sensitive text filtering, not a directory.',
+    '   GET /v1/secrets?name=<name>               bytes, as written; 403 write_only for a secret.',
+    '   DELETE /v1/secrets?name=<name>',
+    '   URL-encode the name. A name is any text, which is why it travels as a query and not as a path. Names are 1-200 characters without control characters; case, spaces, slashes and punctuation',
+    '   remain literal. No normalization, hierarchy, service ownership or automatic renewal is inferred.',
+    '   The owner can read, rename or delete any saved value. Stored copies survive OAuth disconnection.', '',
+    'HANDING IT TO A COMMAND',
+    '   POST /v1/deliveries  {"names": [{"name": "build token", "as": "GH_TOKEN"}]}',
+    '     Each item is {name, as, filename?}. as is required: it names the environment variable, independently of name.',
+    '     filename makes the bytes a temporary file instead; as holds its local path. Use this for binary or multiline data.',
+    '     Up to 16 inputs. Variables and filenames must be distinct; reserved system variables are refused.',
+    '     Returns delivery: {environment, files}. No provider check or refresh occurs; expiry of stored bytes is unknown.',
+    '     Calling this into an agent context exposes values. Use exec when the intent is to run a local command.', '',
+    'FILLING THE STORE',
+    '',
+    '1. Put it there yourself. Anything you obtained or wrote: PUT /v1/secrets?name=<name>, above.',
+    '',
+    '2. ASKING THE OWNER, for what only they can fetch -- an API token, a key, a certificate they must go and create.',
+    '   POST /v1/requests  {"kind":"store", "input":{"fields":[{...}]}, "purpose":"...", "steps":["..."], "valid_minutes":30}',
+    '     fields[].name      suggested name; result.names returns the names the owner chose, result.replaced those replaced',
+    '     fields[].label     what they are being asked for, in their language. It titles the screen and names the field.',
+
+    '     fields[].site      the page where they make it, offered as a link',
+    '     fields[].secret    false lets you read it back afterwards; the default is that you cannot',
+    '     fields[].multiline true for something like a PEM',
+    '     fields[].replace   true to put the value in place of the one already kept under that exact name (rotation).',
+    '                     Refused at creation: name_taken when the name exists and replace is not declared, name_missing',
+    '                     when it is declared and nothing is there. The owner may still give it another name, in which',
+    '                     case nothing is replaced; result.replaced lists the names that were.',
+    '     purpose         one concrete sentence the owner can judge, in their language',
+    '     steps           what they do, one string per step (up to 20, 500 characters each, no line breaks). Foundation',
+    '                     holds no instructions for anyone else\'s',
+    '                     site: look up what to click now, and write it yourself.',
+    '   Give the owner the verification_uri (there is no code). When they finish, it is simply kept.',
+    '   Ask for what the owner already holds. Never take it through the conversation and put it there yourself.',
+    '',
+    '3. CONNECTING A SERVICE for later explicit credential processing. OAuth renewal state stays with the connection,',
+    '   separate from ordinary saved values. Connecting does not create named values.',
+    ...connectorLines(connectors),
+    '   POST /v1/requests  {"kind":"connect", "input":{"connector":"<id>"}, "purpose":"...", "valid_minutes":30}   Give the owner the verification_uri.',
+    '   Poll GET /v1/requests/<id> every few seconds until done; result.connection_id identifies the connection.',
+    '   GET /v1/connections   connection IDs, labels, provider details and available output identifiers.', '',
+    'FUNCTIONS',
+    '   GET /v1/functions   catalog of built-in operations and their invocation endpoints; no arbitrary-code runtime.',
+    '   POST /v1/functions/connection.credentials',
+    '     {"connection_id": "<id>", "save": {"<output identifier>": "<chosen saved name>"}}',
+    '     Checks or renews that connection and saves only the outputs you explicitly name. Returns saved metadata and',
+    '     actual expiry, without credential values. Existing values at those exact names are replaced atomically.',
+    '     Omit save to receive delivery directly. Prefer save when invoking from an AI tool; then use exec or http.request.',
+    '     Saving creates independent copies: subsequent reads never refresh them; invoke this function again when needed.',
+    '     Disconnecting stops future processing, not copies already saved or handed out. Revoke at the provider if needed.', '',
+    'WHEN IT DOES NOT WORK',
+    '   GET /v1/requests/<id>   one of your requests, and what happened at its page (events).',
+    '   GET /v1/requests?status=pending   your requests. Several may be open at once (up to 10).',
+    '   events is the raw record, in order: page_opened / page_viewed / connect_started / connect_failed (with a code and',
+    '   Foundation\'s own message) / connected / stored / denied / cancelled. What was typed is never recorded.',
+    '   DELETE /v1/requests/<id>   cancels it. status is pending / done / denied / cancelled.',
+    '   Completion and result are fixed until the request expires, even if the resulting resource changes or is removed.',
+    '   Current connection state is at GET /v1/connections. Revoked keys receive 401; their pending requests are cancelled.',
+    '   Request feedback expires with the request. A done result is a connection_id or the names saved at completion.',
+    '   Why a registration failed: invalid_values (wrong shape) / invalid_credential (the connector would not take it) /',
+    '   reconnect_required (the service rejected it) / already_connected. A key approval shows its own events at',
+    '   GET /v1/keys/current: confirmation_required (a wrong code) / confirmation_locked (5 tries).', '',
+    'A PLACE FOR FILES (object storage the owner did not have to sign up for)',
+    '   PUT /v1/objects/<key>      body is the bytes; the Content-Type you send is what a reader gets back. Up to 25MB.',
+    '   GET /v1/objects/<key>      the bytes. DELETE removes it. GET /v1/objects?prefix=<p>&cursor=<c> lists what is there.',
+    '   POST /v1/objects/<key>/link {"minutes":n}   a time-limited URL anyone can read, for a thing that only takes a URL.',
+    '   Keys look like a path (a/b/c.txt) but name one whole object: no renaming, no directories, no partial reads or writes.',
+    '   This is not a filesystem. If the owner needs one, they need a machine to mount it on.',
+    '   Where the bytes live is the owner\'s business: a space lent to them now, a bucket of their own later. Nothing you call changes.', '',
+    'HTTPS REQUEST FUNCTION',
+    '   POST /v1/functions/http.request  {"url": "https://api.example.com/v1/items", "method": "POST",',
+    '     "headers": {"authorization": "Bearer {{foundation:token}}"}, "bindings": {"token": "build token"}, "body": "..."}',
+    '     Each placeholder identifies an input slot. bindings maps slots to exact saved names (including braces or spaces).',
+    '     Without bindings, a slot is itself a saved name. Inputs only in headers/body, never in the URL. Up to 8 inputs.',
+    '     body_encoding "base64" sends bytes without substitution. Input values are read as stored, never refreshed.',
+    '     Returns {response: {status, headers, body, body_encoding}}. Common echoes of input secrets are redacted;',
+    '     do not treat redaction as protection against arbitrary transformations by an untrusted destination.',
+    '     Optional save: "<name>" stores the response body and returns only response status/headers and saved metadata.',
+    '     Redirects are returned, not followed.',
+    '     HTTPS on 443, public hostnames only, never this server or private networks. 1MB each way, 20 seconds, 30/minute.',
+    '     No workflow, schedule or implicit execution: the caller chooses each invocation and each saved output.', '',
+    'THE SHELL (only if you can run commands)',
+    '   Install: npm install -g @tomato414941/foundation   (Node.js 24 or later)',
+    '   foundation connect [<url>] [--name <name>]',
+    '     Makes the key as a private file and asks for approval. The key is never printed, so it never reaches you.',
+    '     Given a URL, it also remembers that server for every later command; run it again when the server moves.',
+    '   foundation api <GET|POST|PUT|DELETE|PATCH> </path> [--json <body>] [--from <file>] [--type <media-type>]',
+    '     Any request above, with the key attached and the answer printed as it came. Prefer this over curl: reading the key',
+    '     file to build a header yourself would put the key in your context, which is the thing this avoids.',
+    '   foundation exec <ENV>=<name> [...] -- <command> [args...]',
+    `   foundation exec --inputs '[{"name":"signing key","as":"KEY_FILE","filename":"AuthKey.p8"}]' -- <command>`,
+    '     ENV=name treats everything after the first = literally. Use --inputs JSON for files or structured inputs.',
+    '     Only the child process gets delivered values; files exist only while it runs. FOUNDATION_NAMES is a JSON array',
+    '     of the exact saved names used. Prevent the child command from logging or echoing secrets.',
+    '     Use this instead of POST /v1/deliveries whenever the point is to run something.',
+    `   foundation exec --output '{"name":"login config","as":"AUTH_FILE","filename":"auth.json"}' -- <command>`,
+    '     Creates one empty private file and sets as to its path. Tell the command to write its authentication result there.',
+    '     After exit 0, saves the file bytes under the exact name with secret=true, then removes the temporary file.',
+    '     An existing value at that name is replaced. Output must be a private regular file containing 1 byte to 1MB.',
+    '     May be combined with inputs, using a different environment variable. A failed command never saves its output.',
+    '     If upload cannot be confirmed, exits with an error and reports the retained private file for recovery; inputs are',
+    '     still removed. Retry with api PUT --from, then remove the recovery file. Other temporary files are removed.',
+    '     Use native service login URLs; never collect passwords in chat. Stored credentials keep their original expiry.',
+    '   Environment: FOUNDATION_URL (optional; overrides the remembered server), FOUNDATION_AGENT (optional; your name, e.g. claude / codex), FOUNDATION_RUNTIME_KEY_FILE (optional).',
+    '   One key per machine and OS user by default. FOUNDATION_AGENT gives each agent its own key, but any agent running as the',
+    '   same OS user can read that file, so it is bookkeeping, not protection. To separate them for real, use separate OS users.', '',
+    'RULES',
+    '- Never print, log or write out what is delivered. Hand it to a command, and nowhere else.',
+    '- Send saved values only to an authorized destination. http.request and exec use the destinations you choose.',
+    '- Ask for the least you need. Do not request something the work does not use.',
+    '- Be honest in name, purpose and label. The owner decides based on them.',
+    '- If a request is denied or expires, ask the owner why rather than guessing.',
+    '- Use what you receive only for the work it was asked for.',
+  ].join('\n');
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@tomato414941/foundation",
+  "version": "0.1.0",
+  "description": "Foundation CLI: make a key, and hand what is kept to a command without it passing through the agent.",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "bin": {
+    "foundation": "runtime.mjs"
+  },
+  "files": [
+    "runtime.mjs",
+    "guide.mjs",
+    "env-name.mjs"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tomato414941/foundation.git",
+    "directory": "cli"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "license": "MIT"
+}

package/runtime.mjs

@@ -0,0 +1,295 @@
+#!/usr/bin/env node
+import { open, mkdir, stat, lstat, mkdtemp, writeFile, chmod, readFile, rename } from 'node:fs/promises';
+import { parseArgs } from 'node:util';
+import { rmSync, readdirSync, constants } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { createHash, randomBytes } from 'node:crypto';
+import { homedir, hostname, tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { createRequire } from 'node:module';
+import { validEnvName } from './env-name.mjs';
+import { guide } from './guide.mjs';
+
+// This program does only what the agent running it cannot do for itself.
+//
+// Everything Foundation offers is plain HTTP, and an agent with the key can call it directly; a command
+// wrapper around those calls would only narrow what the agent is allowed to think of. Two things are left:
+//   connect  say which server, and make the key. It has to exist as a private file before anything can be asked, and whoever
+//            makes it must not print it.
+//   exec     hand what is kept to a command, or keep a file it creates, without the bytes passing through
+//            the agent. If the agent fetched the values itself they would be in its context.
+// There is also `api`, which is for people and for scripts rather than for agents: it attaches the key to a
+// request and prints what comes back. One escape hatch, so that the API can grow without this program growing
+// a verb for every endpoint, and without deciding for an agent how it ought to use any of them.
+async function runtimeKey(path, create, privateDirectory) {
+  if (create) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    if (privateDirectory) {
+      const directory = await stat(dirname(path));
+      if ((directory.mode & 0o077) || (process.getuid && directory.uid !== process.getuid())) throw new Error('Foundation key directory must be owned by the current user and private (mode 700).');
+    }
+    let created;
+    try {
+      created = await open(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+      await created.writeFile('fdn_' + randomBytes(32).toString('base64url') + '\n');
+      await created.sync();
+    } catch (error) { if (error.code !== 'EEXIST') throw error; }
+    finally { await created?.close(); }
+  }
+  let handle;
+  try {
+    handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    const info = await handle.stat();
+    if (!info.isFile() || info.size > 512 || (info.mode & 0o077) || (process.getuid && info.uid !== process.getuid())) throw new Error('Runtime key file must be owned by the current user and private (mode 600).');
+    const token = (await handle.readFile('utf8')).trim();
+    if (!/^fdn_[A-Za-z0-9_-]{43}$/.test(token)) throw new Error('Invalid runtime key file.');
+    return token;
+  } catch (error) {
+    if (error.code === 'ENOENT') throw new Error('No key yet. Run: foundation connect');
+    if (error.code === 'ELOOP') throw new Error('Runtime key file must not be a symbolic link.');
+    throw error;
+  } finally { await handle?.close(); }
+}
+
+const VERSION = createRequire(import.meta.url)('./package.json').version;
+// Which server this machine talks to is a setting, not part of the program: `connect <url>` writes it here,
+// and FOUNDATION_URL, when set, wins for that one run.
+const configPath = () => join(process.env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'foundation', 'config.json');
+async function savedUrl() {
+  try { return JSON.parse(await readFile(configPath(), 'utf8')).url || ''; }
+  catch (error) { if (error.code === 'ENOENT') return ''; throw new Error('Cannot read ' + configPath() + ': ' + error.message); }
+}
+async function saveUrl(origin) {
+  const path = configPath();
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  await writeFile(path + '.tmp', JSON.stringify({ url: origin }, null, 2) + '\n', { mode: 0o600 });
+  await rename(path + '.tmp', path);
+}
+function serverUrl(value) {
+  let url;
+  try { url = new URL(value); } catch { throw new Error('No Foundation server yet. Run: foundation connect <url>'); }
+  if ((url.protocol !== 'https:' && !(url.protocol === 'http:' && ['127.0.0.1', 'localhost'].includes(url.hostname))) || url.username || url.password || url.pathname !== '/' || url.search || url.hash) throw new Error('The Foundation URL must be an HTTPS origin (HTTP is allowed only on localhost).');
+  return url;
+}
+
+const validFilename = value => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(value);
+async function outputBytes(path) {
+  let handle;
+  try {
+    const directory = await lstat(dirname(path));
+    if (!directory.isDirectory() || (directory.mode & 0o077) || (process.getuid && directory.uid !== process.getuid())) throw new Error('Output directory must stay private (mode 700) and owned by the current user.');
+    handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    const info = await handle.stat(), limit = 1024 * 1024;
+    if (!info.isFile() || info.nlink !== 1 || (info.mode & 0o077) || (process.getuid && info.uid !== process.getuid())) throw new Error('Output must be a private regular file owned by the current user (mode 600).');
+    if (info.size > limit) throw new Error('Output must contain 1 byte to 1MB.');
+    // Bound the read too: the file may grow after stat, or still have a writer.
+    const bytes = Buffer.alloc(limit + 1);
+    let size = 0;
+    while (size < bytes.length) {
+      const { bytesRead } = await handle.read(bytes, size, bytes.length - size, null);
+      if (!bytesRead) break;
+      size += bytesRead;
+    }
+    if (!size || size > limit) throw new Error('Output must contain 1 byte to 1MB.');
+    return bytes.subarray(0, size);
+  } catch (error) {
+    if (error.code === 'ELOOP') throw new Error('Output must not be a symbolic link.');
+    if (error.code === 'ENOENT') throw new Error('The command did not create its output file.');
+    throw error;
+  } finally { await handle?.close(); }
+}
+
+// --help is the usual thing: the commands and their options. The guide (what Foundation is and how to ask it
+// for things) is its own command, since it is the server's document, not this program's.
+const HELP = `Usage: foundation <command> [options]
+
+Commands:
+  connect [<url>] [--name <name>]      Make this machine's key and ask the owner to approve it.
+                                       With <url>, remember that Foundation server for later commands.
+  api <METHOD> </path> [--json <body>] [--from <file>] [--type <media-type>]
+                                       Send one request to the Foundation API with the key attached.
+  exec <ENV>=<name> [...] -- <command> [args...]
+                                       Run a command with saved values in its environment.
+  exec --inputs '<json>' -- <command>  The same, with files or structured inputs.
+  exec --output '<json>' -- <command>  Also save a file the command writes.
+  guide                                The API guide: what Foundation keeps, and how to ask it for things.
+  version                              Print the version.
+
+Environment:
+  FOUNDATION_URL               The server for this run (otherwise the one saved by connect).
+  FOUNDATION_AGENT             Your name, such as claude or codex; gives each agent its own key file.
+  FOUNDATION_RUNTIME_KEY_FILE  Where the key file is.
+`;
+
+async function main() {
+  const [action, ...args] = process.argv.slice(2);
+  const agentName = (process.env.FOUNDATION_AGENT || '').trim();
+  if (agentName && !/^[A-Za-z0-9][A-Za-z0-9 ._-]{0,39}$/.test(agentName)) throw new Error('FOUNDATION_AGENT must be 1-40 characters of letters, digits, space, dot, underscore or hyphen.');
+  if (action === '--version' || action === '-v' || action === 'version') { console.log(VERSION); return; }
+  const configured = process.env.FOUNDATION_URL || await savedUrl();
+  if (action === '--help' || action === '-h' || action === 'help' || !action) { console.log(HELP); return; }
+  if (action === 'guide') {
+    let connectors;
+    if (configured) {
+      try {
+        const response = await fetch(new URL('/v1/connectors', configured), { redirect: 'error', signal: AbortSignal.timeout(5_000) });
+        const catalog = await response.json();
+        if (response.ok && Array.isArray(catalog.connectors)) connectors = catalog.connectors;
+      } catch {}
+    }
+    console.log(guide(connectors));
+    return;
+  }
+  const separatorAt = args.indexOf('--'), command = separatorAt >= 0 ? args.slice(separatorAt + 1) : [];
+  // Names remain literal. Inputs deliver bytes; an optional output saves one generated file.
+  let names = [], output;
+  if (action === 'exec' && separatorAt > 0) {
+    const parsed = parseArgs({ args: args.slice(0, separatorAt), options: { inputs: { type: 'string' }, output: { type: 'string' } }, strict: true, allowPositionals: true });
+    if (parsed.values.inputs !== undefined && parsed.positionals.length) throw new Error('--inputs and ENV=name are alternatives.');
+    if (parsed.values.inputs !== undefined) {
+      try { names = JSON.parse(parsed.values.inputs); } catch { throw new Error('--inputs must be a JSON array of {name, as, filename?}.'); }
+    } else names = parsed.positionals.map(value => {
+      const at = value.indexOf('=');
+      if (at < 1) throw new Error('Specify the environment variable explicitly: ENV=name');
+      return { name: value.slice(at + 1), as: value.slice(0, at) };
+    });
+    if (!Array.isArray(names) || names.length > 16 || names.some(item => !item || typeof item.name !== 'string' || !item.name || !validEnvName(item.as))) throw new Error('Each input needs a name and a non-reserved environment variable in as.');
+    if (new Set(names.map(item => item.as)).size !== names.length) throw new Error('Each input needs a different environment variable.');
+    if (parsed.values.output !== undefined) {
+      try { output = JSON.parse(parsed.values.output); } catch { throw new Error('--output must be a JSON object {name, as, filename}.'); }
+      if (!output || Array.isArray(output) || typeof output !== 'object' || Object.keys(output).some(key => !['name', 'as', 'filename'].includes(key))) throw new Error('--output must be a JSON object {name, as, filename}.');
+      if (typeof output.name !== 'string' || !output.name.length || output.name.length > 200 || /[\u0000-\u001f\u007f-\u009f]/u.test(output.name) || !output.name.isWellFormed()) throw new Error('Output name must be 1-200 characters without control characters.');
+      if (!validEnvName(output.as) || !validFilename(output.filename)) throw new Error('Output needs a non-reserved environment variable in as and a filename starting with a letter or digit (up to 64 letters, digits, dots, underscores or hyphens).');
+      if (names.some(item => item.as === output.as)) throw new Error('Output needs a different environment variable from every input.');
+    }
+  }
+  let call, connectTo, name;
+  if (action === 'connect') {
+    const parsed = parseArgs({ args, options: { name: { type: 'string' } }, strict: true, allowPositionals: true });
+    if (parsed.positionals.length > 1) throw new Error('Usage: connect [<url>] [--name <name>]');
+    connectTo = parsed.positionals[0];
+    name = parsed.values.name;
+  } else if (action === 'api') {
+    const parsed = parseArgs({ args, options: { json: { type: 'string' }, from: { type: 'string' }, type: { type: 'string' } }, strict: true, allowPositionals: true });
+    if (parsed.positionals.length !== 2 || !/^(GET|POST|PUT|DELETE|PATCH)$/.test(parsed.positionals[0]) || !parsed.positionals[1].startsWith('/')) {
+      throw new Error('Usage: api <GET|POST|PUT|DELETE|PATCH> </path> [--json <body>] [--from <file>] [--type <media-type>]');
+    }
+    if (parsed.values.json !== undefined && parsed.values.from !== undefined) throw new Error('--json and --from are alternatives.');
+    // A request that carries nothing still says so in JSON, which is what the server asks of anything but a GET.
+    const method = parsed.positionals[0];
+    const content = parsed.values.from !== undefined ? await readFile(parsed.values.from) : parsed.values.json !== undefined ? Buffer.from(parsed.values.json) : method === 'GET' ? undefined : Buffer.from('{}');
+    call = { method, target: parsed.positionals[1], body: content,
+      type: parsed.values.type || (parsed.values.from !== undefined ? 'application/octet-stream' : 'application/json') };
+  } else if (!(action === 'exec' && (names.length || output) && command.length)) {
+    throw new Error('Usage: connect [<url>] [--name <name>] | exec [<ENV>=<name> ... | --inputs <json>] [--output <json>] -- <command> [args...] | api <method> </path> [--json <body>] [--from <file>]');
+  }
+  const url = serverUrl(connectTo ?? configured);
+  const keyPath = process.env.FOUNDATION_RUNTIME_KEY_FILE || join(homedir(), '.local', 'state', 'foundation', createHash('sha256').update(url.origin).digest('hex').slice(0, 24) + (agentName ? '-' + agentName.toLowerCase().replace(/[^a-z0-9]+/g, '-') : '') + '.key');
+  const token = await runtimeKey(keyPath, action === 'connect', !process.env.FOUNDATION_RUNTIME_KEY_FILE);
+  async function send(target, payload, { accept, method = 'POST', type = 'application/json' } = {}) {
+    const response = await fetch(url.origin + target, { method, headers: { authorization: 'Bearer ' + token, ...(payload === undefined ? {} : { 'content-type': type }) },
+      body: payload === undefined ? undefined : type === 'application/json' ? JSON.stringify(payload) : payload, redirect: 'error', signal: AbortSignal.timeout(30_000) });
+    const data = await response.json();
+    if (!response.ok && !accept?.(data)) throw new Error('Foundation request failed (' + response.status + ', ' + (data.error?.code || 'unknown') + '). ' + (data.error?.message || 'Check the connection and runtime permission.'));
+    return data;
+  }
+  // One request, with the key attached and the answer printed as it came. Nothing here knows the endpoints.
+  if (action === 'api') {
+    const response = await fetch(url.origin + call.target, { method: call.method, headers: { authorization: 'Bearer ' + token, ...(call.body === undefined ? {} : { 'content-type': call.type }) },
+      ...(call.body === undefined ? {} : { body: call.body }), redirect: 'error', signal: AbortSignal.timeout(30_000) });
+    const bytes = Buffer.from(await response.arrayBuffer());
+    process.stdout.write(bytes);
+    if (bytes.length && !bytes.subarray(-1).equals(Buffer.from('\n'))) process.stdout.write('\n');
+    if (!response.ok) process.exitCode = 1;
+    return;
+  }
+  // Asking the owner to approve this key. The key itself is never printed: it stays in the file.
+  // A key the owner already approved has nothing to ask; connecting again only changes which server is remembered.
+  if (action === 'connect') {
+    const answer = await send('/v1/keys', { name: name ?? hostname() + ' の ' + (agentName || 'AI') }, { accept: data => data.error?.code === 'already_approved' });
+    if (connectTo !== undefined) await saveUrl(url.origin);
+    console.log(answer.error ? 'Already approved on ' + url.origin + '.' : JSON.stringify(answer, null, 2));
+    console.log('\nKey file: ' + keyPath + '\nServer: ' + url.origin + (connectTo !== undefined ? ' (saved to ' + configPath() + ')' : '') + '\nEverything else is HTTP: Authorization: Bearer <the contents of that file>');
+    return;
+  }
+  // Even output-only commands need an approved key before they start an external login.
+  let delivery;
+  if (names.length) ({ delivery } = await send('/v1/deliveries', { names }));
+  else {
+    const current = await send('/v1/keys/current', undefined, { method: 'GET' });
+    if (!current.key) throw new Error('Foundation request failed (401, not_approved). This key is waiting for approval at ' + current.request?.verification_uri + '.');
+    delivery = { environment: {}, files: [] };
+  }
+  if (!delivery || typeof delivery.environment !== 'object' || !Array.isArray(delivery.files)) throw new Error('Foundation returned an invalid delivery.');
+  // What each of them sets is the server's to say; this applies it and refuses anything it may not set.
+  const environment = { ...process.env };
+  delete environment.FOUNDATION_RUNTIME_KEY_FILE;
+  const assign = (name, value) => {
+    if (!validEnvName(name)) throw new Error('Foundation named a reserved environment variable (' + name + ').');
+    if (typeof value !== 'string' || /[\x00\r\n]/.test(value) || value.length > 16384) throw new Error('Foundation returned an invalid value for ' + name + '.');
+    environment[name] = value;
+  };
+  for (const [name, value] of Object.entries(delivery.environment)) assign(name, value);
+  const fileNames = new Set(), variables = new Set(Object.keys(delivery.environment));
+  for (const file of delivery.files) {
+    if (typeof file.env !== 'string' || typeof file.content !== 'string' || !validFilename(file.filename) || !validEnvName(file.env) || fileNames.has(file.filename) || variables.has(file.env)) throw new Error('Foundation described an invalid file.');
+    fileNames.add(file.filename); variables.add(file.env);
+  }
+  if (output && variables.has(output.as)) throw new Error('Output needs a different environment variable from every input.');
+  environment.FOUNDATION_NAMES = JSON.stringify(names.map(item => item.name));
+  // Delivered inputs are always cleaned up. A completed output survives only an unconfirmed upload.
+  let secretDir, outputDir, outputPath, child, interrupted = false, retainOutput = false;
+  const cleanup = () => {
+    if (secretDir) rmSync(secretDir, { recursive: true, force: true });
+    if (outputDir) {
+      if (!retainOutput) rmSync(outputDir, { recursive: true, force: true });
+      else for (const entry of readdirSync(outputDir)) {
+        if (entry !== output.filename) rmSync(join(outputDir, entry), { recursive: true, force: true });
+      }
+    }
+  };
+  const recovery = () => 'Foundation could not confirm the output was saved. The private output file is retained for recovery: ' + outputPath + '\nRetry with foundation api PUT "/v1/secrets?name=<URL-encoded-name>&secret=true" --from <file>, then remove that recovery file.';
+  process.once('exit', cleanup);
+  for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.once(signal, () => {
+    interrupted = true;
+    if (child?.pid && child.exitCode === null && child.signalCode === null) {
+      child.kill(signal);
+      setTimeout(() => child.kill('SIGKILL'), 5_000).unref();
+      return;
+    }
+    if (retainOutput) console.error(recovery());
+    cleanup(); process.exit(1);
+  });
+  try {
+    const temporaryDirectory = async () => {
+      const directory = await mkdtemp(join(process.env.XDG_RUNTIME_DIR && (await stat(process.env.XDG_RUNTIME_DIR).catch(() => null))?.isDirectory() ? process.env.XDG_RUNTIME_DIR : tmpdir(), 'foundation-'));
+      await chmod(directory, 0o700);
+      return directory;
+    };
+    if (delivery.files.length) {
+      secretDir = await temporaryDirectory();
+      for (const file of delivery.files) {
+        const target = join(secretDir, file.filename);
+        await writeFile(target, file.encoding === 'base64' ? Buffer.from(file.content, 'base64') : file.content, { mode: 0o600, flag: 'wx' });
+        assign(file.env, target);
+      }
+    }
+    if (output) {
+      outputDir = await temporaryDirectory();
+      outputPath = join(outputDir, output.filename);
+      await writeFile(outputPath, '', { mode: 0o600, flag: 'wx' });
+      assign(output.as, outputPath);
+    }
+    child = spawn(command[0], command.slice(1), { stdio: 'inherit', env: environment, shell: false });
+    process.exitCode = await new Promise((resolve, reject) => { child.once('error', reject); child.once('exit', (value, signal) => resolve(interrupted ? 1 : value ?? (signal ? 1 : 0))); });
+    if (output && process.exitCode === 0) {
+      const bytes = await outputBytes(outputPath);
+      retainOutput = true;
+      try { await send('/v1/secrets?name=' + encodeURIComponent(output.name) + '&secret=true', bytes, { method: 'PUT', type: 'application/octet-stream' }); }
+      catch { throw new Error(recovery()); }
+      retainOutput = false;
+      console.error('Saved output as ' + JSON.stringify(output.name) + '.');
+    }
+  } finally { cleanup(); }
+}
+main().catch((error) => { console.error(error instanceof TypeError ? 'Unable to connect. Check the Foundation URL and network access.' : error.message); process.exitCode = 1; });