general-agent-runtime 0.0.1

package/dist/context/types.d.ts

@@ -0,0 +1,72 @@
+import type { ModelCapabilities } from "../model/index.js";
+import type { AgentMessage, ContextItemId, Metadata, RunId, SessionId, TurnId } from "../types/index.js";
+export type ContextScope = "system" | "project" | "user" | "dynamic" | "session";
+export type ContextVisibility = "model" | "runtime" | "both";
+export interface ContextItem {
+    id: ContextItemId;
+    scope: ContextScope;
+    source: string;
+    priority: number;
+    visibility: ContextVisibility;
+    content: readonly AgentMessage[];
+    createdAt: string;
+    expiresAt?: string;
+    metadata?: Metadata;
+}
+export interface ContextLoadRequest {
+    sessionId: SessionId;
+    runId: RunId;
+    turnId: TurnId;
+}
+export type ContextMutation = {
+    type: "add";
+    item: ContextItem;
+} | {
+    type: "replace";
+    id: ContextItemId;
+    item: ContextItem;
+} | {
+    type: "remove";
+    id: ContextItemId;
+} | {
+    type: "clear_scope";
+    scope: ContextScope;
+};
+export interface ContextSnapshot {
+    readonly sessionId: SessionId;
+    readonly runId: RunId;
+    readonly turnId: TurnId;
+    readonly items: readonly ContextItem[];
+    readonly createdAt: string;
+}
+export interface ProjectionRequest {
+    snapshot: ContextSnapshot;
+    model: string;
+    capabilities: ModelCapabilities;
+}
+export interface ProjectionStats {
+    estimatedTokensBefore: number;
+    estimatedTokensAfter: number;
+    removedItems: number;
+    deduplicatedMessages: number;
+}
+export interface ProjectionResult {
+    messages: readonly AgentMessage[];
+    stats: ProjectionStats;
+}
+export interface ProjectionStageContext {
+    model: string;
+    capabilities: ModelCapabilities;
+}
+export interface ProjectionStage {
+    readonly id: string;
+    readonly order: number;
+    apply(messages: readonly AgentMessage[], context: ProjectionStageContext, signal?: AbortSignal): Promise<readonly AgentMessage[]>;
+}
+export interface TokenEstimator {
+    estimate(messages: readonly AgentMessage[]): number;
+}
+export interface ContextManager {
+    snapshot(request: ContextLoadRequest, signal?: AbortSignal): Promise<ContextSnapshot>;
+    project(request: ProjectionRequest, signal?: AbortSignal): Promise<ProjectionResult>;
+}

package/dist/context/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/context/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/context/types.ts"],"names":[],"mappings":""}

package/dist/errors/codes.d.ts

@@ -0,0 +1 @@
+export type { ErrorCategory, RuntimeErrorCode, } from "../types/error.js";

package/dist/errors/codes.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=codes.js.map

package/dist/errors/codes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codes.js","sourceRoot":"","sources":["../../src/errors/codes.ts"],"names":[],"mappings":""}

package/dist/errors/index.d.ts

@@ -0,0 +1,4 @@
+export type * from "./codes.js";
+export * from "./runtime-error.js";
+export * from "./normalize.js";
+export * from "./serialize.js";

package/dist/errors/index.js

@@ -0,0 +1,4 @@
+export * from "./runtime-error.js";
+export * from "./normalize.js";
+export * from "./serialize.js";
+//# sourceMappingURL=index.js.map

package/dist/errors/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AACA,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC"}

package/dist/errors/normalize.d.ts

@@ -0,0 +1,2 @@
+import { RuntimeError } from "./runtime-error.js";
+export declare function normalizeUnknownError(error: unknown): RuntimeError;

package/dist/errors/normalize.js

