🌀
← Back to Articles & Artefacts
artefactseast

Hermes Kickoff — Tide / Upterm Agent Bridge Package Map

IAIP Research
axion-upterm-surveyspec-ai-native-terminal-multiplexer-integration-layer

Hermes Kickoff — Tide / Upterm Agent Bridge Package Map

Issue: miadisabelle/Etuaptmumk-RSM#232 Source survey: 01-perplexity-doc--upterm--AI-Native_Terminal_Multiplexer_Integration_Layer_Academic_Survey__Technical_Specification.md Created: 260610230208 UTC

Gist

The safest first slice is NOT a new package yet.

Start by tightening the schema seam in @miadi/tide-contract, then expose typed no-op / dry-run client verbs in @miadi/tide, then mirror the contract with Python models in IronSilk runtime/tide-runtime. Only create a new package if the Upterm relay/protocol implementation needs to be independently versioned after the contract stabilizes.

Live terminal check

Candidate tmux sessions inspected:

  • miadi-tide-cockpit-260601-80: shell handoff into mia, detached from another cockpit; no active agent work visible.
  • miadi-tide-cockpit-74: shell handoff into mia, detached from another cockpit; no active agent work visible.
  • miadi-tide-cockpit-bridgemind-inspired-82: completed Episode 033 checkpoint. It explicitly says it did not modify /src/Miadi, /usr/local/src/mightyeagle, or /usr/local/src/ironsilk and suggested contract/crosswalk work as next steps.
  • tide-terminal-workspace-orchestration-67: shell handoff into mia, detached from another cockpit; no active agent work visible.

Conclusion: no running terminal appears to be actively completing #232. This kickoff packet becomes the handoff/start marker.

Existing package surfaces

/src/Miadi/packages/tide-contract

Current state:

  • src/index.ts exports hand-written contract types.
  • schema/tide-api.schema.json is the planned source of truth.
  • Current contract covers context, health, terminal inventory, detect, peek, steer, send.

First #232 slice here:

  1. Add schema definitions for:
    • ceremonyContext
    • agentAccessLevel
    • uptermAgentContract
    • paneTopology
    • sessionStateSnapshot
    • hermesEventPayload
  2. Add matching TypeScript scaffold exports in src/index.ts until schema generation exists.
  3. Keep payloads intentionally transport-agnostic: contracts should not require a forked uptermd yet.

Suggested issue anchor if split out: Contract: add Upterm agent session and ceremony context schemas for Tide.

/src/Miadi/packages/tide

Current state:

  • Client boundary for Miadi → IronSilk tide runtime.
  • Stable verb surface; transport is internal.
  • Uses execFile argument arrays and daemon socket where possible.
  • Direct sendKeys exists for cockpit steering.

First #232 slice here:

  1. Add an upterm module that is initially dry-run / contract-first:
    • buildUptermHostPlan(input)
    • buildUptermJoinPlan(contract)
    • describeUptermBridge()
  2. Export the verbs from src/index.ts.
  3. Do not add network/session mutation until tide-contract has stable schemas and IronSilk has matching model fixtures.

Suggested issue anchor if split out: Client: add dry-run Upterm bridge planning verbs to @miadi/tide.

/usr/local/src/ironsilk/runtime/tide-runtime

Current state:

  • Python package published as ironsilk; CLI is tide.
  • Runtime state root is ~/.miadi/navigator with MIADI_HOME override.
  • Operator inventory/peek/steer/send/checkpoint/session store already exist.

First #232 slice here:

  1. Add pure data models first, likely in a new tide_runtime/upterm_models.py:
    • AgentAccessLevel
    • CeremonyContext
    • PaneTopology
    • UptermAgentContract
    • SessionStateSnapshot
  2. Add fixture JSON under tests for schema parity with @miadi/tide-contract.
  3. Add a read-only CLI stub only after models pass:
    • tide upterm plan-host --ceremony ... --agents ... --format json
    • tide upterm plan-join --contract ... --format json
  4. Do not implement actual Upterm process spawning, relay extension, or resurrection in this first slice.

Suggested issue anchor if split out: Runtime: add contract-parity Upterm bridge models and plan-only CLI.

/usr/local/src/ironsilk/runtime/tide-runtime-plugin

Current state:

  • Zellij plugin surface exists, but prior notes say cargo check has broader Zellij API drift.

First #232 slice here:

  • Do nothing in the first slice unless the schema needs a Zellij event fixture. Avoid coupling #232 to Rust plugin drift.

New package decision

Do NOT create a new package immediately.

Create a new package only when one of these becomes true:

  1. Upterm protocol/relay logic needs its own release cadence.
  2. Go/uptermd adapter code cannot live cleanly inside IronSilk Python runtime or Miadi TypeScript client.
  3. Security review requires isolating network-facing code from local cockpit/client packages.

If needed later, the likely package is:

  • /src/Miadi/packages/upterm-agent-bridge for TypeScript SDK / contract consumer; or
  • /usr/local/src/ironsilk/runtime/tide-upterm-bridge for Python/CLI runtime bridge.

Prefer exactly one of these, not both, after the first schema/model parity slice proves where the real boundary belongs.

First implementation order

  1. @miadi/tide-contract: schema + TS scaffold for Upterm/certemony/session snapshot contracts.
  2. IronSilk tide-runtime: Python models + fixture parity tests.
  3. @miadi/tide: dry-run planning verbs consuming the contract types.
  4. Later: actual Upterm host/join process control behind guarded runtime commands.
  5. Later: optional new package if network/security/release boundaries demand it.

Verification commands for the first slice

From /src/Miadi:

cd packages/tide-contract
npm test 2>/dev/null || npm run build

cd ../tide
npm test

From /usr/local/src/ironsilk/runtime/tide-runtime:

/home/jgi/anaconda3/envs/ironsilk/bin/python -m pytest tests/test_release_gate.py tests/test_terminal_inventory.py tests/test_terminal_send.py

After adding Python model parity tests, run the new focused test directly before wider tests.

Guardrails

  • Keep tide as the canonical CLI.
  • Keep state under MIADI_HOME / ~/.miadi/navigator, not ~/.hermes.
  • Keep .miadi/tide.yaml as the project-local config path; do not add root .tide.yaml.
  • Preserve know-before-entering: read-only / dry-run before mutation.
  • Do not weaken tide operator send --run guards.
  • Do not implement auto-resume or automatic session resurrection in slice one.
  • Avoid editing /src/Miadi until the target issue/branch is chosen, because that repo has many unrelated untracked files.