@agent-relay/harness-driver 7.1.1

package/dist/lifecycle-hooks.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Typed lifecycle-hook surface for the managed driver client.
+ *
+ * Two kinds of events flow through the same registry:
+ *
+ * 1. **Broker events** — `agentSpawned`, `agentReleased`, `agentExited`,
+ *    `agentReady`, `agentIdle`, `agentExitRequested`,
+ *    `agentActivityChanged`, `agentResult`, `messageReceived`,
+ *    `messageSent`, `workerOutput`, `deliveryUpdate`, `channelSubscribed`,
+ *    `channelUnsubscribed`. These fire when the broker emits the
+ *    corresponding event over the WS stream.
+ * 2. **Call-site hooks** — `beforeAgentSpawn`, `afterAgentSpawn`,
+ *    `beforeAgentRelease`, `afterAgentRelease`. These fire at the SDK
+ *    call site (before / after the HTTP request), so handlers can
+ *    observe — and, for `beforeAgentSpawn`, *modify* — the spawn input
+ *    before it reaches the broker.
+ *
+ * The `beforeAgentSpawn` contract is the only one that supports
+ * mutation: handlers may return a {@link SpawnPatch} to merge into the
+ * input via shallow merge in registration order. All other hooks are
+ * observe-only — return type `void | Promise<void>`.
+ *
+ */
+import type { AgentRuntime, BrokerEvent, MessageInjectionMode } from './protocol.js';
+import type { SpawnAgentResult, SpawnCliInput, SpawnPtyInput } from './types.js';
+type SpawnInput = SpawnPtyInput | SpawnCliInput;
+/**
+ * The subset of {@link SpawnPtyInput} / {@link SpawnCliInput} fields a
+ * `beforeAgentSpawn` handler may patch. Keeping this narrower than the full
+ * input type stops handlers from rewriting identity (`name`, `cli`,
+ * `cwd`) — those need to come from the caller.
+ *
+ * For array fields (`args`, `channels`) a patch *replaces* the array. To
+ * extend rather than replace, spread the current value:
+ *
+ * ```ts
+ * relay.addListener('beforeAgentSpawn', (ctx) => ({
+ *   args: [...(ctx.input.args ?? []), '--session-id', uuid],
+ * }));
+ * ```
+ *
+ * When multiple handlers return patches, allowed patch fields merge in
+ * registration order; later handlers override earlier ones for the same key.
+ */
+export type SpawnPatch = Partial<Pick<SpawnPtyInput & SpawnCliInput, 'args' | 'channels' | 'task' | 'model' | 'team' | 'agentToken' | 'harnessConfig'>>;
+export interface BeforeAgentSpawnContext<TInput extends SpawnInput = SpawnInput> {
+    /** Which spawn API was called. */
+    kind: 'pty' | 'cli' | 'headless';
+    /** Raw input the caller passed in. Treat as read-only — return a {@link SpawnPatch} to modify. */
+    input: Readonly<TInput>;
+    /** `process.pid` of the calling Node process. Useful for burn-style stamping. */
+    spawnerPid: number;
+    /** ISO timestamp captured the instant the hook chain started. */
+    spawnStartTs: string;
+    /** Resolved broker base URL the spawn will POST to. */
+    baseUrl: string;
+}
+export type BeforeAgentSpawnHandler = (ctx: BeforeAgentSpawnContext) => void | SpawnPatch | Promise<void | SpawnPatch>;
+export interface AfterAgentSpawnContext<TInput extends SpawnInput = SpawnInput> extends BeforeAgentSpawnContext<TInput> {
+    /** Final input that was sent to the broker — original input merged with every handler's patch. */
+    resolvedInput: TInput;
+    /** Broker reply on success. */
+    result?: SpawnAgentResult;
+    /** Set when the broker call rejected. Mutually exclusive with `result`. */
+    error?: Error;
+    /** Wall-clock duration from `beforeAgentSpawn` start to here. */
+    durationMs: number;
+}
+export interface BeforeAgentReleaseContext {
+    name: string;
+    reason?: string;
+    baseUrl: string;
+}
+export interface AfterAgentReleaseContext extends BeforeAgentReleaseContext {
+    error?: Error;
+    durationMs: number;
+}
+export interface AgentIdlePayload {
+    name: string;
+    idleSecs: number;
+}
+export interface AgentExitRequestedPayload {
+    name: string;
+    reason: string;
+}
+export interface WorkerOutputPayload {
+    name: string;
+    stream: string;
+    chunk: string;
+}
+/**
+ * Object-shaped payload for channel subscribe / unsubscribe events. The
+ * pre-2.x single-callback fields took two positional args
+ * (`(agent, channels) => void`); the registry standardizes on an object
+ * payload so all events share the one-arg shape and future fields can be
+ * added without breaking handlers.
+ */
+export interface ChannelSubscriptionPayload {
+    agent: string;
+    channels: string[];
+}
+export interface DriverMessage {
+    eventId: string;
+    from: string;
+    to: string;
+    text: string;
+    threadId?: string;
+    data?: Record<string, unknown>;
+    mode?: MessageInjectionMode;
+}
+export interface DriverAgent {
+    readonly name: string;
+    readonly runtime: AgentRuntime;
+    readonly channels: string[];
+    readonly sessionId?: string;
+    readonly pid?: number;
+    readonly status?: string;
+}
+export interface DriverAgentResult<T = unknown> {
+    name: string;
+    resultId: string;
+    final: boolean;
+    data: T;
+    metadata?: unknown;
+}
+export type DriverAgentActivityReason = 'delivery_queued' | 'delivery_injected' | 'delivery_active' | 'delivery_ack' | 'delivery_failed' | 'message_delivery_confirmed' | 'message_delivery_failed' | 'relay_inbound' | 'agent_idle' | 'agent_exited' | 'agent_released';
+export interface DriverAgentActivityChange {
+    name: string;
+    active: boolean;
+    pendingDeliveries: number;
+    reason: DriverAgentActivityReason;
+    eventId?: string;
+}
+/**
+ * Typed event map consumed by the {@link EventBus} that backs
+ * `AgentRelay.addListener` / `removeListener`.
+ *
+ * Each entry's tuple is the handler argument list (always length 1 here —
+ * payloads are objects rather than positional args).
+ *
+ * Declared as a `type` alias rather than an `interface` so it satisfies
+ * the `EventBus<E extends EventMap>` constraint without requiring callers
+ * to spell out an index signature.
+ */
+export type HarnessDriverEvents = {
+    messageReceived: [DriverMessage];
+    messageSent: [DriverMessage];
+    agentSpawned: [DriverAgent];
+    agentReleased: [DriverAgent];
+    agentExited: [DriverAgent];
+    agentReady: [DriverAgent];
+    workerOutput: [WorkerOutputPayload];
+    deliveryUpdate: [BrokerEvent];
+    agentExitRequested: [AgentExitRequestedPayload];
+    agentIdle: [AgentIdlePayload];
+    agentResult: [DriverAgentResult];
+    agentActivityChanged: [DriverAgentActivityChange];
+    channelSubscribed: [ChannelSubscriptionPayload];
+    channelUnsubscribed: [ChannelSubscriptionPayload];
+    beforeAgentSpawn: [BeforeAgentSpawnContext];
+    afterAgentSpawn: [AfterAgentSpawnContext];
+    beforeAgentRelease: [BeforeAgentReleaseContext];
+    afterAgentRelease: [AfterAgentReleaseContext];
+};
+export {};
+//# sourceMappingURL=lifecycle-hooks.d.ts.map