@@ -0,0 +1,32 @@
+import { RuntimeError } from "./runtime-error.js";
+export function normalizeUnknownError(error) {
+    if (error instanceof RuntimeError) {
+        return error;
+    }
+    if (isAbortError(error)) {
+        return new RuntimeError({
+            code: "ABORTED",
+            category: "abort",
+            message: "Operation aborted",
+            cause: error,
+        });
+    }
+    if (error instanceof Error) {
+        return new RuntimeError({
+            code: "INTERNAL",
+            category: "internal",
+            message: error.message,
+            cause: error,
+        });
+    }
+    return new RuntimeError({
+        code: "INTERNAL",
+        category: "internal",
+        message: typeof error === "string" ? error : "Unknown runtime error",
+        cause: error,
+    });
+}
+function isAbortError(error) {
+    return (error instanceof DOMException && error.name === "AbortError") || (error instanceof Error && error.name === "AbortError");
+}
+//# sourceMappingURL=normalize.js.map

package/dist/errors/normalize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.js","sourceRoot":"","sources":["../../src/errors/normalize.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,MAAM,UAAU,qBAAqB,CAAC,KAAc;IAClD,IAAI,KAAK,YAAY,YAAY,EAAE,CAAC;QAClC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,IAAI,YAAY,CAAC;YACtB,IAAI,EAAE,SAAS;YACf,QAAQ,EAAE,OAAO;YACjB,OAAO,EAAE,mBAAmB;YAC5B,KAAK,EAAE,KAAK;SACb,CAAC,CAAC;IACL,CAAC;IAED,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,OAAO,IAAI,YAAY,CAAC;YACtB,IAAI,EAAE,UAAU;YAChB,QAAQ,EAAE,UAAU;YACpB,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,KAAK,EAAE,KAAK;SACb,CAAC,CAAC;IACL,CAAC;IAED,OAAO,IAAI,YAAY,CAAC;QACtB,IAAI,EAAE,UAAU;QAChB,QAAQ,EAAE,UAAU;QACpB,OAAO,EAAE,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,uBAAuB;QACpE,KAAK,EAAE,KAAK;KACb,CAAC,CAAC;AACL,CAAC;AAED,SAAS,YAAY,CAAC,KAAc;IAClC,OAAO,CACL,KAAK,YAAY,YAAY,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,CAC7D,IAAI,CACH,KAAK,YAAY,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,CACtD,CAAC;AACJ,CAAC"}

package/dist/errors/runtime-error.d.ts

@@ -0,0 +1,18 @@
+import type { Metadata } from "../types/metadata.js";
+import type { ErrorCategory, RuntimeErrorCode } from "./codes.js";
+export interface RuntimeErrorOptions {
+    code: RuntimeErrorCode;
+    category: ErrorCategory;
+    message: string;
+    retryable?: boolean;
+    cause?: unknown;
+    metadata?: Metadata;
+}
+export declare class RuntimeError extends Error {
+    readonly code: RuntimeErrorCode;
+    readonly category: ErrorCategory;
+    readonly retryable: boolean;
+    readonly cause?: unknown;
+    readonly metadata?: Metadata;
+    constructor(options: RuntimeErrorOptions);
+}

package/dist/errors/runtime-error.js

