Skip to content

feat: return inbox results to the originating Hermes session #152

Description

@dnth

Context

PR #151 adds a trusted-local durable orchestrator inbox for asynchronous handoffs into FirstMate. A local sender such as Hermes can persist a detailed brief, submit a short inbox note, and wake FirstMate through the existing durable wake queue.

The first release intentionally covers ingress only: note, list, drain --ack, and status. It does not provide a durable way for FirstMate to return completion status, artifacts, or failure details to the originating Hermes session.

Goal

Add a durable result envelope and delivery lifecycle so a FirstMate task created from a local inbox note can return its outcome to the originating Hermes session or another explicitly declared local recipient.

This should complete the asynchronous flow:

Hermes -> durable brief + inbox note -> FirstMate -> work result -> durable result envelope -> Hermes

Proposed Direction

  • Allow an inbox note to carry an optional correlation/reply descriptor without turning the note body into the full brief.
  • Persist immutable correlation data with the inbox record, including the originating request/note ID and a safe recipient identifier.
  • Let FirstMate publish a structured terminal result such as completed, failed, or needs-input.
  • Include artifact pointers and a concise summary; keep large output in durable files.
  • Deliver through an explicit adapter. Reuse the existing Hermes response/outbox lifecycle where appropriate rather than building an unaudited parallel remote transport.
  • Make result publication idempotent and restart-safe, with observable pending/delivered/failed state and retry behavior.
  • Fail closed for malformed recipients, unsafe paths, symlinks, and unauthorized cross-user/session delivery.

Acceptance Criteria

  • A local inbox handoff can optionally declare a supported reply target and correlation ID.
  • FirstMate can publish a structured result containing status, summary, and zero or more durable artifact references.
  • Result records are persisted before delivery is attempted.
  • Repeated publication or retry does not create duplicate user-visible replies.
  • Delivery state survives process restarts and exposes pending, delivered, and failed outcomes.
  • Hermes can receive the result in the originating session when the reply target is valid and supported.
  • Unsupported or malformed reply targets fail closed without losing the result record.
  • Existing inbox notes without reply metadata remain fully compatible.
  • The authenticated Hermes external bridge retains its allowlisting, authority, audit, correlation, and receipt guarantees.
  • Tests cover success, retry, duplicate publication, restart recovery, malformed input, unauthorized targets, and delivery failure.
  • Architecture and operator documentation explain the ingress/result flow and recovery procedure.

Out of Scope

  • Real-time conversational streaming between Hermes and FirstMate.
  • Replacing the authenticated Hermes Gateway bridge.
  • AWS Bedrock-dependent ask or say features.
  • Embedding large task outputs directly in wake messages or inbox notes.

Design Principle

The note is the doorbell. The file is the brief. The result envelope is the receipt.

Follow-up to #151.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions