Add Eve-compatible agent lifecycle hooks with Tilde-owned channels

[danielblignaut]

Outcome

Support Eve-shaped authored hooks for OpenBot agents, following the public Eve hooks guide where the runtime semantics can be honored.

Hooks observe typed agent lifecycle events for audit, metrics, alerts, cleanup, and integrations. Tilde owns channel ingress, delivery, and ChatKit history, so OpenBot must not pretend to support Eve channel adapters or expose a synthetic channel object with misleading guarantees.

Target layout

After the singular-agent migration in #19:

configuration/agent/
├── hooks/
│   ├── audit.ts
│   └── observability/metrics.ts
└── subagents/<id>/hooks/

During migration, the loader may recognize the current configuration/agents/<id>/hooks/ location only as part of the same atomic path transition; do not retain two indefinite layouts.

The path-relative filename is the stable hook slug: hooks/audit.ts becomes audit, and hooks/observability/metrics.ts becomes observability/metrics.

Proposed architecture

Typed authored contract

Expose defineHook, hook/event/context types, and result-narrowing helpers from an OpenBot-owned agent-runtime export. Each hook default-exports:

export default defineHook({
  events: {
    async "message.completed"(event, context) {},
    async "*"(event, context) {},
  },
});

• Recursively discover TypeScript hook files and reject duplicate/unsafe slugs or non-hook default exports.
• Use one versioned event envelope with a stable event ID, timestamp, agent/session/turn coordinates, type, and typed data.
• Run event-specific handlers before * handlers; ignore return values.
• Treat thrown hook errors as real runtime failures with a defined turn.failed/terminal cascade, while preventing infinite failure-hook recursion.
• Keep hooks trusted server code. They are not tools, are never model-selected, and cannot inject model context.

Event source and durability contract

Do not dispatch hooks independently from incidental AI SDK callbacks if that would produce a second, contradictory event vocabulary. The direct-agent/event-publication work in #25 should expose the canonical public event composer used by streaming, Tilde synchronization, and hooks.

Eve documents hooks as running after its durable event write. OpenBot can claim equivalent ordering only if the public Tilde event integration acknowledges durable acceptance before hook dispatch. Otherwise, document and type the weaker guarantee explicitly (for example, accepted rather than persisted) and include reconciliation metadata. Never say an event is durably stored based only on an in-process callback.

Hook delivery is at least once. Event IDs deduplicate storage/observation, while once-per-turn external side effects require an idempotency key derived from stable turn/step coordinates.

Tilde channel boundary

• Tilde remains the only channel owner for OpenBot conversations.
• Do not load channels/, channel adapter handlers, delivery methods, or continuation-token behavior from Eve.
• Hook context contains OpenBot agent identity, Tilde-owned session identity, scoped Computer access where permitted, and an explicit transport descriptor such as kind: "tilde-chatkit"; it does not expose channel.
• Channel-specific Tilde events stay behind the public Tilde integration and are not copied into OpenBot as private API knowledge.
• If a fork authors channels/, fail validation with an actionable explanation rather than silently ignoring it.

Subagent isolation

Coordinate with #15 and #19:

• primary-agent hooks observe primary-agent events only;
• subagent hooks observe only their subagent scope;
• parent hooks do not automatically receive subagent message/tool payloads;
• explicit aggregate observability consumes redacted event envelopes at a higher boundary rather than breaking capability isolation.

Security and operations

• Provide safe logging examples that emit IDs, event type, timing, and bounded metadata—not raw messages, tool outputs, credentials, browser data, or PII.
• Apply cancellation/deadlines to hooks and define timeout/concurrency limits so observability code cannot hang the turn indefinitely.
• Preserve deterministic registration order across local and Vercel bundles.
• Surface hook slug and redacted failure metadata in diagnostics.

Delivery slices

• Record supported semantics and deviations from Eve in ADR-0011, including the Tilde channel/durability boundary.
• Define the versioned event envelope, hook context, failure cascade, and idempotency guidance.
• Add recursive discovery, validation, registration, and deterministic ordering.
• Integrate dispatch with the canonical event composer from Stream directly from clients to agent endpoints and sync Tilde events asynchronously #25.
• Add primary/subagent isolation with Add capability-scoped subagents for computer and desktop work #15/Adopt a singular primary-agent layout with nested subagents #19.
• Add one safe default example hook and scaffold it only if it provides clear value.
• Update agent docs, AGENTS.md, initialization templates, and focused testing skills.

Acceptance criteria

• Recursive hook slugs, typed handlers, wildcard ordering, ignored returns, and deterministic registration work identically in local and Vercel agent builds.
• The documented durability word (persisted, accepted, or another explicit state) is proven by the public Tilde integration and failure/retry tests.
• A thrown hook produces the defined terminal failure exactly once without corrupting the canonical event stream.
• Replayed events and retried turns have documented at-least-once/idempotency behavior.
• channels/ fails validation and no channel adapter/token/delivery API is exposed by OpenBot.
• Primary and subagent hooks remain isolated.
• Cancellation, timeout, concurrent hooks, sensitive-payload handling, and bundle parity have focused integration tests.
• The default example and documentation do not log raw content, tool output, credentials, or PII.

Dependencies and open decisions

• Add capability-scoped subagents for computer and desktop work #15 capability-scoped subagents.
• Adopt a singular primary-agent layout with nested subagents #19 singular primary-agent layout and nested subagents.
• Build a concise integration/E2E suite and focused testing skills #20 concise integration/E2E suite and focused test skills.
• Stream directly from clients to agent endpoints and sync Tilde events asynchronously #25 canonical direct-agent event publication and its public durability acknowledgment.

Open decisions:

• The first supported event vocabulary and which events intentionally differ from Eve.
• Whether Tilde's public acknowledgment is strong enough for post-persistence dispatch.
• Sequential versus bounded-parallel execution across separate hooks; per-hook event order must remain deterministic.
• Hook timeout/failure policy for optional observability versus critical compliance hooks.