@sentropic/h2a 0.97.0 → 0.97.1

package/dist/runtime/send.js

@@ -0,0 +1,108 @@
+import { randomUUID } from "node:crypto";
+import { createEnvelope, signEnvelope, verifyEnvelopeSignature } from "@sentropic/h2a";
+import { assertHostQualifiedAddress, canonicalAddress, resolveRecipient } from "./local-files/paths.js";
+import { listPresence } from "./local-files/presence.js";
+export const H2A_SEND_MAX_MESSAGE_BYTES = 64 * 1024;
+function requiredText(value, label) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(`h2a send: ${label} must be a non-empty string`);
+    }
+    if (value.includes("\0")) {
+        throw new Error(`h2a send: ${label} must not contain NUL bytes`);
+    }
+    return value;
+}
+function resolveRegisteredName(target, registrations) {
+    if (target.includes(":") || target.includes("~"))
+        return { target, resolved: false };
+    const key = target.trim().toLocaleLowerCase();
+    const matches = registrations.filter((registration) => registration.name?.trim().toLocaleLowerCase() === key);
+    if (matches.length > 1) {
+        throw new Error(`'${target}' is ambiguous — ${matches.length} registered agents share it; ` +
+            `address the exact instance (${matches.map((entry) => entry.instance).join(", ")}).`);
+    }
+    return matches.length === 1
+        ? { target: matches[0].instance, resolved: true }
+        : { target, resolved: false };
+}
+/**
+ * Create and persist one authenticated local message. This is the only send
+ * primitive used by the CLI and MCP adapters: resolution, signing and the
+ * active-key check cannot drift between surfaces.
+ */
+export function sendLocalMessage(input) {
+    const requestedRecipient = requiredText(input.to, "target").trim();
+    const message = requiredText(input.message, "message");
+    if (Buffer.byteLength(message, "utf8") > H2A_SEND_MAX_MESSAGE_BYTES) {
+        throw new Error(`h2a send: message exceeds ${H2A_SEND_MAX_MESSAGE_BYTES} UTF-8 bytes`);
+    }
+    const registration = input.store.findInstance(input.signer.instance);
+    if (!registration) {
+        throw new Error(`h2a send: sender is not registered: ${input.signer.instance}`);
+    }
+    const registrations = input.store.listInstances();
+    const live = listPresence(input.store.paths.root);
+    const registeredName = resolveRegisteredName(requestedRecipient, registrations);
+    const resolution = resolveRecipient({
+        target: registeredName.target,
+        liveInstances: live,
+        registeredInstances: registrations.map((entry) => entry.instance)
+    });
+    if (resolution.kind === "refuse" || resolution.kind === "list") {
+        throw new Error(resolution.reason);
+    }
+    let recipient = registeredName.target;
+    if (resolution.kind === "deliver-resolved")
+        recipient = resolution.recipient;
+    if (resolution.kind === "deliver-hint")
+        recipient = resolution.liveCandidate;
+    assertHostQualifiedAddress(recipient, "recipient");
+    const registeredRecipient = registrations.some((entry) => canonicalAddress(entry.instance) === canonicalAddress(recipient));
+    const liveRecipient = live.filter((session) => canonicalAddress(session.instance) === canonicalAddress(recipient));
+    if (!registeredRecipient && liveRecipient.length === 0) {
+        throw new Error(`h2a send: '${requestedRecipient}' matches no live or registered agent; resolve the peer first.`);
+    }
+    const role = (registration.roles[0] ?? "AGENTS");
+    const scope = registration.scopes[0] ?? "scope:default";
+    const createdAt = new Date((input.now ?? Date.now)()).toISOString();
+    const unsigned = createEnvelope({
+        id: `env:send:${(input.randomId ?? randomUUID)()}`,
+        type: "event",
+        actor: { instance: input.signer.instance, role, scope },
+        target: { instance: recipient },
+        body: { kind: "message", topic: "MESSAGE", text: message },
+        createdAt
+    });
+    const envelope = signEnvelope(unsigned, {
+        by: input.signer.instance,
+        privateKeyPem: input.signer.privateKeyPem
+    });
+    const keyIsActive = input.store
+        .listInstanceKeys(input.signer.instance)
+        .some((publicKeyPem) => verifyEnvelopeSignature(envelope, publicKeyPem, { by: input.signer.instance }));
+    if (!keyIsActive) {
+        throw new Error(`h2a send: private key is not active for ${input.signer.instance}`);
+    }
+    input.store.putInboxMessage(recipient, envelope);
+    const resolutionKind = registeredName.resolved ? "registered-name" : resolution.kind;
+    const reason = registeredName.resolved
+        ? `registered name resolved to ${recipient}.`
+        : resolution.kind === "deliver-hint"
+            ? `live alias resolved directly to ${recipient}.`
+            : "reason" in resolution
+                ? resolution.reason
+                : undefined;
+    return {
+        ok: true,
+        from: input.signer.instance,
+        requestedRecipient,
+        recipient,
+        recipientLive: liveRecipient.length > 0,
+        freshSessions: liveRecipient.length,
+        resolution: resolutionKind,
+        dormant: liveRecipient.length === 0,
+        ...(reason ? { reason } : {}),
+        envelope
+    };
+}
+//# sourceMappingURL=send.js.map

