@ap3x/observe 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AP3X
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,27 @@
+# @ap3x/observe
+
+Observability for agent and swarm runs: a hook engine plus typed event seams over `@ap3x/agent-core` and `@ap3x/swarms`.
+
+Part of [AP3X](https://github.com/AP3X-Dev/AP3X) — a TypeScript multi-agent framework.
+
+## Install
+
+```bash
+npm install @ap3x/observe
+```
+
+## What's inside
+
+- **Hook engine** — configurable lifecycle hooks with validation, fail-open/fail-closed modes, and dry-run support.
+- **Swarm bridge** — bridges hooks onto swarm control seams (delegation gates, member run brackets).
+- **Events** — typed run, member, and tool events suitable for tracing or metrics.
+
+For OpenTelemetry export, see [`@ap3x/observe-otel`](https://www.npmjs.com/package/@ap3x/observe-otel).
+
+## Documentation
+
+See the [AP3X repository](https://github.com/AP3X-Dev/AP3X) for architecture notes, the full package map, and examples.
+
+## License
+
+MIT

package/dist/envelope.d.ts

@@ -0,0 +1,43 @@
+import type { Usage } from "@ap3x/ai";
+export type TraceSource = "agent" | "swarm" | "tool" | "hook";
+export interface TraceEvent {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    /** Monotonic per trace, assigned by the pipeline, starts at 1. */
+    seq: number;
+    /** Epoch milliseconds. */
+    ts: number;
+    source: TraceSource;
+    name: string;
+    agent?: {
+        name?: string;
+        model?: string;
+    };
+    usage?: Usage;
+    data?: unknown;
+}
+/** Everything the emitter provides; the pipeline stamps ids, seq, and ts. */
+export interface TraceEventInput {
+    source: TraceSource;
+    name: string;
+    agent?: {
+        name?: string;
+        model?: string;
+    };
+    usage?: Usage;
+    data?: unknown;
+}
+export interface TraceContext {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+}
+export declare function newTraceContext(): TraceContext;
+/** Child of `parent`, else of the ambient context, else a fresh root. */
+export declare function childContext(parent?: TraceContext): TraceContext;
+export declare function currentTraceContext(): TraceContext | undefined;
+export declare function runInTrace<T>(ctx: TraceContext, fn: () => T): T;
+/** Runs fn one span deeper than the ambient context. */
+export declare function withSpan<T>(fn: () => T): T;
+//# sourceMappingURL=envelope.d.ts.map

package/dist/envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../src/envelope.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAEtC,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AAE9D,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,GAAG,EAAE,MAAM,CAAC;IACZ,0BAA0B;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,WAAW,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1C,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,6EAA6E;AAC7E,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,WAAW,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1C,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAID,wBAAgB,eAAe,IAAI,YAAY,CAE9C;AAED,yEAAyE;AACzE,wBAAgB,YAAY,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,YAAY,CAIhE;AAED,wBAAgB,mBAAmB,IAAI,YAAY,GAAG,SAAS,CAE9D;AAED,wBAAgB,UAAU,CAAC,CAAC,EAAE,GAAG,EAAE,YAAY,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAE/D;AAED,wDAAwD;AACxD,wBAAgB,QAAQ,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAE1C"}

package/dist/exporter.d.ts

@@ -0,0 +1,9 @@
+import type { TraceSink } from "./pipeline";
+/**
+ * A TraceSink with a flush barrier. Backends (e.g. OpenTelemetry) implement this
+ * in their own packages so @ap3x/observe stays free of third-party dependencies.
+ */
+export interface Exporter extends TraceSink {
+    flush(): Promise<void>;
+}
+//# sourceMappingURL=exporter.d.ts.map

package/dist/exporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exporter.d.ts","sourceRoot":"","sources":["../src/exporter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C;;;GAGG;AACH,MAAM,WAAW,QAAS,SAAQ,SAAS;IACzC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB"}

package/dist/hooks/agent-bridge.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Bridges a HookEngine onto agent-core's existing AgentHooks seams:
+ *   PreToolUse  -> beforeToolCall   (block / re-validated arg rewrite)
+ *   PostToolUse -> afterToolCall    (field-by-field result override)
+ *   RunStart    -> first steering consult of a run (inject messages)
+ *   TurnStart   -> every steering consult          (inject messages)
+ *   Stop        -> getFollowUpMessages             (force continuation)
+ *   PreCompact  -> beforeCompaction                (defer)
+ */
+import type { AgentHooks, AgentMessage } from "@ap3x/agent-core";
+import type { HookEngine } from "./engine";
+export declare function userMessage(content: string): AgentMessage;
+export type HookAgentHooks = AgentHooks & {
+    /**
+     * Re-arm RunStart for the next run. Self-arms when a Stop consult ends the
+     * run un-extended; call this explicitly when a run ends on error/abort
+     * (those stops never consult getFollowUpMessages).
+     */
+    reset(): void;
+};
+export declare function createHookAgentHooks(engine: HookEngine): HookAgentHooks;
+//# sourceMappingURL=agent-bridge.d.ts.map

package/dist/hooks/agent-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-bridge.d.ts","sourceRoot":"","sources":["../../src/hooks/agent-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAiC,MAAM,kBAAkB,CAAC;AAChG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE3C,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,CAEzD;AAED,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG;IACxC;;;;OAIG;IACH,KAAK,IAAI,IAAI,CAAC;CACf,CAAC;AAEF,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,UAAU,GAAG,cAAc,CAwFvE"}

package/dist/hooks/config.d.ts

@@ -0,0 +1,34 @@
+/**
+ * hooks.json loader. Trust boundary: the file is user-authored JSON, so it is
+ * schema-validated (TypeBox via @ap3x/ai — no new dependency) and malformed
+ * config fails LOUDLY at load time (file + detail), never mid-run.
+ *
+ * File shape: { "hooks": [ { "event", "matcher"?, "command", "timeout"?,
+ * "failMode"?, "name"? } ] }
+ */
+import { type Static } from "@ap3x/ai";
+import { type Hook, type HookEventName } from "./types";
+declare const THookEntry: import("@sinclair/typebox").TObject<{
+    event: import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<HookEventName>[]>;
+    matcher: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    command: import("@sinclair/typebox").TString;
+    timeout: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    failMode: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"open">, import("@sinclair/typebox").TLiteral<"closed">]>>;
+    name: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>;
+export type ShellHookEntry = Static<typeof THookEntry>;
+export declare class HookConfigError extends Error {
+    readonly file: string;
+    constructor(file: string, detail: string);
+}
+export declare function parseHooksFile(file: string, content: string): ShellHookEntry[];
+export interface LoadedHookConfig {
+    file: string;
+    entries: ShellHookEntry[];
+}
+/** Reads each path; missing files are skipped, malformed ones throw HookConfigError. */
+export declare function loadHooksFiles(paths: string[]): LoadedHookConfig[];
+/** Turn validated config rows into engine-registrable shell hooks. */
+export declare function hooksFromEntries(entries: ShellHookEntry[]): Hook[];
+export {};
+//# sourceMappingURL=config.d.ts.map

package/dist/hooks/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/hooks/config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,KAAK,MAAM,EAA0C,MAAM,UAAU,CAAC;AAG/E,OAAO,EAAoB,KAAK,IAAI,EAAE,KAAK,aAAa,EAAE,MAAM,SAAS,CAAC;AAE1E,QAAA,MAAM,UAAU;;;;;;;EAOd,CAAC;AAKH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,OAAO,UAAU,CAAC,CAAC;AAEvD,qBAAa,eAAgB,SAAQ,KAAK;IAEtC,QAAQ,CAAC,IAAI,EAAE,MAAM;gBAAZ,IAAI,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM;CAKjB;AAqBD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAW9E;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,cAAc,EAAE,CAAC;CAC3B;AAED,wFAAwF;AACxF,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,gBAAgB,EAAE,CAkBlE;AASD,sEAAsE;AACtE,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,cAAc,EAAE,GAAG,IAAI,EAAE,CAiBlE"}

package/dist/hooks/engine.d.ts

@@ -0,0 +1,39 @@
+import type { TracePipeline } from "../pipeline";
+import type { Hook, HookDecisionMap, HookEventName, HookPayloadMap } from "./types";
+export declare const DEFAULT_GATING_TIMEOUT_MS = 10000;
+export declare const DEFAULT_HOOK_TIMEOUT_MS = 30000;
+export declare class HookTimeoutError extends Error {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+/** Glob with `*` as the only wildcard, anchored at both ends. */
+export declare function globMatch(pattern: string, value: string): boolean;
+export interface HookOutcome<E extends HookEventName> {
+    /** One entry per matching hook that returned a decision, in registration order. */
+    decisions: Array<HookDecisionMap[E]>;
+    /** True when a failed hook had failMode "closed" — the gated action must be blocked. */
+    failedClosed: boolean;
+    /** Human-readable reason from the first fail-closed hook. */
+    failReason?: string;
+}
+export interface HookEngineOptions {
+    /** Hook executions/failures are emitted here as `source: "hook"` trace events. */
+    pipeline?: TracePipeline;
+}
+type StoredHook = Hook<HookEventName>;
+/**
+ * Registry + executor for hooks. Hooks run sequentially in registration
+ * order; a fail-closed hook error short-circuits (the action is blocked
+ * regardless of later hooks). `run` never rejects.
+ */
+export declare class HookEngine {
+    #private;
+    constructor(options?: HookEngineOptions);
+    register<E extends HookEventName>(hook: Hook<E>): () => void;
+    list(): readonly StoredHook[];
+    /** Cheap pre-check so bridges can skip work when nothing listens. */
+    hasHooks(event: HookEventName): boolean;
+    run<E extends HookEventName>(event: E, payload: HookPayloadMap[E], matchValue?: string): Promise<HookOutcome<E>>;
+}
+export {};
+//# sourceMappingURL=engine.d.ts.map

package/dist/hooks/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/hooks/engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAY,IAAI,EAAE,eAAe,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAS9F,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAChD,eAAO,MAAM,uBAAuB,QAAS,CAAC;AAE9C,qBAAa,gBAAiB,SAAQ,KAAK;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM;gBAAjB,SAAS,EAAE,MAAM;CAIvC;AAMD,iEAAiE;AACjE,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAGjE;AAgBD,MAAM,WAAW,WAAW,CAAC,CAAC,SAAS,aAAa;IAClD,mFAAmF;IACnF,SAAS,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC;IACrC,wFAAwF;IACxF,YAAY,EAAE,OAAO,CAAC;IACtB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC,kFAAkF;IAClF,QAAQ,CAAC,EAAE,aAAa,CAAC;CAC1B;AAED,KAAK,UAAU,GAAG,IAAI,CAAC,aAAa,CAAC,CAAC;AAEtC;;;;GAIG;AACH,qBAAa,UAAU;;gBAIT,OAAO,CAAC,EAAE,iBAAiB;IAIvC,QAAQ,CAAC,CAAC,SAAS,aAAa,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI;IAS5D,IAAI,IAAI,SAAS,UAAU,EAAE;IAI7B,qEAAqE;IACrE,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO;IAIjC,GAAG,CAAC,CAAC,SAAS,aAAa,EAC/B,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,EAC1B,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;CAsD3B"}

package/dist/hooks/shell.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Shell-command hook type. Protocol (spec, verbatim): event payload as JSON on
+ * stdin; exit 0 = allow (optional stdout JSON decision); exit 2 = block,
+ * stderr is the reason; any other exit = hook error routed to failMode.
+ * Non-JSON stdout = no decision (the exit code governs).
+ */
+import type { HookDecisionMap, HookEventName } from "./types";
+export declare class HookExecutionError extends Error {
+    constructor(message: string);
+}
+export interface ShellHookResult {
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+}
+/** Never rejects; spawn failures surface as exitCode null + stderr. */
+export declare function runShellHook(command: string, payloadJson: string, timeoutMs: number): Promise<ShellHookResult>;
+/** Map one settled shell execution onto the event's decision shape. */
+export declare function shellDecision<E extends HookEventName>(event: E, result: ShellHookResult): HookDecisionMap[E] | undefined;
+//# sourceMappingURL=shell.d.ts.map

package/dist/hooks/shell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell.d.ts","sourceRoot":"","sources":["../../src/hooks/shell.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE9D,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,uEAAuE;AACvE,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,eAAe,CAAC,CA0C1B;AA8DD,uEAAuE;AACvE,wBAAgB,aAAa,CAAC,CAAC,SAAS,aAAa,EACnD,KAAK,EAAE,CAAC,EACR,MAAM,EAAE,eAAe,GACtB,eAAe,CAAC,CAAC,CAAC,GAAG,SAAS,CAiEhC"}

package/dist/hooks/swarm-bridge.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Bridges a HookEngine onto the swarms control seams:
+ *   SubagentStart -> delegation gate (block a delegation before it runs)
+ *   SubagentStop  -> member_run_end events (observe-only, fire-and-forget)
+ */
+import type { HookEngine } from "./engine";
+/**
+ * The delegation gate is a single process-global slot (last caller wins):
+ * attach ONE engine at a time, and detach it before attaching another —
+ * a stale detacher clears whichever gate is currently installed.
+ */
+export declare function attachSwarmHooks(engine: HookEngine): () => void;
+//# sourceMappingURL=swarm-bridge.d.ts.map

package/dist/hooks/swarm-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"swarm-bridge.d.ts","sourceRoot":"","sources":["../../src/hooks/swarm-bridge.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE3C;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,IAAI,CA4C/D"}

package/dist/hooks/types.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Hook contract (observability spec P2). Full control parity: every hook
+ * point can block, rewrite, or force continuation — not merely observe.
+ * Payload/decision shapes are per-event; the engine stays generic and each
+ * bridge does its own event-specific decision merging.
+ */
+import type { AgentMessage, AgentToolResult } from "@ap3x/agent-core";
+export type HookEventName = "PreToolUse" | "PostToolUse" | "RunStart" | "TurnStart" | "Stop" | "PreCompact" | "SubagentStart" | "SubagentStop";
+export declare const HOOK_EVENT_NAMES: readonly HookEventName[];
+export interface PreToolUsePayload {
+    toolName: string;
+    toolCallId: string;
+    args: Record<string, unknown>;
+}
+export interface PostToolUsePayload {
+    toolName: string;
+    toolCallId: string;
+    args: Record<string, unknown>;
+    result: AgentToolResult;
+    isError: boolean;
+}
+/** RunStart fires with turn 0; TurnStart/Stop carry the current turn index. */
+export interface TurnPayload {
+    turn: number;
+}
+export interface SubagentStartPayload {
+    agentName?: string;
+    mechanism: string;
+    depth: number;
+    task: string;
+}
+export interface SubagentStopPayload {
+    agentName: string;
+    mechanism: string;
+    depth: number;
+    durationMs: number;
+    isError: boolean;
+}
+export interface HookPayloadMap {
+    PreToolUse: PreToolUsePayload;
+    PostToolUse: PostToolUsePayload;
+    RunStart: TurnPayload;
+    TurnStart: TurnPayload;
+    Stop: TurnPayload;
+    PreCompact: Record<string, never>;
+    SubagentStart: SubagentStartPayload;
+    SubagentStop: SubagentStopPayload;
+}
+export interface PreToolUseDecision {
+    block?: boolean;
+    reason?: string;
+    /** Replacement args; re-validated against the tool schema by agent-core. */
+    updatedArgs?: Record<string, unknown>;
+}
+export interface PostToolUseDecision {
+    /** Field-by-field override of the tool result (redaction, replacement). */
+    override?: Partial<AgentToolResult>;
+}
+export interface InjectDecision {
+    /** Messages injected into the working context before the next turn. */
+    messages?: AgentMessage[];
+}
+export interface StopDecision {
+    /** Force the run to continue with `messages` as the next user turn. */
+    continue?: boolean;
+    messages?: AgentMessage[];
+}
+export interface PreCompactDecision {
+    /** Skip launching a compaction this turn; re-consulted next turn. */
+    defer?: boolean;
+}
+export interface SubagentStartDecision {
+    block?: boolean;
+    reason?: string;
+}
+export interface HookDecisionMap {
+    PreToolUse: PreToolUseDecision;
+    PostToolUse: PostToolUseDecision;
+    RunStart: InjectDecision;
+    TurnStart: InjectDecision;
+    Stop: StopDecision;
+    PreCompact: PreCompactDecision;
+    SubagentStart: SubagentStartDecision;
+    /** Observe-only: the member run already ended; nothing to control. */
+    SubagentStop: Record<string, never>;
+}
+/** What a hook timeout/crash means: "open" = proceed as if allowed (default), "closed" = block the gated action. */
+export type FailMode = "open" | "closed";
+export interface Hook<E extends HookEventName = HookEventName> {
+    event: E;
+    /**
+     * Glob (`*` wildcard) matched against the tool name (PreToolUse/PostToolUse)
+     * or agent name (SubagentStart/SubagentStop). Ignored at events with no
+     * match value. Absent = match everything.
+     */
+    matcher?: string;
+    /** Milliseconds. Default: 10s at gating points, 30s at others. */
+    timeout?: number;
+    /** Default "open". */
+    failMode?: FailMode;
+    /** Display label for traces and `ap3x hooks list`. */
+    name?: string;
+    handler: (payload: HookPayloadMap[E]) => HookDecisionMap[E] | undefined | Promise<HookDecisionMap[E] | undefined>;
+}
+/** Identity helper that pins the event's payload/decision types. */
+export declare function defineHook<E extends HookEventName>(hook: Hook<E>): Hook<E>;
+//# sourceMappingURL=types.d.ts.map

package/dist/hooks/types.d.ts.map

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

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export { type TraceSource, type TraceEvent, type TraceEventInput, type TraceContext, newTraceContext, childContext, currentTraceContext, runInTrace, withSpan, } from "./envelope";
+export { type TraceSink, type TracePipelineOptions, TracePipeline, } from "./pipeline";
+export { type TraceWriterOptions, TraceWriter, } from "./trace-writer";
+export { parseTraceFile, summarizeTrace, type ParsedTrace, type TraceHeader, type TraceFooter, type TraceSummary, type ToolStats, } from "./trace-file";
+export { type QueuedSinkOptions, QueuedSink, } from "./queued-sink";
+export type { Exporter } from "./exporter";
+export { type AgentEventSource, type ObserveAgentOptions, observeAgent, } from "./taps/agent";
+export { observeSwarms, enableDelegationSpans } from "./taps/swarm";
+export { type HookEventName, HOOK_EVENT_NAMES, type HookPayloadMap, type HookDecisionMap, type PreToolUsePayload, type PostToolUsePayload, type TurnPayload, type SubagentStartPayload, type SubagentStopPayload, type PreToolUseDecision, type PostToolUseDecision, type InjectDecision, type StopDecision, type PreCompactDecision, type SubagentStartDecision, type FailMode, type Hook, defineHook, } from "./hooks/types";
+export { DEFAULT_GATING_TIMEOUT_MS, DEFAULT_HOOK_TIMEOUT_MS, HookTimeoutError, globMatch, type HookOutcome, type HookEngineOptions, HookEngine, } from "./hooks/engine";
+export { type HookAgentHooks, createHookAgentHooks, userMessage, } from "./hooks/agent-bridge";
+export { attachSwarmHooks } from "./hooks/swarm-bridge";
+export { type ShellHookResult, HookExecutionError, runShellHook, shellDecision, } from "./hooks/shell";
+export { type ShellHookEntry, type LoadedHookConfig, HookConfigError, parseHooksFile, loadHooksFiles, hooksFromEntries, } from "./hooks/config";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,eAAe,EACf,YAAY,EACZ,mBAAmB,EACnB,UAAU,EACV,QAAQ,GACT,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,KAAK,SAAS,EACd,KAAK,oBAAoB,EACzB,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,KAAK,kBAAkB,EACvB,WAAW,GACZ,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,cAAc,EACd,cAAc,EACd,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,SAAS,GACf,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,KAAK,iBAAiB,EACtB,UAAU,GACX,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,YAAY,GACb,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AACpE,OAAO,EACL,KAAK,aAAa,EAClB,gBAAgB,EAChB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,WAAW,EAChB,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,QAAQ,EACb,KAAK,IAAI,EACT,UAAU,GACX,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,yBAAyB,EACzB,uBAAuB,EACvB,gBAAgB,EAChB,SAAS,EACT,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,UAAU,GACX,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,KAAK,cAAc,EACnB,oBAAoB,EACpB,WAAW,GACZ,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EACL,KAAK,eAAe,EACpB,kBAAkB,EAClB,YAAY,EACZ,aAAa,GACd,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,eAAe,EACf,cAAc,EACd,cAAc,EACd,gBAAgB,GACjB,MAAM,gBAAgB,CAAC"}