package/dist/lifecycle-hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-hooks.d.ts","sourceRoot":"","sources":["../src/lifecycle-hooks.ts"],"names":[],"mappings":"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"}

package/dist/lifecycle-hooks.js

@@ -0,0 +1,25 @@
+/**
+ * Typed lifecycle-hook surface for the managed driver client.
+ *
+ * Two kinds of events flow through the same registry:
+ *
+ * 1. **Broker events** — `agentSpawned`, `agentReleased`, `agentExited`,
+ *    `agentReady`, `agentIdle`, `agentExitRequested`,
+ *    `agentActivityChanged`, `agentResult`, `messageReceived`,
+ *    `messageSent`, `workerOutput`, `deliveryUpdate`, `channelSubscribed`,
+ *    `channelUnsubscribed`. These fire when the broker emits the
+ *    corresponding event over the WS stream.
+ * 2. **Call-site hooks** — `beforeAgentSpawn`, `afterAgentSpawn`,
+ *    `beforeAgentRelease`, `afterAgentRelease`. These fire at the SDK
+ *    call site (before / after the HTTP request), so handlers can
+ *    observe — and, for `beforeAgentSpawn`, *modify* — the spawn input
+ *    before it reaches the broker.
+ *
+ * The `beforeAgentSpawn` contract is the only one that supports
+ * mutation: handlers may return a {@link SpawnPatch} to merge into the
+ * input via shallow merge in registration order. All other hooks are
+ * observe-only — return type `void | Promise<void>`.
+ *
+ */
+export {};
+//# sourceMappingURL=lifecycle-hooks.js.map

package/dist/lifecycle-hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-hooks.js","sourceRoot":"","sources":["../src/lifecycle-hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG"}