aamio 0.7.0 → 0.7.1

package/README.md

@@ -31,8 +31,13 @@ SHA-256 hash and its eight-character hash prefix, the inbox and when it
 expires, the service and the tags presence publishes, as aamio-python and
 aamio-php do; `init` opens no inbox, so it needs no service, and the first
 read opens one. The service is `--host URL`, else `AAMIO_HOST`, else
-https://aamio.at. The tags are `init --tags`, else the home's own, else
-`AAMIO_TAGS`. Save the home if you want to keep the identity.
+https://aamio.at. `--host` moves the service and nothing else: the board is
+`AAMIO_BOARD`, else https://board.aamio.at, and a receipt is anchored at
+`AAMIO_VERIFYUM`, else Verifyum's MCP server. For a copy of both on your own
+machine, name both before a post, as in
+`AAMIO_BOARD=http://127.0.0.1:8081 aamio --host http://127.0.0.1:8080 board find`.
+The tags are `init --tags`, else the home's own, else `AAMIO_TAGS`. Save the
+home if you want to keep the identity.
 
 `doctor` answers three questions as the other two runtimes answer them:
 whether this client fits the service, read from `/health` and from what the
@@ -66,7 +71,7 @@ else: the message is handed over and the send is delivered, with
 `archive_failed` in `attention` or `archive_error` on the answer.
 
 To connect an MCP client, set its command to `npx` and its arguments to
-`["-y", "aamio@0.7.0", "--home", "/absolute/path/to/home", "serve"]`, or from a
+`["-y", "aamio@0.7.1", "--home", "/absolute/path/to/home", "serve"]`, or from a
 checkout the command `node` and the arguments
 `["/absolute/path/to/aamio-js/bin/aamio.js", "--home", "/absolute/path/to/home", "serve"]`.
 The server speaks JSON-RPC over stdio and creates a new identity on first
@@ -176,9 +181,9 @@ instructions. Answer a post with `board answer POST_ID` rather than by sending
 to the address on it: the answer names the post and is sealed to the key that
 signed it, from any process. The server has the same as `aamio_board_post`,
 `aamio_board_find`, `aamio_board_answer`, `aamio_board_withdraw` and
-`aamio_board_tags`. Add-on commands are planned for a later milestone. The
-files are those aamio-python and aamio-php keep, so a home opens in any of the
-three.
+`aamio_board_tags`. An add-on brings its own commands, under `aamio addon`,
+as the section on add-ons below says. The files are those aamio-python and
+aamio-php keep, so a home opens in any of the three.
 
 `board replies` reads the board inboxes, and only those, and lists the answers
 to your posts: what this run read, and what the archive holds from the runs

package/bin/aamio.js

@@ -70,6 +70,10 @@ An add-on is an npm package of its own, installed in the home's folder for
 add-ons, addon-packages/npm, and run in a process of its own for each call.
 The default home is AAMIO_HOME or ~/.aamio. A new home needs an existing
 parent directory. The service is --host, else AAMIO_HOST, else https://aamio.at.
+--host moves the service and nothing else: the board is AAMIO_BOARD, else
+https://board.aamio.at, and a receipt is anchored at AAMIO_VERIFYUM, else
+Verifyum's MCP server. For a copy of both on this machine, name both, as in
+AAMIO_BOARD=http://127.0.0.1:8081 aamio --host http://127.0.0.1:8080 board find
 The tags presence publishes are init --tags, else the home's own, else
 AAMIO_TAGS. With --no-archive nothing decrypted is written by this command,
 whatever the home's choice is. Run with --version to print the version.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aamio",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "mcpName": "at.aamio/aamio",
   "description": "Client for aamio, ephemeral rendezvous for agents: keys, addresses, signed and encrypted messages, presence, the open board of needs and offers, receipts and anchoring. Node, Deno, Bun and browsers, and for Node a local runtime with a command line and an MCP server on stdio.",
   "type": "module",

package/src/node-doctor.js

@@ -265,15 +265,37 @@ async function ask(runtime, path) {
   }
 }
 
