@panphora/clay-agent 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Miranda
+
+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,82 @@
-# Temporary Holding Version
+# @panphora/clay-agent
 
-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.
+Let AI agents read and edit your [Hyperclay](https://hyperclay.com) documents, from the command line or as an MCP server for Claude Code, Claude Desktop and Cursor.
+
+> **Early release.** Agent keys are not yet available on hyperclay.com, so this version cannot connect to anything yet. Support for the HTML Clay and Hyperclay Local desktop apps comes in a later version.
+
+## How it works
+
+You make an **agent key** in the Hyperclay dashboard: a named key that can be limited to one team or folder, and to reading, changing content, or full editing. You can revoke it at any time. The agent acts as you, with no more access than you have, and every change it makes is kept in the document's version history as "Recorded by you through <key name>", so any change can be restored.
+
+Every write is based on the version the agent read. If the document changed in the meantime, the write is refused and the agent is told to read it again. Nothing is merged or overwritten silently.
+
+## Sign in
+
+```bash
+npx -y @panphora/clay-agent login
+```
+
+Paste the key when asked. It is saved in `~/.config/clay-agent/credentials.json`, readable only by you. The key is never accepted as a command-line argument (it would end up in your shell history), and it is never printed. `CLAY_AGENT_KEY` works instead of a saved key.
+
+```bash
+npx -y @panphora/clay-agent status
+npx -y @panphora/clay-agent logout
+```
+
+## Use it as an MCP server
+
+Claude Code:
+
+```bash
+claude mcp add clay -- npx -y @panphora/clay-agent mcp
+```
+
+Claude Desktop and Cursor (`claude_desktop_config.json` or `.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "clay": { "command": "npx", "args": ["-y", "@panphora/clay-agent", "mcp"] }
+  }
+}
+```
+
+If Node is installed through nvm, use the absolute path to `npx` (`which npx`) as the command.
+
+Options: `mcp --read-only` offers only the reading tools.
+
+### Tools
+
+| Tool | What it does |
+|---|---|
+| `list_documents` | Documents the key can reach |
+| `read_document` | The whole document when small; otherwise an outline, or the parts you select (`select` by CSS selector, `range` by offset) |
+| `outline_document` | The element tree with selector paths and sizes |
+| `find_in_document` | Where some text appears, with the element around it |
+| `read_data` | The page's structured data, through its `api` rules |
+| `write_data` | Change that data |
+| `edit_document` | Replace exact text in the version read; each match must be unique |
+| `save_document` | Save a whole document |
+| `list_versions`, `read_version`, `restore_version` | Version history |
+
+Large documents (up to 5 MB) are read in pieces: an outline first, then the parts the agent needs, and small changes go through `edit_document`.
+
+## Use it from the command line
+
+```bash
+clay-agent list
+clay-agent read hyperclay:123 --outline
+clay-agent read hyperclay:123 --select 'main > section'
+clay-agent edit hyperclay:123 --find 'Draft' --replace 'Final' --if-match <etag>
+clay-agent versions hyperclay:123
+```
+
+A document is `hyperclay:<id>` or its hyperclay.com URL. Writes need `--if-match` with the etag from a read. Add `--json` to any command for machine-readable output.
+
+Exit codes: `0` done, `1` refused or failed, `2` the document changed since it was read (the current etag is printed), `3` the host is not reachable, `4` not signed in, or the key is malformed, revoked or expired, `5` the host may or may not have saved the write (read the document before trying again).
+
+Needs Node 20.18.1 or later.
+
+## License
+
+MIT

package/bin/clay-agent.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.js';
+
+process.exitCode = await main(process.argv.slice(2), {
+  stdin: process.stdin,
+  stdout: process.stdout,
+  stderr: process.stderr,
+  env: process.env,
+});

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@panphora/clay-agent",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Let AI agents read and edit malleable HTML documents on hyperclay.com, HTML Clay and Hyperclay Local, from the command line or as an MCP server",
+  "type": "module",
+  "bin": {
+    "clay-agent": "bin/clay-agent.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=20.18.1"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "hyperclay",
+    "html-clay",
+    "malleable-html",
+    "ai-agent"
+  ],
+  "author": "David Miranda",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/panphora/clay-agent.git"
+  },
+  "homepage": "https://github.com/panphora/clay-agent",
+  "bugs": {
+    "url": "https://github.com/panphora/clay-agent/issues"
+  },
+  "hyper": {
+    "kind": "cli",
+    "status": "active",
+    "url": "https://github.com/panphora/clay-agent"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.32.2",
+    "cheerio": "1.2.0",
+    "zod": "4.6.7"
+  }
+}

package/src/actions.js

