@panphora/clay-agent 0.0.0-stage → 0.1.0

package/src/discovery.js

@@ -0,0 +1,76 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { homeDir } from './credentials.js';
+
+export function userConfigDir(env = process.env, platform = process.platform) {
+  if (platform === 'darwin') {
+    return path.join(homeDir(env), 'Library', 'Application Support');
+  }
+  if (platform === 'win32') {
+    return env.APPDATA || path.join(homeDir(env), 'AppData', 'Roaming');
+  }
+  return env.XDG_CONFIG_HOME || path.join(homeDir(env), '.config');
+}
+
+function isPositiveInteger(value) {
+  return Number.isInteger(value) && value > 0;
+}
+
+async function readJson(file) {
+  let text;
+  try {
+    text = await fs.readFile(file, 'utf8');
+  } catch {
+    return null;
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+function isObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+export async function htmlClay(env = process.env, platform = process.platform) {
+  const file = path.join(userConfigDir(env, platform), 'htmlclay', 'config.json');
+  const data = await readJson(file);
+  if (!isObject(data) || !isPositiveInteger(data.port)) return null;
+  return { port: data.port };
+}
+
+export function defaultIsAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === 'EPERM';
+  }
+}
+
+export async function hyperclayLocal(env = process.env, platform = process.platform, { isAlive = defaultIsAlive } = {}) {
+  const file = path.join(userConfigDir(env, platform), 'Hyperclay Local', 'served-roots.json');
+  const data = await readJson(file);
+  if (!isObject(data)) return null;
+  if (data.v !== 1) return null;
+  if (typeof data.pid !== 'number') return null;
+  if (!Array.isArray(data.roots)) return null;
+  if (!isAlive(data.pid)) return null;
+
+  const roots = [];
+  for (const root of data.roots) {
+    if (!isObject(root)) continue;
+    if (typeof root.path !== 'string' || !path.isAbsolute(root.path)) continue;
+    if (!isPositiveInteger(root.port)) continue;
+    roots.push({ path: root.path, port: root.port });
+  }
+  return { roots };
+}
+
+export async function discover(env = process.env, platform = process.platform, options = {}) {
+  const [clay, local] = await Promise.all([htmlClay(env, platform), hyperclayLocal(env, platform, options)]);
+  return { htmlClay: clay, hyperclayLocal: local };
+}

package/src/errors.js

@@ -0,0 +1,90 @@
+// One error type for both front doors. The MCP server turns it into `isError` with
+// `{ error: { code, message, hint } }`; the CLI prints it and exits with `exitCode(code)`.
+
+export class ClayError extends Error {
+  constructor(code, message, { hint = null, status = null, etag = null, retryable = false, details = null } = {}) {
+    super(message);
+    this.name = 'ClayError';
+    this.code = code;
+    this.hint = hint;
+    this.status = status;
+    this.etag = etag;
+    this.retryable = retryable;
+    this.details = details;
+  }
+
+  toJSON() {
+    const error = { code: this.code, message: this.message };
+    if (this.hint) error.hint = this.hint;
+    if (this.status) error.status = this.status;
+    if (this.etag) error.etag = this.etag;
+    if (this.retryable) error.retryable = true;
+    if (this.details) error.details = this.details;
+    return redact({ error });
+  }
+}
+
+const KEY_PATTERN = /hcak_[0-9a-f]{64}/gi;
+
+function redactString(text) {
+  return text.replace(KEY_PATTERN, (key) => `${key.slice(0, 13)}\u2026`);
+}
+
+// A key never reaches output: keep the prefix the dashboard shows, drop the rest.
+export function redact(value) {
+  if (typeof value === 'string') return redactString(value);
+  if (Array.isArray(value)) return value.map(redact);
+  if (value && typeof value === 'object') {
+    const result = {};
+    for (const [name, item] of Object.entries(value)) {
+      result[redactString(name)] = redact(item);
+    }
+    return result;
+  }
+  return value;
+}
+
+// 0 done, 1 refused or failed, 2 conflict, 3 host unreachable,
+// 4 not signed in or bad key, 5 outcome unknown.
+const EXIT = {
+  conflict: 2,
+  'host-unavailable': 3,
+  unauthorized: 4,
+  'key-missing': 4,
+  'key-revoked': 4,
+  'key-expired': 4,
+  'invalid-key': 4,
+  'outcome-unknown': 5,
+};
+
+export function exitCode(code) {
+  return EXIT[code] ?? 1;
+}
+
+const NETWORK_CODES = new Set([
+  'ECONNREFUSED',
+  'ECONNRESET',
+  'ENOTFOUND',
+  'EAI_AGAIN',
+  'ENETUNREACH',
+  'ETIMEDOUT',
+]);
+
+function isNetworkError(error) {
+  for (const code of [error?.code, error?.cause?.code]) {
+    if (typeof code !== 'string') continue;
+    if (NETWORK_CODES.has(code) || code.startsWith('UND_ERR_')) return true;
+  }
+  return false;
+}
+
+export function asClayError(error) {
+  if (error instanceof ClayError) return error;
+  if (isNetworkError(error)) {
+    return new ClayError('host-unavailable', 'Could not reach the host.', {
+      hint: 'Check your internet connection, or open the desktop app if this is a local document, then try again.',
+      retryable: true,
+    });
+  }
+  return new ClayError('internal', 'Something went wrong inside clay-agent.');
+}

