ambleloftHook events and registration API
Internal alpha.9 / M2 preview: declare completion events, register during activate and handle durable at-least-once delivery.
Browse contracts, signatures, fields and examples. Unspecified defaults are not inferred.
On this page
01Events and signature
Preview capability · SDK 0.1.0-alpha.9
Only these two events are supported. background.job.completed signals a terminal outcome, not necessarily success.
type TurnReference = { conversationId: string; turnId: string; version: number };
type HookEnvelope = { eventId: string; projectId: string; occurredAt: string } & (
| (TurnReference & { type: 'conversation.turn.completed' })
| { type: 'background.job.completed'; jobId: string; status: BackgroundJob['status'] }
);
// ExtensionContext
hooks.register(handler: string, callback: (event: HookEnvelope,
context: { signal: AbortSignal; projectId: string; requestId: string }
) => void | Promise<void>): Disposable;02Manifest and registration validation
The schema constrains event names and structure. CLI/host validation checks the main entry, project permissions, duplicate events and handler names. Hooks and operations share a unique handler namespace. Registration must match the declared name and happen synchronously during activate.
| Field / API | Contract |
|---|---|
| conversation.turn.completed | Produced after the complete tool loop and final reply; not a token stream or tool fragment. |
| background.job.completed | Use jobId with jobs.get for authoritative results and handle all terminal states. |
| Disposable | Add registration disposables to context.subscriptions for cleanup. |
03ACK, retries and ordering
Successful handler return is the ACK. Delivery is at least once; eventId can repeat. Handlers have 30 seconds, with up to five host retries after the first failure. A conversation waits for its preceding pending/delivering attempt; dead letters do not block later events. There is no cross-conversation global ordering. Make business effects idempotent. ACK does not prove job or business success. These durable Hooks are separate from ordinary notification listeners.
04Retention and unsupported capabilities
Snapshots and unacknowledged events are retained for seven days, with a 1,000-event capacity per extension. Revocation, disabling and uninstalling clear corresponding events; reauthorization does not backfill history. Live message streams, arbitrary lifecycle events, chat interception and response editing are not exposed.