clavarium-tether 0.0.0-stage → 0.1.0-next.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Clavarium Tether authors
+
+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/README.md

@@ -1,3 +1,153 @@
-# Temporary Holding Version
+# Clavarium Tether
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An AI agent reaches outside its own machine, kept on a tether: a level per
+target, a person's approval, a journal, and a stop.
+
+A target is one access given to an agent: a computer, a machine reached by
+SSH, browser tabs, an online folder. On each, the agent has a level:
+
+| Level | The agent... |
+|---|---|
+| Watch | reads only |
+| Propose | reads; each action waits for a person |
+| Frame | reads, acts where a rule allows (`git status`, under `~/Projects`); the rest waits |
+| Free | does everything; the journal says it all |
+
+    tether                                 your targets, your level on each
+    tether run web "sudo apt upgrade -y" --why "Installs 14 updates."
+    tether files web read ~/site/index.html
+    tether open web; tether type web "top" --enter; tether read web
+
+A call that waits shows the person the exact command and the agent's one
+line why: **Accept**, **Refuse**, or **Always** (a rule from the command,
+and it is not asked again). Not answered in time, it is refused.
+
+An MCP server gives the same verbs to an AI agent. A person sees the
+requests, the levels and the journal on its screen (`ui/`), drawn by Tether
+in the page of the application that runs it.
+
+A sibling of [Clavarium Parley](https://github.com/clavarium/clavarium-parley),
+[Clavarium Docket](https://github.com/clavarium/clavarium-docket) and
+[Clavarium Binder](https://github.com/clavarium/clavarium-binder), built the
+same way, universal (nothing in it is specific to Clavarium).
+
+## What an agent cannot do
+
+- **Hold a key.** Passwords and keys stay with the keeper (the application,
+  or `tether serve`), from the application's secret store. The agent asks
+  through its own folder; it never connects, and never sees a secret.
+- **Approve.** Only a person does, on the screen or wherever the
+  application asks them.
+- **Hide.** Each call is a line of the journal: who, where, what exactly,
+  the decision and by whom, when, the size of the result and its exit code.
+  Never a secret, never a file's content.
+- **Go on after Stop.** One button cuts every target of an agent: what
+  waits is refused, terminals are closed, every call after is refused until
+  a person resumes.
+
+## Reach a server over SSH
+
+A target of kind `ssh` is a machine that already runs an SSH server. The
+keeper connects to it as an ordinary SSH client — like ansible or a deploy
+job — through the `ssh2` library (pure JS; no system `ssh`, and **nothing is
+installed on the far machine**). The agent gets the same verbs as on any
+other target: `tether run`, `tether read`, `tether files …`, each through its
+level and a person's approval.
+
+The target says `host`, `port`, `user`, optionally a host-key `pin` to check
+the server's identity and a `root` folder that files may not leave. The
+private key is held by the keeper, from the application's secret store, and
+named in the target — never the key itself; it never reaches the agent, the
+journal or any log.
+
+    tether serve --side ./.tether=Assistant \
+      --ssh deploy@example.com --ssh-key ~/.ssh/deploy_ed25519 \
+      --ssh-root /srv/app --ssh-pin SHA256:… --ssh-title "App server"
+
+declares one SSH target without an application. `--ssh-key FILE` reads the key
+from that file (its content is the secret; the path is not stored); the target
+starts at level Propose. A host-key `--ssh-pin` refuses a server whose key does
+not match.
+
+## Reach an online folder
+
+A target of kind `files` is an online folder on a server the person runs or
+owns. The keeper talks to it as an ordinary file-sync client over HTTPS (no
+extra dependency — Node's own `fetch`); **nothing is installed anywhere**, and
+the agent never connects. The agent gets the `files.*` verbs — `tether files …
+list / read / search / write / move / delete` — each through its level and a
+person's approval. Two kinds of server are reached:
+
+**Nextcloud (and any WebDAV).** The target says the WebDAV `url`, a Basic-auth
+`user`, and optionally a `root` folder files may not leave. The password — a
+Nextcloud **app password** is ideal — is held by the keeper, from the
+application's secret store, and only named in the target.
+
+    tether serve --side ./.tether=Assistant \
+      --webdav https://cloud.example.com/remote.php/dav/files/alice \
+      --webdav-user alice --webdav-pass-env NEXTCLOUD_APP_PASSWORD \
+      --webdav-root /Projects --webdav-title "Cloud"
+
+**SharePoint / OneDrive (Microsoft Graph).** The target says the `drive` id and
+optionally a `root`. V1 takes a bearer token the host keeps fresh (named in the
+target, read here from an environment variable); a client-credentials flow with
+a client secret is also supported (see the protocol). Large-file upload sessions
+are left for a later version.
+
+    tether serve --side ./.tether=Assistant \
+      --graph-drive <drive-id> --graph-token-env GRAPH_TOKEN \
+      --graph-root /Shared --graph-title "Team drive"
+
+`--webdav-pass-env` and `--graph-token-env` name an environment variable; the
+secret is never passed on the command line, written to the store or journalled.
+Both targets start at level Propose.
+## Reach a browser
+
+A target of kind `browser` is a set of tabs a person grants to an agent through
+the **Tether extension** (Chrome and Firefox, one codebase; `extension/`). The
+extension connects OUT to the keeper over a WebSocket — nothing is installed as a
+server, and the browser may sit behind any firewall. The agent gets browser
+verbs scoped to the granted tabs only: `tabs`, `open`, `shot`, `html`,
+`console`, `eval`, `click`, `type`, `key`, `scroll`, `drag`.
+
+    tether serve --browser --port 8787 --side ./.tether=Assistant
+
+serves the browser endpoint at `ws://127.0.0.1:8787/browser` (a browser-safe
+port — browsers refuse 4190). The person opens the popup, which shows a short
+code; they type it in the keeper page to pair. A long-lived token is then kept
+in the extension's storage — never logged, never shown to the agent. In the
+popup the person turns tabs on one by one, or allows a whole site.
+
+- **Granted tabs only.** A verb on a tab that was not granted is refused, on both
+  the extension's side and the keeper's. `browser.open` of a new tab grants it.
+- **Propose by default.** Each action waits for the person; sites are allowed one
+  at a time. Always ask before a payment, a post or a send.
+- **A visible indicator.** While the agent acts in a tab, the extension shows a
+  badge on its icon and a red border around the page.
+
+Build the extension with WXT (`cd extension && npm install && npm run build`
+for Chrome, `npm run build:firefox` for Firefox); load the unpacked build from
+`extension/.output/`.
+
+## Without an application
+
+    tether serve --store ~/tether-data --side ./.tether=Assistant --local ~/Projects
+
+keeps the targets and shows their page on `http://127.0.0.1:4190/`.
+`--local FOLDER` gives the agents this machine (a shell, and that folder),
+at level Propose; it is off unless asked for. Put the store where the agents
+cannot write.
+
+See [docs/protocol.md](docs/protocol.md). One dependency, `ssh2` (the SSH
+connector); Node 22 or later; tmux for the local connector's terminals.
+
+**Status:** first version (0.1), not yet published. The `local`, `ssh`,
+`webdav` (Nextcloud/WebDAV) and `graph` (SharePoint/OneDrive) connectors are
+built. A `screen` slot is ready for a host to plug an engine into (see docs).
+The `computer` and `browser` connectors come next.
+**Status:** first version (0.1), not yet published. The `local`, `ssh` and
+`browser` connectors are built (the browser one with its WebExtension in
+`extension/`). A `screen` slot is ready for a host to plug an engine into (see
+docs). The `computer` connector and online folders come next.
+
+License: MIT.

package/bin/cli.mjs

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+/* THE COMMAND: the verbs for any agent or script that can run a command. It
+ * asks through the same folder as the MCP server (server/mcp.mjs), and prints
+ * the keeper's answer. `serve` IS a keeper: the targets, their approvals and
+ * their page, for use without an application.
+ */
+import { realpathSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { ask, findFolder } from '../server/mcp.mjs';
+import { NAME, VERSION, FOLDER, ENV_DIR } from '../server/name.mjs';
+
+export const HELP = `${NAME}: act on the targets you were given (machines, folders, browsers).
+
+  ${NAME}                                  your targets, your level on each, its rules
+  ${NAME} run TARGET "command" [--timeout S]   run a command: its output and exit code
+  ${NAME} open TARGET                      open a terminal
+  ${NAME} read TARGET [--lines N]          read the terminal's screen
+  ${NAME} type TARGET "keys" [--enter]     type in the terminal
+  ${NAME} files TARGET list [PATH]
+  ${NAME} files TARGET read PATH
+  ${NAME} files TARGET search "text" [--in PATH]
+  ${NAME} files TARGET write PATH --text "..." | --from LOCAL_FILE
+  ${NAME} files TARGET move FROM TO
+  ${NAME} files TARGET delete PATH
+  ${NAME} browser TARGET tabs               the tabs a person granted you
+  ${NAME} browser TARGET open URL [--tab N]  open a URL (a granted tab, or a new one)
+  ${NAME} browser TARGET shot [--tab N]      a screenshot of a granted tab
+  ${NAME} browser TARGET html [--tab N] [--selector S] [--readable]
+  ${NAME} browser TARGET console [--tab N] [--lines N]
+  ${NAME} browser TARGET eval "script" [--tab N]
+  ${NAME} browser TARGET click [SELECTOR | --x N --y N] [--tab N]
+  ${NAME} browser TARGET type "text" [--selector S] [--tab N]
+  ${NAME} browser TARGET key KEY [--selector S] [--tab N]
+  ${NAME} browser TARGET scroll [--dx N] [--dy N] [--selector S] [--tab N]
+  ${NAME} browser TARGET drag FROM TO [--tab N]
+  ${NAME} serve [--store DIR] [--port N] [--side FOLDER=NAME] [--local FOLDER[=TITLE]]
+                                       keep targets yourself, with their page (no application)
+
+Add --why "one short line" when you act: a person may read it before deciding.
+Depending on your level a person approves first; the command waits for them.
+Exit: 0 done, 1 refused, 2 no folder, 3 nobody keeps the targets, 4 not answered in time, 64 not understood.
+The folder used is --dir FOLDER, else $${ENV_DIR}, else the nearest ${FOLDER} folder from here up.
+${NAME} ${VERSION}`;
+
+const FILE_VERBS = ['list', 'read', 'search', 'write', 'move', 'delete'];
+const BROWSER_VERBS = ['tabs', 'open', 'shot', 'html', 'console', 'eval', 'click', 'type', 'key', 'scroll', 'drag'];
+
+/* A command line, read: [verb, args] or { refused }. A --from file is read by run(). */
+export function read(argv) {
+    const flags = {}; const words = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--enter') { flags.enter = true; continue; }
+        if (a === '--readable') { flags.readable = true; continue; }
+        if (a.startsWith('--')) { if (argv[i + 1] === undefined) return { refused: `${a} needs a value` }; flags[a.slice(2)] = argv[++i]; continue; }
+        words.push(a);
+    }
+    const [verb = 'targets', target, ...rest] = words;
+    const why = flags.why !== undefined ? { why: flags.why } : {};
+    const need = (ok, usage) => (ok ? null : { refused: `${NAME} ${usage}` });
+    switch (verb) {
+        case 'targets': return ['targets', {}];
+        case 'run': return need(target && rest.length, 'run TARGET "command"') ?? ['terminal.run', { target, command: rest.join(' '), ...(flags.timeout !== undefined ? { timeout: Number(flags.timeout) } : {}), ...why }];
+        case 'open': return need(target, 'open TARGET') ?? ['terminal.open', { target, ...why }];
+        case 'read': return need(target, 'read TARGET') ?? ['terminal.read', { target, ...(flags.lines !== undefined ? { lines: Number(flags.lines) } : {}) }];
+        case 'type': return need(target && rest.length, 'type TARGET "keys"') ?? ['terminal.type', { target, text: rest.join(' '), enter: !!flags.enter, ...why }];
+        case 'files': {
+            const [what, ...p] = rest;
+            if (!target || !FILE_VERBS.includes(what)) return { refused: `${NAME} files TARGET ${FILE_VERBS.join('|')} ...` };
+            switch (what) {
+                case 'list': return ['files.list', { target, path: p[0] ?? '.' }];
+                case 'read': return need(p[0], 'files TARGET read PATH') ?? ['files.read', { target, path: p[0] }];
+                case 'search': return need(p.length, 'files TARGET search "text"') ?? ['files.search', { target, text: p.join(' '), path: flags.in ?? '.' }];
+                case 'write':
+                    if (!p[0] || (flags.text === undefined) === (flags.from === undefined)) return { refused: `${NAME} files TARGET write PATH --text "..." | --from LOCAL_FILE` };
+                    return ['files.write', { target, path: p[0], ...(flags.text !== undefined ? { text: flags.text } : { from: flags.from }), ...why }];
+                case 'move': return need(p.length === 2, 'files TARGET move FROM TO') ?? ['files.move', { target, from: p[0], to: p[1], ...why }];
+                default: return need(p[0], 'files TARGET delete PATH') ?? ['files.delete', { target, path: p[0], ...why }];
+            }
+        }
+        case 'browser': {
+            const [what, ...p] = rest;
+            if (!target || !BROWSER_VERBS.includes(what)) return { refused: `${NAME} browser TARGET ${BROWSER_VERBS.join('|')} ...` };
+            const tab = flags.tab !== undefined ? { tab: Number(flags.tab) } : {};
+            const sel = flags.selector !== undefined ? { selector: flags.selector } : {};
+            switch (what) {
+                case 'tabs': return ['browser.tabs', { target }];
+                case 'open': return need(p[0], 'browser TARGET open URL') ?? ['browser.open', { target, url: p[0], ...tab, ...why }];
+                case 'shot': return ['browser.shot', { target, ...tab }];
+                case 'html': return ['browser.html', { target, ...tab, ...sel, ...(flags.readable ? { readable: true } : {}) }];
+                case 'console': return ['browser.console', { target, ...tab, ...(flags.lines !== undefined ? { lines: Number(flags.lines) } : {}) }];
+                case 'eval': return need(p.length, 'browser TARGET eval "script"') ?? ['browser.eval', { target, script: p.join(' '), ...tab, ...why }];
+                case 'click': return ['browser.click', { target, ...tab, ...(p[0] ? { selector: p[0] } : sel), ...(flags.x !== undefined ? { x: Number(flags.x) } : {}), ...(flags.y !== undefined ? { y: Number(flags.y) } : {}), ...(flags.button ? { button: flags.button } : {}), ...why }];
+                case 'type': return need(p.length, 'browser TARGET type "text"') ?? ['browser.type', { target, text: p.join(' '), ...tab, ...sel, ...why }];
+                case 'key': return need(p[0], 'browser TARGET key KEY') ?? ['browser.key', { target, key: p[0], ...tab, ...sel, ...why }];
+                case 'scroll': return ['browser.scroll', { target, ...tab, ...sel, ...(flags.dx !== undefined ? { dx: Number(flags.dx) } : {}), ...(flags.dy !== undefined ? { dy: Number(flags.dy) } : {}), ...why }];
+                default: return need(p.length === 2, 'browser TARGET drag FROM TO') ?? ['browser.drag', { target, from: p[0], to: p[1], ...tab, ...why }];
+            }
+        }
+        default: return { refused: `Unknown: ${verb}. Run "${NAME} --help".` };
+    }
+}
+
+/* Runs one command line. Resolves with { code, out, err }: nothing is printed here. */
+export async function run(argv, { env = process.env, cwd = process.cwd(), wait, onHeld } = {}) {
+    const args = [...argv];
+    let dir;
+    const at = args.indexOf('--dir');
+    if (at >= 0) { dir = args[at + 1]; if (!dir) return { code: 64, out: '', err: '--dir needs a folder.\n' }; args.splice(at, 2); }
+    if (['--help', '-h', 'help'].includes(args[0])) return { code: 0, out: `${HELP}\n`, err: '' };
+    if (args[0] === '--version') return { code: 0, out: `${VERSION}\n`, err: '' };
+    const what = read(args);
+    if (what.refused) return { code: 64, out: '', err: `${what.refused}\n` };
+    if (what[1].from !== undefined) {
+        try { what[1].text = readFileSync(what[1].from, 'utf8'); } catch (e) { return { code: 64, out: '', err: `cannot read ${what[1].from}: ${e.code ?? e.message}\n` }; }
+        delete what[1].from;
+    }
+    const folder = findFolder({ dir, env, from: cwd });
+    if (!folder) return { code: 2, out: '', err: `No ${FOLDER} folder here or above. Run it from your work folder, or give --dir FOLDER.\n` };
+    const r = await ask(folder, what[0], what[1], { ...(wait ? { wait } : {}), onHeld });
+    if (r.ok) return { code: 0, out: `${r.text}\n`, err: '' };
+    return { code: r.nokeeper ? 3 : r.late ? 4 : 1, out: '', err: `Not done: ${r.text}\n` };
+}
+
+const main = (() => { try { return realpathSync(process.argv[1] ?? '') === realpathSync(fileURLToPath(import.meta.url)); } catch { return false; } })();
+if (main) {
+    const argv = process.argv.slice(2);
+    if (argv[0] === 'serve') {
+        const { serveMain } = await import('../host/serve.mjs');
+        await serveMain(argv.slice(1));
+    } else {
+        const r = await run(argv, { onHeld: (until) => process.stderr.write(`Waiting for a person (until ${new Date(until).toLocaleTimeString()})...\n`) });
+        if (r.out) process.stdout.write(r.out);
+        if (r.err) process.stderr.write(r.err);
+        process.exitCode = r.code;
+    }
+}