@@ -0,0 +1,21 @@
+export class RuntimeError extends Error {
+    code;
+    category;
+    retryable;
+    cause;
+    metadata;
+    constructor(options) {
+        super(options.message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = "RuntimeError";
+        this.code = options.code;
+        this.category = options.category;
+        this.retryable = options.retryable ?? false;
+        if (options.cause !== undefined) {
+            this.cause = options.cause;
+        }
+        if (options.metadata !== undefined) {
+            this.metadata = options.metadata;
+        }
+    }
+}
+//# sourceMappingURL=runtime-error.js.map

package/dist/errors/runtime-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-error.js","sourceRoot":"","sources":["../../src/errors/runtime-error.ts"],"names":[],"mappings":"AAYA,MAAM,OAAO,YAAa,SAAQ,KAAK;IAC5B,IAAI,CAAmB;IACvB,QAAQ,CAAgB;IACxB,SAAS,CAAU;IACV,KAAK,CAAW;IACzB,QAAQ,CAAY;IAE7B,YAAY,OAA4B;QACtC,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;QAC3F,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACzB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACjC,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,KAAK,CAAC;QAE5C,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YAChC,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAC7B,CAAC;QAED,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;YACnC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACnC,CAAC;IACH,CAAC;CACF"}

package/dist/errors/serialize.d.ts

@@ -0,0 +1,2 @@
+import type { SerializedRuntimeError } from "../types/error.js";
+export declare function serializeRuntimeError(error: unknown): SerializedRuntimeError;

package/dist/errors/serialize.js

@@ -0,0 +1,12 @@
+import { normalizeUnknownError } from "./normalize.js";
+export function serializeRuntimeError(error) {
+    const normalized = normalizeUnknownError(error);
+    return {
+        code: normalized.code,
+        category: normalized.category,
+        message: normalized.message,
+        retryable: normalized.retryable,
+        ...(normalized.metadata ? { metadata: normalized.metadata } : {}),
+    };
+}
+//# sourceMappingURL=serialize.js.map

package/dist/errors/serialize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize.js","sourceRoot":"","sources":["../../src/errors/serialize.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAEvD,MAAM,UAAU,qBAAqB,CAAC,KAAc;IAClD,MAAM,UAAU,GAAG,qBAAqB,CAAC,KAAK,CAAC,CAAC;IAEhD,OAAO;QACL,IAAI,EAAE,UAAU,CAAC,IAAI;QACrB,QAAQ,EAAE,UAAU,CAAC,QAAQ;QAC7B,OAAO,EAAE,UAAU,CAAC,OAAO;QAC3B,SAAS,EAAE,UAAU,CAAC,SAAS;QAC/B,GAAG,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,UAAU,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAClE,CAAC;AACJ,CAAC"}

package/dist/events/bus.d.ts

@@ -0,0 +1,17 @@
+import type { EventSink } from "./sink.js";
+import type { AgentEvent } from "./types.js";
+export interface EventBus {
+    publish(event: AgentEvent): Promise<void>;
+    subscribe(sink: EventSink): () => void;
+}
+export interface DefaultEventBusOptions {
+    onSinkError?: (sink: EventSink, error: unknown) => void;
+}
+export declare class DefaultEventBus implements EventBus {
+    private readonly sinks;
+    private lastSeq;
+    private readonly onSinkError?;
+    constructor(options?: DefaultEventBusOptions);
+    subscribe(sink: EventSink): () => void;
+    publish(event: AgentEvent): Promise<void>;
+}

package/dist/events/bus.js

@@ -0,0 +1,52 @@
+import { RuntimeError } from "../errors/index.js";
+import { deepFreeze } from "../utils/index.js";
+export class DefaultEventBus {
+    sinks = new Map();
+    lastSeq = 0;
+    onSinkError;
+    constructor(options = {}) {
+        if (options.onSinkError !== undefined) {
+            this.onSinkError = options.onSinkError;
+        }
+    }
+    subscribe(sink) {
+        if (this.sinks.has(sink.id)) {
+            throw new RuntimeError({
+                code: "INTERNAL",
+                category: "internal",
+                message: `Event sink already subscribed: ${sink.id}`,
+            });
+        }
+        this.sinks.set(sink.id, sink);
+        return () => {
+            this.sinks.delete(sink.id);
+        };
+    }
+    async publish(event) {
+        if (event.seq <= this.lastSeq) {
+            throw new RuntimeError({
+                code: "INTERNAL",
+                category: "internal",
+                message: `Event seq must increase monotonically: last=${this.lastSeq}, received=${event.seq}`,
+            });
+        }
+        this.lastSeq = event.seq;
+        const immutable = deepFreeze(structuredClone(event));
+        const sinks = [...this.sinks.values()];
+        const settled = await Promise.allSettled(sinks.map((sink) => sink.handle(immutable)));
+        for (let index = 0; index < settled.length; index += 1) {
+            const result = settled[index];
+            const sink = sinks[index];
+            if (result?.status !== "rejected" || sink === undefined) {
+                continue;
+            }
+            try {
+                this.onSinkError?.(sink, result.reason);
+            }
+            catch {
+                // Observer diagnostics must not affect the runtime.
+            }
+        }
+    }
+}
+//# sourceMappingURL=bus.js.map

package/dist/events/bus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bus.js","sourceRoot":"","sources":["../../src/events/bus.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAa/C,MAAM,OAAO,eAAe;IACT,KAAK,GAAG,IAAI,GAAG,EAAqB,CAAC;IAC9C,OAAO,GAAG,CAAC,CAAC;IACH,WAAW,CAA6C;IAEzE,YAAY,UAAkC,EAAE;QAC9C,IAAI,OAAO,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;YACtC,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;QACzC,CAAC;IACH,CAAC;IAED,SAAS,CAAC,IAAe;QACvB,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;YAC5B,MAAM,IAAI,YAAY,CAAC;gBACrB,IAAI,EAAE,UAAU;gBAChB,QAAQ,EAAE,UAAU;gBACpB,OAAO,EAAE,kCAAkC,IAAI,CAAC,EAAE,EAAE;aACrD,CAAC,CAAC;QACL,CAAC;QAED,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;QAC9B,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC7B,CAAC,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,KAAiB;QAC7B,IAAI,KAAK,CAAC,GAAG,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAC9B,MAAM,IAAI,YAAY,CAAC;gBACrB,IAAI,EAAE,UAAU;gBAChB,QAAQ,EAAE,UAAU;gBACpB,OAAO,EAAE,+CAA+C,IAAI,CAAC,OAAO,cAAc,KAAK,CAAC,GAAG,EAAE;aAC9F,CAAC,CAAC;QACL,CAAC;QAED,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC;QACzB,MAAM,SAAS,GAAG,UAAU,CAAC,eAAe,CAAC,KAAK,CAAC,CAAe,CAAC;QACnE,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;QAEvC,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,CACtC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAC5C,CAAC;QAEF,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;YACvD,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;YAC9B,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;YAC1B,IAAI,MAAM,EAAE,MAAM,KAAK,UAAU,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;gBACxD,SAAS;YACX,CAAC;YAED,IAAI,CAAC;gBACH,IAAI,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;YAC1C,CAAC;YAAC,MAAM,CAAC;gBACP,oDAAoD;YACtD,CAAC;QACH,CAAC;IACH,CAAC;CACF"}

package/dist/events/index.d.ts

@@ -0,0 +1,6 @@
+export type * from "./types.js";
+export type * from "./sink.js";
+export { DefaultEventBus, type EventBus, type DefaultEventBusOptions, } from "./bus.js";
+export { EventSequence } from "./sequence.js";
+export { DefaultEventPublisher, type EventPublisher, } from "./publisher.js";
+export { EventStream } from "./stream.js";

package/dist/events/index.js

@@ -0,0 +1,5 @@
+export { DefaultEventBus, } from "./bus.js";
+export { EventSequence } from "./sequence.js";
+export { DefaultEventPublisher, } from "./publisher.js";
+export { EventStream } from "./stream.js";
+//# sourceMappingURL=index.js.map

package/dist/events/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/events/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,eAAe,GAGhB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EACL,qBAAqB,GAEtB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC"}

package/dist/events/publisher.d.ts

@@ -0,0 +1,12 @@
+import type { EventBus } from "./bus.js";
+import { EventSequence } from "./sequence.js";
+import type { AgentEvent, AgentEventInput } from "./types.js";
+export interface EventPublisher {
+    publish(input: AgentEventInput): Promise<AgentEvent>;
+}
+export declare class DefaultEventPublisher implements EventPublisher {
+    private readonly bus;
+    private readonly sequence;
+    constructor(bus: EventBus, sequence?: EventSequence);
+    publish(input: AgentEventInput): Promise<AgentEvent>;
+}

package/dist/events/publisher.js

@@ -0,0 +1,22 @@
+import { deepFreeze } from "../utils/deep.js";
+import { newEventId } from "../utils/id.js";
+import { EventSequence } from "./sequence.js";
+export class DefaultEventPublisher {
+    bus;
+    sequence;
+    constructor(bus, sequence = new EventSequence()) {
+        this.bus = bus;
+        this.sequence = sequence;
+    }
+    async publish(input) {
+        const event = deepFreeze({
+            ...structuredClone(input),
+            id: newEventId(),
+            seq: this.sequence.next(),
+            timestamp: new Date().toISOString(),
+        });
+        await this.bus.publish(event);
+        return event;
+    }
+}
+//# sourceMappingURL=publisher.js.map

package/dist/events/publisher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"publisher.js","sourceRoot":"","sources":["../../src/events/publisher.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAE5C,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAO9C,MAAM,OAAO,qBAAqB;IAEb;IACA;IAFnB,YACmB,GAAa,EACb,WAAW,IAAI,aAAa,EAAE;QAD9B,QAAG,GAAH,GAAG,CAAU;QACb,aAAQ,GAAR,QAAQ,CAAsB;IAC9C,CAAC;IAEJ,KAAK,CAAC,OAAO,CAAC,KAAsB;QAClC,MAAM,KAAK,GAAG,UAAU,CAAC;YACvB,GAAG,eAAe,CAAC,KAAK,CAAC;YACzB,EAAE,EAAE,UAAU,EAAE;YAChB,GAAG,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE;YACzB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAe,CAAC;QAEjB,MAAM,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAC9B,OAAO,KAAK,CAAC;IACf,CAAC;CACF"}

package/dist/events/sequence.d.ts

@@ -0,0 +1,6 @@
+export declare class EventSequence {
+    private value;
+    constructor(startAt?: number);
+    next(): number;
+    current(): number;
+}

package/dist/events/sequence.js

@@ -0,0 +1,14 @@
+export class EventSequence {
+    value;
+    constructor(startAt = 0) {
+        this.value = startAt;
+    }
+    next() {
+        this.value += 1;
+        return this.value;
+    }
+    current() {
+        return this.value;
+    }
+}
+//# sourceMappingURL=sequence.js.map

package/dist/events/sequence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sequence.js","sourceRoot":"","sources":["../../src/events/sequence.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,aAAa;IAChB,KAAK,CAAS;IAEtB,YAAY,OAAO,GAAG,CAAC;QACrB,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC;IACvB,CAAC;IAED,IAAI;QACF,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC;QAChB,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,OAAO;QACL,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;CACF"}

package/dist/events/sink.d.ts

@@ -0,0 +1,5 @@
+import type { AgentEvent } from "./types.js";
+export interface EventSink {
+    readonly id: string;
+    handle(event: AgentEvent, signal?: AbortSignal): Promise<void>;
+}

package/dist/events/sink.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=sink.js.map

package/dist/events/sink.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sink.js","sourceRoot":"","sources":["../../src/events/sink.ts"],"names":[],"mappings":""}

package/dist/events/stream.d.ts

@@ -0,0 +1,12 @@
+import type { EventSink } from "./sink.js";
+import type { AgentEvent } from "./types.js";
+export declare class EventStream implements EventSink, AsyncIterable<AgentEvent> {
+    readonly id: string;
+    private readonly queue;
+    private readonly waiters;
+    private closed;
+    constructor(id: string);
+    handle(event: AgentEvent): Promise<void>;
+    close(): void;
+    [Symbol.asyncIterator](): AsyncIterator<AgentEvent>;
+}

package/dist/events/stream.js

@@ -0,0 +1,46 @@
+export class EventStream {
+    id;
+    queue = [];
+    waiters = [];
+    closed = false;
+    constructor(id) {
+        this.id = id;
+    }
+    async handle(event) {
+        if (this.closed) {
+            return;
+        }
+        const waiter = this.waiters.shift();
+        if (waiter !== undefined) {
+            waiter({ value: event, done: false });
+            return;
+        }
+        this.queue.push(event);
+    }
+    close() {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        for (const waiter of this.waiters.splice(0)) {
+            waiter({ value: undefined, done: true });
+        }
+    }
+    [Symbol.asyncIterator]() {
+        return {
+            next: async () => {
+                const event = this.queue.shift();
+                if (event !== undefined) {
+                    return { value: event, done: false };
+                }
+                if (this.closed) {
+                    return { value: undefined, done: true };
+                }
+                return new Promise((resolve) => {
+                    this.waiters.push(resolve);
+                });
+            },
+        };
+    }
+}
+//# sourceMappingURL=stream.js.map

package/dist/events/stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.js","sourceRoot":"","sources":["../../src/events/stream.ts"],"names":[],"mappings":"AAKA,MAAM,OAAO,WAAW;IAKD;IAJJ,KAAK,GAAiB,EAAE,CAAC;IACzB,OAAO,GAAa,EAAE,CAAC;IAChC,MAAM,GAAG,KAAK,CAAC;IAEvB,YAAqB,EAAU;QAAV,OAAE,GAAF,EAAE,CAAQ;IAAG,CAAC;IAEnC,KAAK,CAAC,MAAM,CAAC,KAAiB;QAC5B,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,OAAO;QACT,CAAC;QAED,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACpC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,MAAM,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;YACtC,OAAO;QACT,CAAC;QAED,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACzB,CAAC;IAED,KAAK;QACH,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,OAAO;QACT,CAAC;QAED,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;YAC5C,MAAM,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAC3C,CAAC;IACH,CAAC;IAED,CAAC,MAAM,CAAC,aAAa,CAAC;QACpB,OAAO;YACL,IAAI,EAAE,KAAK,IAAI,EAAE;gBACf,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;gBACjC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;oBACxB,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;gBACvC,CAAC;gBAED,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;oBAChB,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;gBAC1C,CAAC;gBAED,OAAO,IAAI,OAAO,CAA6B,CAAC,OAAO,EAAE,EAAE;oBACzD,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBAC7B,CAAC,CAAC,CAAC;YACL,CAAC;SACF,CAAC;IACJ,CAAC;CACF"}

package/dist/events/types.d.ts

@@ -0,0 +1,42 @@
+import type { ToolExecutionResult } from "../tools/types.js";
+import type { AgentMessage, CompactionId, EventId, RunId, SerializedRuntimeError, SessionId, StopReason, ToolCall, TurnId, Usage } from "../types/index.js";
+export interface AgentEventEnvelope<TType extends string, TData> {
+    id: EventId;
+    seq: number;
+    timestamp: string;
+    sessionId: SessionId;
+    runId?: RunId;
+    turnId?: TurnId;
+    type: TType;
+    data: TData;
+}
+export type AgentEvent = AgentEventEnvelope<"run_start", {
+    input: string;
+}> | AgentEventEnvelope<"turn_start", {
+    turn: number;
+}> | AgentEventEnvelope<"message_start", {
+    role: "assistant";
+}> | AgentEventEnvelope<"message_delta", {
+    delta: string;
+}> | AgentEventEnvelope<"reasoning_delta", {
+    delta: string;
+}> | AgentEventEnvelope<"message_end", {
+    message: AgentMessage;
+}> | AgentEventEnvelope<"tool_start", {
+    call: ToolCall;
+}> | AgentEventEnvelope<"tool_end", {
+    result: ToolExecutionResult;
+}> | AgentEventEnvelope<"compact_start", {
+    reason: string;
+}> | AgentEventEnvelope<"compact_end", {
+    checkpointId?: CompactionId;
+}> | AgentEventEnvelope<"usage", {
+    usage: Usage;
+}> | AgentEventEnvelope<"turn_end", {
+    turn: number;
+}> | AgentEventEnvelope<"run_end", {
+    reason: StopReason;
+}> | AgentEventEnvelope<"error", {
+    error: SerializedRuntimeError;
+}>;
+export type AgentEventInput = AgentEvent extends infer TEvent ? TEvent extends AgentEvent ? Omit<TEvent, "id" | "seq" | "timestamp"> : never : never;

package/dist/events/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/events/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/events/types.ts"],"names":[],"mappings":""}

package/dist/hooks/bus.d.ts

@@ -0,0 +1,14 @@
+import type { HookRegistry } from "./registry.js";
+import type { HookContext, HookName, HookRunResult } from "./types.js";
+export interface HookBus {
+    run<T>(event: HookName, value: T, context: HookContext): Promise<HookRunResult<T>>;
+}
+export interface DefaultHookBusOptions {
+    defaultTimeoutMs?: number;
+}
+export declare class DefaultHookBus implements HookBus {
+    private readonly registry;
+    private readonly defaultTimeoutMs;
+    constructor(registry: HookRegistry, options?: DefaultHookBusOptions);
+    run<T>(event: HookName, value: T, context: HookContext): Promise<HookRunResult<T>>;
+}

package/dist/hooks/bus.js

@@ -0,0 +1,104 @@
+import { RuntimeError } from "../errors/runtime-error.js";
+import { deepFreeze } from "../utils/deep.js";
+import { assertHookActionAllowed } from "./policy.js";
+import { runHookWithTimeout } from "./timeout.js";
+function copyValue(value) {
+    try {
+        return deepFreeze(structuredClone(value));
+    }
+    catch (error) {
+        throw new RuntimeError({
+            code: "HOOK_FAILED",
+            category: "hook",
+            message: "Hook payload must be structured-cloneable",
+            cause: error,
+        });
+    }
+}
+export class DefaultHookBus {
+    registry;
+    defaultTimeoutMs;
+    constructor(registry, options = {}) {
+        this.registry = registry;
+        if (options.defaultTimeoutMs !== undefined &&
+            (!Number.isSafeInteger(options.defaultTimeoutMs) ||
+                options.defaultTimeoutMs <= 0)) {
+            throw new RangeError("defaultTimeoutMs must be a positive integer");
+        }
+        this.defaultTimeoutMs = options.defaultTimeoutMs;
+    }
+    async run(event, value, context) {
+        if (context.signal?.aborted) {
+            throw new RuntimeError({
+                code: "ABORTED",
+                category: "abort",
+                message: "Operation aborted",
+                cause: context.signal.reason,
+            });
+        }
+        let current = copyValue(value);
+        for (const registered of this.registry.list(event)) {
+            const hook = registered;
+            context.signal?.throwIfAborted();
+            let action;
+            try {
+                action = await runHookWithTimeout(hook, copyValue(current), context, this.defaultTimeoutMs);
+            }
+            catch (error) {
+                if (error instanceof RuntimeError && error.code === "ABORTED") {
+                    throw error;
+                }
+                if (hook.failureMode === "fail_open") {
+                    continue;
+                }
+                throw new RuntimeError({
+                    code: "HOOK_FAILED",
+                    category: "hook",
+                    message: `Hook failed: ${hook.id}`,
+                    cause: error,
+                    metadata: { hookId: hook.id, event },
+                });
+            }
+            assertHookActionAllowed(event, action);
+            if (action.type === "modify") {
+                current = copyValue(action.value);
+                continue;
+            }
+            if (action.type === "continue") {
+                continue;
+            }
+            if (action.type === "block") {
+                return {
+                    value: current,
+                    blocked: true,
+                    stopRequested: false,
+                    retryRequested: false,
+                    reason: action.reason,
+                };
+            }
+            if (action.type === "stop") {
+                return {
+                    value: current,
+                    blocked: false,
+                    stopRequested: true,
+                    retryRequested: false,
+                    ...(action.reason === undefined ? {} : { reason: action.reason }),
+                };
+            }
+            return {
+                value: current,
+                blocked: false,
+                stopRequested: false,
+                retryRequested: true,
+                ...(action.reason === undefined ? {} : { reason: action.reason }),
+            };
+        }
+        return {
+            value: current,
+            blocked: false,
+            stopRequested: false,
+            retryRequested: false,
+        };
+    }
+}
+//# sourceMappingURL=bus.js.map

package/dist/hooks/bus.js.map

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

package/dist/hooks/index.d.ts

@@ -0,0 +1,5 @@
+export type * from "./types.js";
+export { DefaultHookRegistry, type HookRegistry, } from "./registry.js";
+export { DefaultHookBus, type HookBus, type DefaultHookBusOptions, } from "./bus.js";
+export { runHookWithTimeout } from "./timeout.js";
+export { assertHookActionAllowed, type HookActionType, } from "./policy.js";