package/dist/runtime/send.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"send.js","sourceRoot":"","sources":["../../src/runtime/send.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentropic/h2a",
-  "version": "0.97.0",
+  "version": "0.97.1",
   "description": "h2a — the unified CLI + core for human-to-agent coordination.",
   "license": "MIT",
   "type": "module",
@@ -55,10 +55,10 @@
     "@sentropic/cluster-mesh": "0.9.0",
     "@sentropic/contracts": "^0.3.0",
     "@sentropic/events": "^0.2.0",
-    "@sentropic/track": "^0.97.0",
+    "@sentropic/track": "^0.97.1",
     "hono": "^4.13.7"
   },
   "peerDependencies": {
-    "@sentropic/h2a-runtime": "^0.97.0"
+    "@sentropic/h2a-runtime": "^0.97.1"
   }
 }

package/skills/h2a/SKILL.md

@@ -148,7 +148,7 @@ Return shape (all cases exit 0 except user errors):
 
 ### `/h2a send <peer> "<text>"`
 
-Compose and route an envelope to a named peer.
+Send an authenticated message to a named peer through the native core tool.
 
 **Resolve-before-send rule (0.59.0+):** Always resolve the peer to its LIVE full id (`host:label:uuid12`) via `h2a_discover_sessions` BEFORE sending. A bare `host:label` sent to an ambiguous target (>1 live agent sharing that alias) or a phantom target (0 live, 0 registered) is now **REFUSED** by `h2a_inbox put` / `h2a` CLI with exit 1. Never invent a sub-label. The safe pattern is: discover → pick the exact live `host:label:uuid12` → send to that. A bare alias is only acceptable for a dormant/wake-drop or exactly 1 live match (the tool surfaces the live candidate in `liveCandidate`).
 
@@ -160,41 +160,19 @@ Steps:
    - If the user names a peer by PURPOSE/role, call `h2a_discover_sessions` with `{ scope: "<purpose>" }`. If the user names a peer by FRIENDLY NAME, call `h2a_discover_sessions` with `{ name: "<substring>" }`. NEVER grep the registry for a name: instance ids are workspace-derived (`host:slug(workspace):uuid`) so a text search misses. If several match, list and ask; if none, the agent hasn't advertised that scope/name.
    - If `<peer>` is missing, list discover and ask the user to pick.
 2. If `"<text>"` is missing, prompt the user for the content.
-3. Compose an `H2AEnvelope` JSON:
-   ```json
-   {
-     "protocol": "sentropic.h2a",
-     "version": "0.1",
-     "id": "env:<epoch-ms>:<4hex>",
-     "type": "event",
-     "actor": {
-       "instance": "<this-agent-instance>",
-       "role": "<this-agent-role-or-AGENTS>",
-       "scope": "<shared-scope-or-default>"
-     },
-     "body": { "kind": "message", "text": "<text>" },
-     "createdAt": "<ISO-8601-now>"
-   }
-   ```
-4. **Hard rule: the recipient MUST be host-qualified (`<host>:<label>`, e.g. `claude:radar-immobilier`). A bare label (e.g. `radar-immobilier`) is rejected — the same label can live on several hosts (claude, codex, …), so a bare label is ambiguous and routes to an orphan inbox nobody reads.**
-
-   Call `h2a_inbox` with `{ action: "put", instance: "<peer>", envelope }`.
-
-   **Conversation threading (optional, lightweight):** To continue an existing back-and-forth as a thread, add two top-level fields to the envelope JSON before putting it:
-   - `"threadId": "<id>"` — reuse the `threadId` from the peer's previous envelope, or mint a fresh one as `thr:<epoch-ms>:<4hex>` to start a new thread.
-   - `"replyTo": "<prev-envelope-id>"` — the `id` of the envelope you are replying to.
-
-   To reconstruct the ordered fil of a thread (for supervision or before opening a formal negotiation):
-   ```sh
-   h2a thread --id <threadId> --instance <self-instance> --root <root>
-   ```
-   This returns the envelopes (from your inbox + outbox) that share that `threadId`, sorted ascending by `createdAt`, deduped. No new store — storage is derived on the fly.
-
-5. **Report honestly per the target's liveness** (h2a writes the inbox unconditionally — it does NOT yet error on a dead target, so YOU must say which it was):
+3. Call `h2a_send` with exactly `{ to: "<peer>", message: "<text>" }`.
+   The local MCP sidecar supplies its trusted signing identity; never request,
+   construct, or pass a private key or sender field. The tool resolves the peer,
+   constructs the canonical envelope, verifies the sender's active key, and only
+   then writes the inbox. If the tool is unavailable because the sidecar has no
+   auto-open signing identity, report that error; do not fall back to unsigned
+   `h2a_inbox put`.
+4. **Report honestly from the tool result:**
    - target was **live** in discover → *"Delivered to `<peer>` (live) — push fires if subscribed."*
    - target was **NOT live** → *"`<peer>` is dormant — envelope deposited for its wake (no live session; it will only see this once woken)."* Never claim "Delivered" to a dormant/unknown peer.
 
-For richer payloads (file pointer, deliverable, status update), set `body.kind` to a category and add the relevant fields; ask the user if ambiguous.
+For richer payloads, use the formal negotiation/inbox contracts; `h2a_send` is
+deliberately the small signed text-message primitive.
 
 ### `/h2a receive`