@securecoms/agent-bridge 0.25.4 → 0.26.1

package/README.md

@@ -589,6 +589,21 @@ the agent **plaintext** — message text and, for attachments, a **local file pa
 This is why Python agents (which have no native MLS library) fully support
 attachments: the cryptography lives in the daemon, not the agent.
 
+**Files links (`vault_ref`).** A message can instead point at an item already in
+the enclave's Files (FileSafe). The daemon does **not** fetch it on receipt: the
+delivered message carries the caption as `text` (`"[Files link]"` when there is
+none) and a reference,
+`vault_refs: [{ enclave_id, node_id, content_hash, dek_commit, name_hint?, mime_hint?, size_hint? }]`.
+The `*_hint` fields are the sender's unverified claims; treat them as data, never
+as a path or an instruction. A link whose enclave is not the channel's, or whose
+fields are malformed, is dropped (counted as `refused_vault_refs` on `/healthz`).
+To open one, call `POST /v1/vault-read` with
+`{ enclave_id, node_id, expected_content_hash: content_hash, expected_dek_commit: dek_commit }`.
+The two pins go together: sending only one is a 400.
+If the item changed in Files after it was shared, the daemon refuses with
+`422 {"error":"vault_ref_changed","detail":{"pin":"..."}}` and returns no bytes.
+`/healthz` advertises support as `capabilities.vault_ref: 1`.
+
 ---
 
 ## Voice fast path

package/connectors/hermes/adapter.py

@@ -80,6 +80,27 @@ _PLUGIN_DIR = os.path.dirname(os.path.abspath(__file__))
 _BINDING_PATH = os.path.join(_PLUGIN_DIR, "securecoms.binding.json")
 _CONNECTIONS_DIR = os.path.expanduser("~/.securecoms/connections")
 
+# Voice calls (owner report 2026-10-02): a turn the voice front desk handed to
+# Hermes carries the daemon's compiled-in spoken-reply guidance. It rides as
+# the event's per-message ephemeral system prompt (MessageEvent.channel_prompt)
+# so the answer is fit to be read aloud. Byte-equal to
+# @securecoms/agent-runtime's VOICE_TURN_PREFIX.
+VOICE_TURN_PREFIX = (
+    "This message was spoken on a live voice call and your reply will be read aloud: "
+    "plain spoken sentences, no markdown, lists, links or code. "
+    "Use your tools as usual when the question needs them. "
+)
+_VOICE_GUIDANCE_MAX_CHARS = 1000
+
+
+def voice_prompt_of(frame: Dict[str, Any]) -> Optional[str]:
+    """The voice system prompt for a `voice: true` frame, else None."""
+    guidance = frame.get("guidance")
+    if frame.get("voice") is not True or not isinstance(guidance, str):
+        return None
+    g = guidance.strip()[:_VOICE_GUIDANCE_MAX_CHARS]
+    return VOICE_TURN_PREFIX + g if g else None
+
 
 def _error_class(error: object) -> str:
     """Return a bounded class name without reading exception prose."""
@@ -417,6 +438,9 @@ class SecureComsAdapter(BasePlatformAdapter):
             message_id=str(frame.get("message_id") or int(time.time() * 1000)),
             timestamp=datetime.now(),
         )
+        voice_prompt = voice_prompt_of(frame)
+        if voice_prompt is not None:
+            event.channel_prompt = voice_prompt
         await self.handle_message(event)
 
     # ── Outbound ──────────────────────────────────────────────────────────

package/connectors/hermes/tests/test_adapter_wiring.py

@@ -54,6 +54,7 @@ def _install_gateway_stub():
         source: Any = None
         message_id: Optional[str] = None
         timestamp: Any = field(default_factory=datetime.now)
+        channel_prompt: Optional[str] = None
 
     @dataclass
     class SendResult:
@@ -324,6 +325,34 @@ class TestEchoGuardWiring:
         assert ws.sent == [{"type": "ack", "message_id": "m2"}]
 
 