@@ -0,0 +1,288 @@
+import { ClayError } from './errors.js';
+import { applyEdits } from './html/edit.js';
+import { find } from './html/find.js';
+import { outline } from './html/outline.js';
+import { range as sliceRange, select as selectMatches } from './html/select.js';
+import { createSession } from './session.js';
+
+const KEY_PATTERN = /hcak_[0-9a-f]{64}/;
+const TOO_LARGE_HINT =
+  'Use outline_document to see its structure, find_in_document to locate text, or read_document with select or range to read part of it.';
+
+const CUT_HINT =
+  'The answer was cut to stay within maxChars. Read the rest with range, starting at the end offset shown.';
+
+const WHOLE_READ_FIRST_HINT =
+  'Read the whole document with read_document first; save_document replaces all of it.';
+
+function readFirstHint(explicitEtag) {
+  return explicitEtag
+    ? 'Pass --if-match with the etag from a read.'
+    : 'Read the document first (read_document, outline_document, find_in_document or read_data), then write.';
+}
+
+function shapeRead({ ref, host, etag, html, maxChars, input }) {
+  if (input.select !== undefined && input.select !== null) {
+    if (input.range !== undefined && input.range !== null) {
+      throw new ClayError('invalid-read', 'Pass either `select` or `range`, not both.', {
+        hint: 'Use `select` for elements by CSS selector, or `range` for a start and length.',
+      });
+    }
+    const { count, matches } = selectMatches(html, input.select, { maxChars });
+    const answer = { ref, host, etag, size: html.length, count, matches };
+    if (matches.some((match) => match.truncated)) answer.hint = CUT_HINT;
+    return answer;
+  }
+  if (input.range !== undefined && input.range !== null) {
+    const start = input.range.start;
+    const length = input.range.length;
+    const { start: from, end, html: slice, truncated } = sliceRange(html, start, length, { maxChars });
+    const answer = { ref, host, etag, size: html.length, start: from, end, html: slice };
+    if (truncated) {
+      answer.truncated = true;
+      answer.hint = CUT_HINT;
+    }
+    return answer;
+  }
+  if (html.length <= maxChars) {
+    return { ref, host, etag, size: html.length, html };
+  }
+  return {
+    ref,
+    host,
+    etag,
+    size: html.length,
+    tooLarge: true,
+    outline: outline(html, { depth: 3 }).outline,
+    hint: TOO_LARGE_HINT,
+  };
+}
+
+export function createActions({ adapters, resolve, session = createSession(), readOnly = false, explicitEtag = false }) {
+  function refuseReadOnly() {
+    if (readOnly) throw new ClayError('read-only-mode', 'This server was started read-only.');
+  }
+
+  async function targetFor(input) {
+    const target = await resolve(input.document, { host: input.host });
+    const host = target.host;
+    const adapter = adapters[host];
+    if (!adapter) {
+      throw new ClayError('host-unavailable', `No adapter is available for ${host}.`, {
+        hint: 'This build talks to hyperclay.com; other hosts are not connected yet.',
+      });
+    }
+    const { id, ref } = await adapter.locate(target);
+    return { host, adapter, id, ref };
+  }
+
+  async function load(input) {
+    const { host, adapter, id, ref } = await targetFor(input);
+    const stored = session.latest(ref);
+    const ifNoneMatch = stored && stored.html !== undefined ? stored.etag : undefined;
+    const result = await adapter.read(id, { ifNoneMatch });
+    if (result.notModified) {
+      return { ref, host, id, etag: stored.etag, html: stored.html, size: stored.html.length };
+    }
+    session.remember(ref, { etag: result.etag, html: result.html });
+    return {
+      ref,
+      host,
+      id,
+      etag: result.etag,
+      html: result.html,
+      size: result.size ?? result.html.length,
+    };
+  }
+
+  function etagFor(input, ref, { whole = false } = {}) {
+    if (input.etag) return input.etag;
+    if (explicitEtag) {
+      throw new ClayError('read-first', 'This write needs the etag from a read.', {
+        hint: readFirstHint(true),
+      });
+    }
+    const known = whole ? session.wholeEtag(ref) : session.seenEtag(ref);
+    if (!known) {
+      throw new ClayError('read-first', 'This write needs the etag from a read.', {
+        hint: whole ? WHOLE_READ_FIRST_HINT : readFirstHint(false),
+      });
+    }
+    return known;
+  }
+
+  function afterWrite(ref, etag) {
+    session.remember(ref, { etag });
+    session.markSeen(ref, etag);
+  }
+
+  function refuseSecret(html) {
+    if (typeof html === 'string' && KEY_PATTERN.test(html)) {
+      throw new ClayError('secret-in-content', 'The document would contain an agent key. Remove it before saving.');
+    }
+  }
+
+  return {
+    list_documents(input = {}) {
+      const host = input.host ?? 'hyperclay';
+      const adapter = adapters[host];
+      if (!adapter) {
+        throw new ClayError('host-unavailable', `No adapter is available for ${host}.`, {
+          hint: 'This build talks to hyperclay.com; other hosts are not connected yet.',
+        });
+      }
+      return adapter.list({ where: input.where, cursor: input.cursor });
+    },
+
+    async read_document(input = {}) {
+      const maxChars = input.maxChars ?? 40000;
+      const loaded = await load(input);
+      const shaped = shapeRead({
+        ref: loaded.ref,
+        host: loaded.host,
+        etag: loaded.etag,
+        html: loaded.html,
+        maxChars,
+        input,
+      });
+      session.markSeen(loaded.ref, loaded.etag);
+      if (!input.select && !input.range && !shaped.tooLarge) {
+        session.markWhole(loaded.ref, loaded.etag);
+      }
+      return shaped;
+    },
+
+    async outline_document(input = {}) {
+      const loaded = await load(input);
+      const result = outline(loaded.html, { depth: input.depth ?? 4, select: input.select ?? null });
+      session.markSeen(loaded.ref, loaded.etag);
+      const answer = {
+        ref: loaded.ref,
+        host: loaded.host,
+        etag: loaded.etag,
+        size: result.size,
+        hasApiRules: result.hasApiRules,
+        dataKeys: result.dataKeys,
+        depth: result.depth,
+        truncated: result.truncated,
+        outline: result.outline,
+      };
+      if (result.truncated) answer.hint = result.hint;
+      return answer;
+    },
+
+    async find_in_document(input = {}) {
+      const loaded = await load(input);
+      const { count, matches } = await find(loaded.html, {
+        text: input.text,
+        regex: input.regex,
+        limit: input.limit ?? 20,
+      });
+      session.markSeen(loaded.ref, loaded.etag);
+      return { ref: loaded.ref, host: loaded.host, etag: loaded.etag, count, matches };
+    },
+
+    async read_data(input = {}) {
+      const { host, adapter, id, ref } = await targetFor(input);
+      const result = await adapter.readData(id);
+      const stored = session.latest(ref);
+      const keep =
+        stored && stored.etag === result.etag && stored.html !== undefined ? { html: stored.html } : {};
+      session.remember(ref, { etag: result.etag, ...keep });
+      session.markSeen(ref, result.etag);
+      return { ref, host, etag: result.etag, data: result.data };
+    },
+
+    async write_data(input = {}) {
+      refuseReadOnly();
+      const { host, adapter, id, ref } = await targetFor(input);
+      refuseSecret(JSON.stringify(input.data));
+      const etag = etagFor(input, ref);
+      const result = await adapter.writeData(id, { data: input.data, etag });
+      afterWrite(ref, result.etag);
+      return { ref, host, etag: result.etag, changed: result.changed, data: result.data ?? input.data };
+    },
+
+    async edit_document(input = {}) {
+      refuseReadOnly();
+      const { host, adapter, id, ref } = await targetFor(input);
+      const etag = etagFor(input, ref);
+      let base = session.htmlFor(ref, etag);
+      if (base === null) {
+        const loaded = await load(input);
+        if (loaded.etag !== etag) {
+          throw new ClayError('conflict', 'The document changed after you read it.', {
+            etag: loaded.etag,
+            hint: 'Read it again and redo the edit.',
+          });
+        }
+        base = loaded.html;
+      }
+      const { html } = applyEdits(base, input.edits);
+      refuseSecret(html);
+      const result = await adapter.save(id, { html, etag });
+      afterWrite(ref, result.etag);
+      if (session.wholeEtag(ref) === etag) session.markWhole(ref, result.etag);
+      else session.clearWhole(ref);
+      return {
+        ref,
+        host,
+        etag: result.etag,
+        changed: result.changed,
+        chars: html.length,
+        undoVersionId: result.undoVersionId,
+      };
+    },
+
+    async save_document(input = {}) {
+      refuseReadOnly();
+      const { host, adapter, id, ref } = await targetFor(input);
+      refuseSecret(input.html);
+      const etag = etagFor(input, ref, { whole: true });
+      const result = await adapter.save(id, { html: input.html, etag });
+      afterWrite(ref, result.etag);
+      session.markWhole(ref, result.etag);
+      return {
+        ref,
+        host,
+        etag: result.etag,
+        changed: result.changed,
+        undoVersionId: result.undoVersionId,
+      };
+    },
+
+    async list_versions(input = {}) {
+      const { host, adapter, id, ref } = await targetFor(input);
+      const result = await adapter.versions(id, { before: input.before });
+      return { ref, host, versions: result.versions, nextBefore: result.nextBefore };
+    },
+
+    async read_version(input = {}) {
+      const { host, adapter, id, ref } = await targetFor(input);
+      const version = await adapter.version(id, input.version);
+      const maxChars = input.maxChars ?? 40000;
+      const shaped = shapeRead({
+        ref,
+        host,
+        etag: version.etag,
+        html: version.html,
+        maxChars,
+        input: { select: input.select, range: input.range },
+      });
+      const { ref: shapedRef, host: shapedHost, etag: shapedEtag, ...rest } = shaped;
+      const result = { ref: shapedRef, host: shapedHost };
+      if (shapedEtag !== undefined) result.etag = shapedEtag;
+      result.version = input.version;
+      return Object.assign(result, rest);
+    },
+
+    async restore_version(input = {}) {
+      refuseReadOnly();
+      const { host, adapter, id, ref } = await targetFor(input);
+      const etag = etagFor(input, ref);
+      const result = await adapter.restore(id, input.version, { etag });
+      afterWrite(ref, result.etag);
+      return { ref, host, etag: result.etag };
+    },
+  };
+}