package/src/hosts/hyperclay-adapter.js

@@ -0,0 +1,85 @@
+import { ClayError } from '../errors.js';
+
+const PLAIN_USERNAME = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+
+function stringId(value) {
+  return value === undefined || value === null ? null : String(value);
+}
+
+function sameUrl(left, right) {
+  const normalize = (url) => String(url ?? '').replace(/\/$/, '').replace(/\.html$/, '');
+  return normalize(left) === normalize(right);
+}
+
+export function hyperclayAdapter(client) {
+  const byUrl = new Map();
+
+  async function locate(target) {
+    if (target.url) {
+      let found = byUrl.get(target.url);
+      if (!found) {
+        const listed = await client.list({ url: target.url });
+        const match = (listed?.documents ?? []).find((doc) => sameUrl(doc.url, target.url));
+        if (!match) {
+          throw new ClayError('not-found', 'No document at that URL that this key can reach.');
+        }
+        found = { id: match.id, ref: `hyperclay:${match.id}` };
+        byUrl.set(target.url, found);
+      }
+      return { id: found.id, ref: found.ref };
+    }
+    return { id: target.id, ref: target.ref };
+  }
+
+  async function list({ where, cursor } = {}) {
+    const query = { cursor };
+    if (where !== undefined && where !== null && where !== '') {
+      if (String(where).includes('hcak_')) {
+        throw new ClayError('invalid-argument', 'Do not put an agent key in a document search.');
+      }
+      if (PLAIN_USERNAME.test(where)) query.account = where;
+      else query.url = where;
+    }
+    const result = await client.list(query);
+    const documents = (result?.documents ?? []).map((doc) => ({
+      ref: `hyperclay:${doc.id}`,
+      host: 'hyperclay',
+      name: doc.name,
+      url: doc.url,
+      path: doc.path,
+      updatedAt: doc.updatedAt,
+    }));
+    return { documents, nextCursor: stringId(result?.nextCursor) };
+  }
+
+  return {
+    locate,
+    list,
+    read(id, { ifNoneMatch } = {}) {
+      return client.read(id, { ifNoneMatch });
+    },
+    readData(id) {
+      return client.readData(id);
+    },
+    writeData(id, { data, etag } = {}) {
+      return client.writeData(id, { data, etag });
+    },
+    save(id, { html, etag } = {}) {
+      return client.save(id, { html, etag });
+    },
+    async versions(id, { before } = {}) {
+      const result = await client.versions(id, { before });
+      return {
+        ...result,
+        versions: (result?.versions ?? []).map((version) => ({ ...version, id: stringId(version?.id) })),
+        nextBefore: stringId(result?.nextBefore),
+      };
+    },
+    version(id, versionId) {
+      return client.version(id, versionId);
+    },
+    restore(id, versionId, { etag } = {}) {
+      return client.restore(id, versionId, { etag });
+    },
+  };
+}

package/src/hosts/hyperclay.js