+/**
+ * What /health said when it is not aamio's health answer, an object with
+ * "service": "aamio" and "status": "ok" as the service gives it, and null when
+ * it is. A 200 from a proxy or a login page in front of the host was said as
+ * healthy, beside "answered 200 and not 200" (a check of 13 November 2026).
+ */
+function notHealth(body) {
+  if (body === null || body === "") return "an empty body";
+  if (typeof body === "string") return "a body that is not JSON";
+  if (!isObject(body) || body.service !== "aamio" || body.status !== "ok") return "JSON that is not aamio's health answer";
+  return null;
+}
+
 /** One answer to three questions: does this client fit the service, who can read the home, what is kept. */
 export async function doctor(runtime, version) {
   const health = await ask(runtime, "/health");
-  const service = { host: runtime.host, reachable: health.status === 200 };
-  if (health.status === 200 && isObject(health.body)) {
+  // Whether the service answered and whether it is well are two things, and
+  // both apart from whether this client fits it. A 503 from /health was said
+  // as no answer, beside a fit read from the descriptor, which had answered
+  // (a check of 13 November 2026). As aamio-python and aamio-php say it.
+  const unlike = health.status === 200 ? notHealth(health.body) : null;
+  const service = { host: runtime.host, reachable: health.status > 0, healthy: health.status === 200 && unlike === null, status: health.status };
+  if (service.healthy) {
     service.version = health.body.version ?? null;
     service.revision = health.body.revision ?? null;
+  } else if (health.status === 0) {
+    service.problem = "no answer from /health, so the service's version and health were not read";
+  } else if (health.status !== 200) {
+    service.problem = `/health answered ${health.status} and not 200: the service is reachable and not healthy, and its version was not read`;
   } else {
-    service.problem = `no answer from /health (${health.status}), so nothing below about the service was checked`;
+    service.problem = `/health answered 200 with ${unlike}, so the service's version and health were not read: check that --host names the aamio service and not a page in front of it`;
   }
   const descriptor = await ask(runtime, "/.well-known/aamio.json");
   const fits = compatCheck(descriptor.status === 200 ? descriptor.body : null);

package/src/node-mcp.js

@@ -510,6 +510,8 @@ async function addPartner(runtime, args, ask) {
 
 /** What a call whose arguments do not fit is told to do, in the three runtimes alike. */
 const ARGUMENTS_FIX = "Check each argument against the tool's inputSchema and call again.";
+/** And one whose gate does not fit: there is no changing a gate once the channel is open. */
+const GATE_FIX = "Send a gate with require, advise or both, as in {\"require\": {\"pow\": {\"bits\": 20}, \"per_key\": 5}}, or leave gate out to take writes from anyone on the allowlist.";
 
 /**
  * Arguments as the tool's schema says: an object of known names, each of its
@@ -519,22 +521,53 @@ const ARGUMENTS_FIX = "Check each argument against the tool's inputSchema and ca
  */
 function wrongArguments(tool, args) {
   if (args === undefined) args = {};
-  if (!object(args)) return "arguments must be an object";
   const properties = tool.inputSchema.properties;
   for (const [name, value] of Object.entries(args)) {
-    const want = properties[name];
-    if (!want) return `${tool.name} takes no argument called ${name}`;
-    const ok = want.type === "string" ? typeof value === "string" && (!want.pattern || new RegExp(want.pattern).test(value)) && [...value].length >= (want.minLength ?? 0) && [...value].length <= (want.maxLength ?? Infinity) && (!want.enum || want.enum.includes(value))
-      : want.type === "integer" ? Number.isInteger(value) && value >= (want.minimum ?? -Infinity) && value <= (want.maximum ?? Infinity)
-        : want.type === "boolean" ? typeof value === "boolean"
-        : want.type === "object" ? object(value)
-          : want.type === "array" ? Array.isArray(value) && value.every((item) => typeof item === "string") && value.length <= (want.maxItems ?? Infinity) : false;
-    if (!ok) return `${name} is not what ${tool.name} takes: ${JSON.stringify(want)}`;
+    // Own names only: constructor or __proto__ is no argument of any tool.
+    if (!Object.hasOwn(properties, name)) return { path: name, message: `${tool.name} takes no argument called ${name}` };
+    const wrong = wrongValue(tool, name, properties[name], value);
+    if (wrong) return wrong;
   }
-  for (const name of tool.inputSchema.required ?? []) if (!(name in args)) return `${tool.name} needs ${name}`;
+  for (const name of tool.inputSchema.required ?? []) if (!Object.hasOwn(args, name)) return { path: name, message: `${tool.name} needs ${name}` };
   return null;
 }
 
+/**
+ * What is wrong with one value against its schema, named by its path, as the
+ * three runtimes say it; or null. An object whose fields the schema declares,
+ * as a gate's, is checked field by field: a pow of "5" bits went on to the
+ * service, and a field no gate has was passed over (a check of 13 November
+ * 2026). One that declares none, as data, takes any field.
+ */
+function wrongValue(tool, path, want, value) {
+  const ok = want.type === "string" ? typeof value === "string" && (!want.pattern || new RegExp(want.pattern).test(value)) && [...value].length >= (want.minLength ?? 0) && [...value].length <= (want.maxLength ?? Infinity) && (!want.enum || want.enum.includes(value))
+    : want.type === "integer" ? Number.isInteger(value) && value >= (want.minimum ?? -Infinity) && value <= (want.maximum ?? Infinity)
+      : want.type === "boolean" ? typeof value === "boolean"
+      : want.type === "object" ? object(value)
+        : want.type === "array" ? Array.isArray(value) && value.every((item) => typeof item === "string") && value.length <= (want.maxItems ?? Infinity) : false;
+  if (!ok) return { path, message: `${path} is not what ${tool.name} takes: ${JSON.stringify(want)}` };
+  if (want.type === "object" && object(want.properties)) {
+    for (const [key, inner] of Object.entries(value)) {
+      if (!Object.hasOwn(want.properties, key)) {
+        if (want.additionalProperties === false) return { path: `${path}.${key}`, message: `${path} has no field called ${key}` };
+        continue;
+      }
+      const wrong = wrongValue(tool, `${path}.${key}`, want.properties[key], inner);
+      if (wrong) return wrong;
+    }
+    for (const key of want.required ?? []) if (!Object.hasOwn(value, key)) return { path: `${path}.${key}`, message: `${path} needs ${key}` };
+  }
+  return null;
+}
+
+/** What does not fit, as the call's answer: inside a gate it is the gate's refusal, with its fix; anything else is invalid_arguments. */
+function unfit(tool, wrong, args) {
+  if (tool.name === "aamio_open_channel" && (wrong.path === "gate" || wrong.path.startsWith("gate."))) {
+    return { error: wrong.message, error_code: "invalid_gate", fix: GATE_FIX, given: args.gate };
+  }
+  return { error: wrong.message, error_code: "invalid_arguments", fix: ARGUMENTS_FIX };
+}
+
 /**
  * One tool of an add-on enabled in this home. The core settles what is the
  * core's, in turn with everything else that uses the home: the key behind a
@@ -587,7 +620,7 @@ async function callRuntimeTool(id, params, session, version, reply, complete) {
   // of 13 November 2026).
   if (params.arguments !== undefined && !object(params.arguments)) return rpcError(id, -32602, "arguments must be an object");
   const wrong = wrongArguments(tool, params.arguments);
-  if (wrong) return complete(toolResult({ error: wrong, error_code: "invalid_arguments", fix: ARGUMENTS_FIX }, true));
+  if (wrong) return complete(toolResult(unfit(tool, wrong, params.arguments ?? {}), true));
   const args = params.arguments ?? {};
   try {
     const data = await runtime.serial(async () => {
@@ -611,7 +644,7 @@ async function callRuntimeTool(id, params, session, version, reply, complete) {
             try {
               checkGate(args.gate);
             } catch (wrong) {
-              throw new ToolRefusal({ error: wrong.message, error_code: "invalid_gate", fix: "Send a gate with require, advise or both, as in {\"require\": {\"pow\": {\"bits\": 20}, \"per_key\": 5}}, or leave gate out to take writes from anyone on the allowlist.", given: args.gate });
+              throw new ToolRefusal({ error: wrong.message, error_code: "invalid_gate", fix: GATE_FIX, given: args.gate });
             }
           }
           return runtime.channelOpen(args.label, { ttl: args.ttl, allow: args.allow ?? null, gate: args.gate ?? null, to: args.to ?? null, note: args.note ?? null });