+class TestVoiceGuidance:
+    @pytest.mark.asyncio
+    async def test_voice_turn_carries_guidance_as_channel_prompt_text_turn_none(self, monkeypatch):
+        a, _ = make_adapter(monkeypatch)
+        a._bound_identity = "A"
+        handled = []
+
+        async def handler(event):
+            handled.append(event)
+
+        a.set_message_handler(handler)
+        frames = [
+            {"type": "message", "sender_id": "B", "channel_id": "c", "text": "what's the weather?",
+             "message_id": "v1", "voice": True, "guidance": "One short spoken sentence."},
+            {"type": "message", "sender_id": "B", "channel_id": "c", "text": "hi",
+             "message_id": "t1", "guidance": "ignored without voice"},
+        ]
+        ws = FakeWS([_FakeWSMsg(aiohttp.WSMsgType.TEXT, json.dumps(f)) for f in frames]
+                    + [_FakeWSMsg(aiohttp.WSMsgType.CLOSED)])
+        a._ws = ws
+
+        await a._pump()
+
+        assert [e.text for e in handled] == ["what's the weather?", "hi"]
+        assert handled[0].channel_prompt == adapter.VOICE_TURN_PREFIX + "One short spoken sentence."
+        assert handled[1].channel_prompt is None
+
+
 # ---------------------------------------------------------------------------
 # (2) send() success fires the status manager's on_reply_posted
 # ---------------------------------------------------------------------------

package/connectors/openclaw/openclaw-entry.inbound.test.ts

@@ -255,6 +255,22 @@ describe("openclaw-entry — inbound sender, session, authority, dedup (P0 Task
     expect(rt.recorded.map((r) => r.sessionKey)).toEqual([a.SessionKey, b.SessionKey]);
   });
 