@@ -0,0 +1,210 @@
+import { randomUUID } from 'node:crypto';
+
+import { ClayError, asClayError, redact } from '../errors.js';
+
+const KEY_HINT =
+  'Make an agent key in the dashboard (Account, then Agent keys), then run: npx -y @panphora/clay-agent login';
+
+const HINTS = {
+  conflict: 'The document changed after you read it. Read it again and redo the change.',
+  'precondition-required': 'Read the document first, then send its etag.',
+  'read-first': 'Read the document first, then send its etag.',
+  unauthorized: KEY_HINT,
+  'key-revoked': KEY_HINT,
+  'key-expired': KEY_HINT,
+};
+
+export function hyperclayClient({ base, getKey, fetchImpl = fetch, timeoutMs = 30000 } = {}) {
+  const root = `${String(base ?? '').replace(/\/+$/, '')}/_/agent/v1`;
+
+  function requireEtag(method, etag) {
+    if (!etag) {
+      throw new ClayError('read-first', `${method} needs the etag from a read.`, {
+        hint: HINTS['read-first'],
+      });
+    }
+    return etag;
+  }
+
+  function lostOutcome() {
+    return new ClayError('outcome-unknown', 'The change may or may not have been saved.', {
+      hint: 'Read the document again before trying anything else.',
+    });
+  }
+
+  function isTimeout(error) {
+    return error?.name === 'TimeoutError' || error?.cause?.name === 'TimeoutError';
+  }
+
+  function tookTooLong() {
+    return new ClayError('host-unavailable', 'The host did not answer in time.', {
+      hint: 'Check your connection, then try again.',
+      retryable: true,
+    });
+  }
+
+  function notSent(error) {
+    const code = error?.code;
+    return code === 'ECONNREFUSED' || code === 'ENOTFOUND' || code === 'EAI_AGAIN' || code === 'ENETUNREACH';
+  }
+
+  async function request(pathname, { method = 'GET', query = null, body, etag, ifNoneMatch } = {}) {
+    const key = getKey ? await getKey() : null;
+    if (!key) {
+      throw new ClayError('key-missing', 'Not signed in to hyperclay.com.', { hint: KEY_HINT });
+    }
+
+    const write = method !== 'GET';
+    const url = new URL(`${root}${pathname}`);
+
+    if (query) {
+      for (const [name, value] of Object.entries(query)) {
+        if (value === undefined || value === null) continue;
+        url.searchParams.set(name, String(value));
+      }
+    }
+
+    const headers = {
+      Authorization: `Bearer ${key}`,
+      Accept: 'application/json',
+    };
+    if (body !== undefined) headers['Content-Type'] = 'application/json';
+    if (etag) headers['If-Match'] = etag;
+    if (ifNoneMatch) headers['If-None-Match'] = ifNoneMatch;
+
+    let response;
+    try {
+      response = await fetchImpl(url, {
+        method,
+        headers,
+        body: body === undefined ? undefined : JSON.stringify(body),
+        redirect: 'error',
+        signal: AbortSignal.timeout(timeoutMs),
+      });
+    } catch (error) {
+      if (isTimeout(error)) {
+        if (write) throw lostOutcome();
+        throw tookTooLong();
+      }
+      const cause = error?.cause ?? error;
+      if (write && !notSent(cause)) throw lostOutcome();
+      throw asClayError(cause);
+    }
+
+    let text;
+    try {
+      text = await response.text();
+    } catch (error) {
+      if (write) throw lostOutcome();
+      if (isTimeout(error)) throw tookTooLong();
+      throw asClayError(error?.cause ?? error);
+    }
+
+    let parsed = null;
+    if (text) {
+      try {
+        parsed = JSON.parse(text);
+      } catch {
+        parsed = null;
+      }
+    }
+
+    const detail = parsed?.error;
+
+    if (response.status === 304) {
+      return { notModified: true, etag: ifNoneMatch ?? null };
+    }
+
+    if (response.ok) {
+      if (parsed === null) {
+        if (write) throw lostOutcome();
+        throw new ClayError('host-error', redact(`hyperclay.com answered ${response.status}.`), {
+          status: response.status,
+        });
+      }
+      if (write && typeof parsed.etag !== 'string') throw lostOutcome();
+      return parsed;
+    }
+
+    if (detail?.code) {
+      const details = {};
+      for (const [name, value] of Object.entries(detail)) {
+        if (name === 'code' || name === 'message' || name === 'etag') continue;
+        details[name] = value;
+      }
+      const retryable = response.status === 429 || response.status === 503;
+      if (retryable) {
+        const retryAfter = response.headers.get('retry-after');
+        const seconds = Number(retryAfter);
+        if (retryAfter !== null && Number.isFinite(seconds)) details.retryAfter = seconds;
+      }
+      throw new ClayError(detail.code, redact(detail.message || 'hyperclay.com refused this request.'), {
+        hint: HINTS[detail.code] ?? null,
+        status: response.status,
+        etag: detail.etag ?? null,
+        retryable,
+        details: Object.keys(details).length ? details : null,
+      });
+    }
+
+    if (write && response.status >= 500) throw lostOutcome();
+
+    if (response.status === 404) {
+      throw new ClayError('not-found', 'This host does not have agent keys turned on.', {
+        status: response.status,
+      });
+    }
+
+    throw new ClayError('host-error', redact(`hyperclay.com answered ${response.status}.`), {
+      status: response.status,
+    });
+  }
+
+  return {
+    list({ account, url, cursor, limit } = {}) {
+      return request('/documents', { query: { account, url, cursor, limit } });
+    },
+
+    read(id, { ifNoneMatch } = {}) {
+      return request(`/documents/${encodeURIComponent(id)}`, { ifNoneMatch });
+    },
+
+    readData(id) {
+      return request(`/documents/${encodeURIComponent(id)}/data`);
+    },
+
+    versions(id, { before } = {}) {
+      return request(`/documents/${encodeURIComponent(id)}/versions`, { query: { before } });
+    },
+
+    version(id, versionId) {
+      return request(`/documents/${encodeURIComponent(id)}/versions/${encodeURIComponent(versionId)}`);
+    },
+
+    async save(id, { html, etag } = {}) {
+      const match = requireEtag('Saving', etag);
+      return request(`/documents/${encodeURIComponent(id)}`, {
+        method: 'PUT',
+        etag: match,
+        body: { html, operationId: randomUUID() },
+      });
+    },
+
+    async writeData(id, { data, etag } = {}) {
+      const match = requireEtag('Writing data', etag);
+      return request(`/documents/${encodeURIComponent(id)}/data`, {
+        method: 'POST',
+        etag: match,
+        body: { data, operationId: randomUUID() },
+      });
+    },
+
+    async restore(id, versionId, { etag } = {}) {
+      const match = requireEtag('Restoring', etag);
+      return request(
+        `/documents/${encodeURIComponent(id)}/versions/${encodeURIComponent(versionId)}/restore`,
+        { method: 'POST', etag: match, body: { operationId: randomUUID() } },
+      );
+    },
+  };
+}