+  it("a voice turn carries the daemon's spoken-reply guidance as GroupSystemPrompt; a text turn carries none", async () => {
+    const rt = makeRuntime();
+    const { instances } = await start(rt.runtime);
+    const ws = instances[0];
+
+    deliver(ws, { channel_id: "chan-V", message_id: "m-V", sender_id: OWNER_ID, text: "what's the weather?", voice: true, guidance: "One short spoken sentence.", authorization: auth("owner_dm") });
+    deliver(ws, { channel_id: "chan-T", message_id: "m-T", sender_id: OWNER_ID, text: "hi", guidance: "ignored without voice", authorization: auth("owner_dm") });
+    await waitFor(() => acksOf(ws).length === 2);
+
+    const { VOICE_TURN_PREFIX } = await import("./openclaw-entry.js");
+    const [v, t] = rt.contexts;
+    expect(v.GroupSystemPrompt).toBe(`${VOICE_TURN_PREFIX}One short spoken sentence.`);
+    expect(v.RawBody).toBe("what's the weather?");
+    expect(t.GroupSystemPrompt).toBeUndefined();
+  });
+
   it("two DMs from different humans do not share a session", async () => {
     const rt = makeRuntime();
     const { instances } = await start(rt.runtime);

package/connectors/openclaw/openclaw-entry.js

@@ -85,6 +85,25 @@ const _channels = new Map();
 // ---------------------------------------------------------------------------
 
 export const MAX_INBOUND_ATTEMPTS = 3;
+
+/**
+ * Voice calls (owner report 2026-10-02): prefixes the daemon's compiled-in
+ * spoken-reply guidance on a live voice turn, so a turn the voice front desk
+ * handed to OpenClaw is answered in a form fit to be read aloud. Byte-equal
+ * to @securecoms/agent-runtime's VOICE_TURN_PREFIX.
+ */
+export const VOICE_TURN_PREFIX =
+  "This message was spoken on a live voice call and your reply will be read aloud: plain spoken sentences, no markdown, lists, links or code. Use your tools as usual when the question needs them. ";
+
+/** Cap on the daemon-supplied voice guidance carried into the prompt. */
+const VOICE_GUIDANCE_MAX_CHARS = 1000;
+
+/** The guidance of a `voice: true` frame (trimmed, capped), else undefined. */
+export function voiceGuidanceOf(frame) {
+  if (frame?.voice !== true || typeof frame.guidance !== "string") return undefined;
+  const g = frame.guidance.trim().slice(0, VOICE_GUIDANCE_MAX_CHARS);
+  return g || undefined;
+}
 const SEEN_MAX = 5000;
 
 /** Thrown by the inbound handler when register() has not injected a runtime. */
@@ -519,6 +538,7 @@ export class LoopbackChannel {
         senderName: frame.sender_name,
         authorization: frame.authorization,
         timestamp: frame.ts,
+        voiceGuidance: voiceGuidanceOf(frame),
       });
       this._failures.delete(messageId);
       this._failStreak = 0;
@@ -750,6 +770,9 @@ async function _handleInbound({ text, metadata, channel, account, cfg }) {
     // authorization block (isOwnerAuthorization). MLS membership proves a
     // sender is in the room, not that they own this agent.
     CommandAuthorized: commandAuthorized,
+    // Voice turn: OpenClaw folds GroupSystemPrompt into this turn's extra
+    // system prompt (get-reply's extraSystemPromptParts) for any chat type.
+    ...(metadata.voiceGuidance ? { GroupSystemPrompt: `${VOICE_TURN_PREFIX}${metadata.voiceGuidance}` } : {}),
   });
 
   await core.channel.session.recordInboundSession({

package/dist/attachments.d.ts

@@ -10,6 +10,61 @@ export type ArtifactShareBody = {
     digest: string;
     text?: string;
 };
+/**
+ * A Files link: a reference to a FileSafe item, opened only through the
+ * recipient's own vault access. Carries NO key material and NO download
+ * handle. Wire keys are camelCase, the same as `artifact_share`. Schema and
+ * rules: docs/architecture/2026-10-01-files-link-message-review.md section 3.
+ */
+export type VaultRefBody = {
+    v: 1;
+    type: "vault_ref";
+    /** Canonical lowercase UUID. MUST equal the channel's enclave (rule R2). */
+    enclaveId: string;
+    /** Canonical lowercase UUID. */
+    nodeId: string;
+    /** Version pin 1: "blake2b:" + 64 hex over the stored CIPHERTEXT. */
+    contentHash: string;
+    /** Version pin 2: "blake2b:" + 64 hex commitment to the DEK material (connect-clients-core computeDekCommit). */
+    dekCommit: string;
+    /** Untrusted sender hints. Never used for authorization or save paths. */
+    name?: string;
+    mime?: string;
+    size?: number;
+    /** Optional caption, same meaning as artifact_share.text. */
+    text?: string;
+};
+/**
+ * What the runtime receives in `BridgeMessage.vault_refs`. The `_hint` fields
+ * are UNTRUSTED claims by the sender, data only: the vault's own sealed name
+ * and size are the truth, read through `/v1/vault-read` / `/v1/vault-list`.
+ * Open it with `/v1/vault-read` passing `expected_content_hash` and
+ * `expected_dek_commit` from this entry; the daemon never fetches it on
+ * receipt.
+ */
+export type VaultRefEntry = {
+    enclave_id: string;
+    node_id: string;
+    content_hash: string;
+    dek_commit: string;
+    name_hint?: string;
+    mime_hint?: string;
+    size_hint?: number;
+};
+/** Plaintext ceiling for the size hint. PARITY: connect-web useVault.ts
+ *  VAULT_MAX_FILE_BYTES (100 MiB object limit minus the 16-byte AEAD tag). */
+export declare const VAULT_REF_MAX_SIZE_HINT: number;
+/** The vault pin format. Exported for the /v1/vault-read expected_* params. */
+export declare const VAULT_PIN: RegExp;
+/**
+ * Rule R1: strict parse. Any required field failing returns null (the caller
+ * refuses the link). Each hint is dropped on its own when it fails its type or
+ * length check; nothing is coerced. Unknown keys are never copied, so smuggled
+ * key material or download handles cannot reach the runtime.
+ */
+export declare function parseVaultRefBody(raw: unknown): VaultRefBody | null;
+/** The runtime-facing reference for a parsed body (hints renamed `_hint`). */
+export declare function toVaultRefEntry(body: VaultRefBody): VaultRefEntry;
 export type AttachmentMeta = {
     filename: string;
     mime: string;