package/src/hosts/whoami.js

@@ -0,0 +1,56 @@
+import { ClayError, asClayError, redact } from '../errors.js';
+
+const TIMEOUT_MS = 30000;
+
+function isTimeout(error) {
+  return error?.name === 'TimeoutError' || error?.cause?.name === 'TimeoutError';
+}
+
+export async function whoami(base, key) {
+  let response;
+  try {
+    response = await fetch(`${base}/_/agent/v1/whoami`, {
+      headers: { Authorization: `Bearer ${key}` },
+      redirect: 'error',
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+  } catch (error) {
+    if (isTimeout(error)) {
+      throw new ClayError('host-unavailable', 'The host did not answer in time.', {
+        hint: 'Check your connection, then try again.',
+        retryable: true,
+      });
+    }
+    throw asClayError(error?.cause ?? error);
+  }
+
+  if (response.status === 200) {
+    try {
+      return await response.json();
+    } catch (error) {
+      throw asClayError(error);
+    }
+  }
+
+  let body = null;
+  try {
+    body = await response.json();
+  } catch {
+    body = null;
+  }
+
+  const error = body?.error;
+  if (error?.code) {
+    throw new ClayError(error.code, redact(error.message || 'The host refused this agent key.'), {
+      status: response.status,
+    });
+  }
+
+  if (response.status === 404) {
+    throw new ClayError('not-found', 'This host does not have agent keys turned on.');
+  }
+
+  throw new ClayError('internal', redact(`The host answered with ${response.status}.`), {
+    status: response.status,
+  });
+}

package/src/html/edit.js

@@ -0,0 +1,103 @@
+import { ClayError } from '../errors.js';
+
+const MAX_EDITS = 50;
+const OFFSET_SAMPLE = 5;
+
+function invalid(message, hint) {
+  return new ClayError('invalid-edits', message, { hint });
+}
+
+function locate(html, needle) {
+  const offsets = [];
+  let from = 0;
+  for (;;) {
+    const start = html.indexOf(needle, from);
+    if (start === -1) break;
+    offsets.push(start);
+    from = start + 1;
+  }
+  return offsets;
+}
+
+function checkShape(edits) {
+  if (!Array.isArray(edits) || edits.length < 1 || edits.length > MAX_EDITS) {
+    throw invalid(
+      `\`edits\` must hold between 1 and ${MAX_EDITS} edits.`,
+      'Pass an array of `{ find, replace }` objects, optionally with a 1-based `occurrence`.',
+    );
+  }
+  for (const edit of edits) {
+    if (!edit || typeof edit !== 'object' || Array.isArray(edit)) {
+      throw invalid('Each edit must be an object with `find` and `replace`.', 'Pass `{ find, replace }`.');
+    }
+    if (typeof edit.find !== 'string' || edit.find.length === 0) {
+      throw invalid('Each edit needs a non-empty `find` string.', 'Copy the exact text from a read.');
+    }
+    if (typeof edit.replace !== 'string') {
+      throw invalid('Each edit needs a `replace` string.', 'Use an empty string to delete the text.');
+    }
+    if (edit.occurrence !== undefined && (!Number.isInteger(edit.occurrence) || edit.occurrence < 1)) {
+      throw invalid('`occurrence` must be a whole number counting from 1.', 'Pass `occurrence: 2` for the second match.');
+    }
+  }
+}
+
+export function applyEdits(html, edits) {
+  checkShape(edits);
+  const planned = [];
+  for (let index = 0; index < edits.length; index += 1) {
+    const edit = edits[index];
+    const offsets = locate(html, edit.find);
+    if (offsets.length === 0) {
+      throw new ClayError('edit-not-found', `Edit ${index + 1} did not match any text.`, {
+        hint: 'Read the document again and copy the text exactly, including whitespace.',
+        details: { index },
+      });
+    }
+    let offset;
+    if (edit.occurrence === undefined) {
+      if (offsets.length > 1) {
+        throw new ClayError(
+          'edit-not-unique',
+          `Edit ${index + 1} matches ${offsets.length} places, so it is ambiguous.`,
+          {
+            hint: 'Add surrounding text to `find` so it is unique, or pass `occurrence` to pick one.',
+            details: { index, count: offsets.length, offsets: offsets.slice(0, OFFSET_SAMPLE) },
+          },
+        );
+      }
+      offset = offsets[0];
+    } else {
+      if (edit.occurrence > offsets.length) {
+        throw new ClayError(
+          'edit-not-found',
+          `Edit ${index + 1} asked for occurrence ${edit.occurrence}, but the text occurs ${offsets.length} times.`,
+          {
+            hint: 'Read the document again and count the occurrences, or drop `occurrence` when the text is unique.',
+            details: { index },
+          },
+        );
+      }
+      offset = offsets[edit.occurrence - 1];
+    }
+    planned.push({ index, start: offset, end: offset + edit.find.length, replace: edit.replace });
+  }
+  for (let a = 0; a < planned.length; a += 1) {
+    for (let b = a + 1; b < planned.length; b += 1) {
+      const one = planned[a];
+      const two = planned[b];
+      if (one.start < two.end && two.start < one.end) {
+        throw new ClayError('edits-overlap', `Edits ${one.index + 1} and ${two.index + 1} overlap.`, {
+          hint: 'Give each edit its own non-overlapping text, or merge them into one edit.',
+          details: { indexes: [one.index, two.index] },
+        });
+      }
+    }
+  }
+  planned.sort((one, two) => two.start - one.start);
+  let output = html;
+  for (const edit of planned) {
+    output = output.slice(0, edit.start) + edit.replace + output.slice(edit.end);
+  }
+  return { html: output, applied: planned.length };
+}