@simulacra-ai/core 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./checkpoints/index.ts";
+export * from "./conversations/index.ts";
+export * from "./context-transformers/index.ts";
+export * from "./policies/index.ts";
+export * from "./workflows/index.ts";
+export * from "./tools/index.ts";
+export { CancellationToken, CancellationTokenSource, OperationCanceledError, peek_generator, sleep, } from "./utils/async.ts";
+export { deep_merge, undefined_if_empty } from "./utils/object.ts";
+export type { DeepPartial, Prettify } from "./utils/types.ts";
+//# 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,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,cAAc,iCAAiC,CAAC;AAChD,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,sBAAsB,EACtB,cAAc,EACd,KAAK,GACN,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACnE,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+export * from "./checkpoints/index.js";
+export * from "./conversations/index.js";
+export * from "./context-transformers/index.js";
+export * from "./policies/index.js";
+export * from "./workflows/index.js";
+export * from "./tools/index.js";
+export { CancellationToken, CancellationTokenSource, OperationCanceledError, peek_generator, sleep, } from "./utils/async.js";
+export { deep_merge, undefined_if_empty } from "./utils/object.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,cAAc,iCAAiC,CAAC;AAChD,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,sBAAsB,EACtB,cAAc,EACd,KAAK,GACN,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/policies/composite-policy.d.ts

@@ -0,0 +1,29 @@
+import { CancellationToken } from "../utils/async.ts";
+import { Policy, PolicyResult } from "./types.ts";
+/**
+ * Policy that combines multiple policies into a single execution chain.
+ *
+ * Policies are applied in the order provided, with each policy wrapping
+ * the execution of the next.
+ */
+export declare class CompositePolicy extends Policy {
+    #private;
+    /**
+     * Creates a new composite policy.
+     *
+     * @param policies - The policies to compose. If empty, uses a NoopPolicy.
+     */
+    constructor(...policies: Policy[]);
+    /**
+     * Executes a function with all composed policies applied.
+     *
+     * @template TResult - The return type of the function.
+     * @template TArgs - The argument types of the function.
+     * @param cancellation_token - Token for cancelling the operation.
+     * @param fn - The function to execute.
+     * @param args - Arguments to pass to the function.
+     * @returns A promise that resolves to the policy result.
+     */
+    execute<TResult, TArgs extends unknown[]>(cancellation_token: CancellationToken, fn: (...args: TArgs) => Promise<TResult>, ...args: TArgs): Promise<PolicyResult<TResult>>;
+}
+//# sourceMappingURL=composite-policy.d.ts.map

package/dist/policies/composite-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composite-policy.d.ts","sourceRoot":"","sources":["../../src/policies/composite-policy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEtD,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAElD;;;;;GAKG;AACH,qBAAa,eAAgB,SAAQ,MAAM;;IAGzC;;;;OAIG;gBACS,GAAG,QAAQ,EAAE,MAAM,EAAE;IAKjC;;;;;;;;;OASG;IACG,OAAO,CAAC,OAAO,EAAE,KAAK,SAAS,OAAO,EAAE,EAC5C,kBAAkB,EAAE,iBAAiB,EACrC,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,OAAO,CAAC,EACxC,GAAG,IAAI,EAAE,KAAK,GACb,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;CAiDlC"}

package/dist/policies/composite-policy.js

@@ -0,0 +1,77 @@
+import { NoopPolicy } from "./noop-policy.js";
+import { Policy } from "./types.js";
+/**
+ * Policy that combines multiple policies into a single execution chain.
+ *
+ * Policies are applied in the order provided, with each policy wrapping
+ * the execution of the next.
+ */
+export class CompositePolicy extends Policy {
+    #policies;
+    /**
+     * Creates a new composite policy.
+     *
+     * @param policies - The policies to compose. If empty, uses a NoopPolicy.
+     */
+    constructor(...policies) {
+        super();
+        this.#policies = policies.length > 0 ? policies : [new NoopPolicy()];
+    }
+    /**
+     * Executes a function with all composed policies applied.
+     *
+     * @template TResult - The return type of the function.
+     * @template TArgs - The argument types of the function.
+     * @param cancellation_token - Token for cancelling the operation.
+     * @param fn - The function to execute.
+     * @param args - Arguments to pass to the function.
+     * @returns A promise that resolves to the policy result.
+     */
+    async execute(cancellation_token, fn, ...args) {
+        let current_fn = fn;
+        const policy_metadata = {};
+        const execution_order = [];
+        for (let i = this.#policies.length - 1; i >= 0; i--) {
+            cancellation_token.throw_if_cancellation_requested();
+            const policy = this.#policies[i];
+            const policy_name = `${policy.constructor.name}[${i}]`;
+            execution_order.push(policy_name);
+            const wrapped_fn = current_fn;
+            current_fn = async (...wrapped_args) => {
+                const policy_result = await policy.execute(cancellation_token, wrapped_fn, ...wrapped_args);
+                policy_metadata[policy_name] = policy_result.metadata;
+                if (policy_result.result) {
+                    return policy_result.value;
+                }
+                else {
+                    throw policy_result.error;
+                }
+            };
+        }
+        try {
+            return {
+                result: true,
+                value: await current_fn(...args),
+                metadata: {
+                    policy: CompositePolicy.name,
+                    policies: policy_metadata,
+                    execution_order: [...execution_order].reverse(),
+                    policy_count: this.#policies.length,
+                },
+            };
+        }
+        catch (error) {
+            return {
+                result: false,
+                error,
+                metadata: {
+                    policy: CompositePolicy.name,
+                    policies: policy_metadata,
+                    execution_order: [...execution_order].reverse(),
+                    policy_count: this.#policies.length,
+                },
+            };
+        }
+    }
+}
+//# sourceMappingURL=composite-policy.js.map

package/dist/policies/composite-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"composite-policy.js","sourceRoot":"","sources":["../../src/policies/composite-policy.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,MAAM,EAAgB,MAAM,YAAY,CAAC;AAElD;;;;;GAKG;AACH,MAAM,OAAO,eAAgB,SAAQ,MAAM;IAChC,SAAS,CAAW;IAE7B;;;;OAIG;IACH,YAAY,GAAG,QAAkB;QAC/B,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,UAAU,EAAE,CAAC,CAAC;IACvE,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,OAAO,CACX,kBAAqC,EACrC,EAAwC,EACxC,GAAG,IAAW;QAEd,IAAI,UAAU,GAAG,EAAE,CAAC;QACpB,MAAM,eAAe,GAA4B,EAAE,CAAC;QACpD,MAAM,eAAe,GAAa,EAAE,CAAC;QAErC,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YACpD,kBAAkB,CAAC,+BAA+B,EAAE,CAAC;YAErD,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;YACjC,MAAM,WAAW,GAAG,GAAG,MAAM,CAAC,WAAW,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC;YACvD,eAAe,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;YAElC,MAAM,UAAU,GAAG,UAAU,CAAC;YAC9B,UAAU,GAAG,KAAK,EAAE,GAAG,YAAmB,EAAE,EAAE;gBAC5C,MAAM,aAAa,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,kBAAkB,EAAE,UAAU,EAAE,GAAG,YAAY,CAAC,CAAC;gBAC5F,eAAe,CAAC,WAAW,CAAC,GAAG,aAAa,CAAC,QAAQ,CAAC;gBAEtD,IAAI,aAAa,CAAC,MAAM,EAAE,CAAC;oBACzB,OAAO,aAAa,CAAC,KAAK,CAAC;gBAC7B,CAAC;qBAAM,CAAC;oBACN,MAAM,aAAa,CAAC,KAAK,CAAC;gBAC5B,CAAC;YACH,CAAC,CAAC;QACJ,CAAC;QAED,IAAI,CAAC;YACH,OAAO;gBACL,MAAM,EAAE,IAAI;gBACZ,KAAK,EAAE,MAAM,UAAU,CAAC,GAAG,IAAI,CAAC;gBAChC,QAAQ,EAAE;oBACR,MAAM,EAAE,eAAe,CAAC,IAAI;oBAC5B,QAAQ,EAAE,eAAe;oBACzB,eAAe,EAAE,CAAC,GAAG,eAAe,CAAC,CAAC,OAAO,EAAE;oBAC/C,YAAY,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM;iBACpC;aACF,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO;gBACL,MAAM,EAAE,KAAK;gBACb,KAAK;gBACL,QAAQ,EAAE;oBACR,MAAM,EAAE,eAAe,CAAC,IAAI;oBAC5B,QAAQ,EAAE,eAAe;oBACzB,eAAe,EAAE,CAAC,GAAG,eAAe,CAAC,CAAC,OAAO,EAAE;oBAC/C,YAAY,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM;iBACpC;aACF,CAAC;QACJ,CAAC;IACH,CAAC;CACF"}

package/dist/policies/default-policy.d.ts

@@ -0,0 +1,7 @@
+import type { Policy } from "./types.ts";
+/**
+ * The default policy used when none is passed to Conversation.
+ * A composite that includes retry with exponential backoff. Rate and token limits require attach(conversation) so are not in the default.
+ */
+export declare function getDefaultPolicy(): Policy;
+//# sourceMappingURL=default-policy.d.ts.map

package/dist/policies/default-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-policy.d.ts","sourceRoot":"","sources":["../../src/policies/default-policy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAIzC;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAQzC"}

package/dist/policies/default-policy.js

@@ -0,0 +1,14 @@
+import { CompositePolicy } from "./composite-policy.js";
+import { RetryPolicy } from "./retry-policy.js";
+/**
+ * The default policy used when none is passed to Conversation.
+ * A composite that includes retry with exponential backoff. Rate and token limits require attach(conversation) so are not in the default.
+ */
+export function getDefaultPolicy() {
+    return new CompositePolicy(new RetryPolicy({
+        max_attempts: 3,
+        initial_backoff_ms: 1000,
+        backoff_factor: 2,
+    }));
+}
+//# sourceMappingURL=default-policy.js.map

package/dist/policies/default-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-policy.js","sourceRoot":"","sources":["../../src/policies/default-policy.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD;;;GAGG;AACH,MAAM,UAAU,gBAAgB;IAC9B,OAAO,IAAI,eAAe,CACxB,IAAI,WAAW,CAAC;QACd,YAAY,EAAE,CAAC;QACf,kBAAkB,EAAE,IAAI;QACxB,cAAc,EAAE,CAAC;KAClB,CAAC,CACH,CAAC;AACJ,CAAC"}

package/dist/policies/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./composite-policy.ts";
+export * from "./default-policy.ts";
+export * from "./noop-policy.ts";
+export * from "./rate-limit-policy.ts";
+export * from "./retry-policy.ts";
+export * from "./token-limit-policy.ts";
+export * from "./types.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/policies/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/policies/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,yBAAyB,CAAC;AACxC,cAAc,YAAY,CAAC"}

package/dist/policies/index.js

@@ -0,0 +1,8 @@
+export * from "./composite-policy.js";
+export * from "./default-policy.js";
+export * from "./noop-policy.js";
+export * from "./rate-limit-policy.js";
+export * from "./retry-policy.js";
+export * from "./token-limit-policy.js";
+export * from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/policies/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/policies/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,yBAAyB,CAAC;AACxC,cAAc,YAAY,CAAC"}

package/dist/policies/noop-policy.d.ts

@@ -0,0 +1,21 @@
+import { CancellationToken } from "../utils/async.ts";
+import { Policy, PolicyResult } from "./types.ts";
+/**
+ * Policy that performs no special operations.
+ *
+ * Simply executes the provided function with cancellation support.
+ */
+export declare class NoopPolicy extends Policy {
+    /**
+     * Executes a function with no additional policy logic.
+     *
+     * @template TResult - The return type of the function.
+     * @template TArgs - The argument types of the function.
+     * @param cancellation_token - Token for cancelling the operation.
+     * @param fn - The function to execute.
+     * @param args - Arguments to pass to the function.
+     * @returns A promise that resolves to the policy result.
+     */
+    execute<TResult, TArgs extends unknown[]>(cancellation_token: CancellationToken, fn: (...args: TArgs) => Promise<TResult>, ...args: TArgs): Promise<PolicyResult<TResult>>;
+}
+//# sourceMappingURL=noop-policy.d.ts.map

package/dist/policies/noop-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"noop-policy.d.ts","sourceRoot":"","sources":["../../src/policies/noop-policy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAElD;;;;GAIG;AACH,qBAAa,UAAW,SAAQ,MAAM;IACpC;;;;;;;;;OASG;IACG,OAAO,CAAC,OAAO,EAAE,KAAK,SAAS,OAAO,EAAE,EAC5C,kBAAkB,EAAE,iBAAiB,EACrC,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,OAAO,CAAC,EACxC,GAAG,IAAI,EAAE,KAAK,GACb,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;CAgBlC"}

package/dist/policies/noop-policy.js

@@ -0,0 +1,36 @@
+import { Policy } from "./types.js";
+/**
+ * Policy that performs no special operations.
+ *
+ * Simply executes the provided function with cancellation support.
+ */
+export class NoopPolicy extends Policy {
+    /**
+     * Executes a function with no additional policy logic.
+     *
+     * @template TResult - The return type of the function.
+     * @template TArgs - The argument types of the function.
+     * @param cancellation_token - Token for cancelling the operation.
+     * @param fn - The function to execute.
+     * @param args - Arguments to pass to the function.
+     * @returns A promise that resolves to the policy result.
+     */
+    async execute(cancellation_token, fn, ...args) {
+        try {
+            cancellation_token.throw_if_cancellation_requested();
+            return {
+                result: true,
+                value: await Promise.race([fn(...args), cancellation_token.await_cancellation()]),
+                metadata: { policy: NoopPolicy.name },
+            };
+        }
+        catch (error) {
+            return {
+                result: false,
+                error,
+                metadata: { policy: NoopPolicy.name },
+            };
+        }
+    }
+}
+//# sourceMappingURL=noop-policy.js.map

package/dist/policies/noop-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"noop-policy.js","sourceRoot":"","sources":["../../src/policies/noop-policy.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAgB,MAAM,YAAY,CAAC;AAElD;;;;GAIG;AACH,MAAM,OAAO,UAAW,SAAQ,MAAM;IACpC;;;;;;;;;OASG;IACH,KAAK,CAAC,OAAO,CACX,kBAAqC,EACrC,EAAwC,EACxC,GAAG,IAAW;QAEd,IAAI,CAAC;YACH,kBAAkB,CAAC,+BAA+B,EAAE,CAAC;YACrD,OAAO;gBACL,MAAM,EAAE,IAAI;gBACZ,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE,kBAAkB,CAAC,kBAAkB,EAAE,CAAC,CAAC;gBACjF,QAAQ,EAAE,EAAE,MAAM,EAAE,UAAU,CAAC,IAAI,EAAE;aACtC,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO;gBACL,MAAM,EAAE,KAAK;gBACb,KAAK;gBACL,QAAQ,EAAE,EAAE,MAAM,EAAE,UAAU,CAAC,IAAI,EAAE;aACtC,CAAC;QACJ,CAAC;IACH,CAAC;CACF"}

package/dist/policies/rate-limit-policy.d.ts

@@ -0,0 +1,44 @@
+import { Conversation } from "../conversations/index.ts";
+import { CancellationToken } from "../utils/async.ts";
+import { Policy, PolicyResult } from "./types.ts";
+/**
+ * Configuration options for rate limiting.
+ */
+export type RateLimitPolicyOptions = {
+    /** Maximum number of requests allowed in the time period. */
+    limit: number;
+    /** Time period in milliseconds. */
+    period_ms: number;
+};
+/**
+ * Policy that enforces rate limits on operations.
+ *
+ * Tracks request timestamps and delays execution when the rate limit is exceeded.
+ */
+export declare class RateLimitPolicy extends Policy {
+    #private;
+    /**
+     * Creates a new rate limit policy.
+     *
+     * @param options - The rate limiting configuration.
+     */
+    constructor(options: RateLimitPolicyOptions);
+    /**
+     * Attaches this policy to a conversation to track its requests.
+     *
+     * @param conversation - The conversation to monitor.
+     */
+    attach(conversation: Conversation): void;
+    /**
+     * Executes a function with rate limiting applied.
+     *
+     * @template TResult - The return type of the function.
+     * @template TArgs - The argument types of the function.
+     * @param cancellation_token - Token for cancelling the operation.
+     * @param fn - The function to execute.
+     * @param args - Arguments to pass to the function.
+     * @returns A promise that resolves to the policy result.
+     */
+    execute<TResult, TArgs extends unknown[]>(cancellation_token: CancellationToken, fn: (...args: TArgs) => Promise<TResult>, ...args: TArgs): Promise<PolicyResult<TResult>>;
+}
+//# sourceMappingURL=rate-limit-policy.d.ts.map

package/dist/policies/rate-limit-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit-policy.d.ts","sourceRoot":"","sources":["../../src/policies/rate-limit-policy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAsB,MAAM,2BAA2B,CAAC;AAC7E,OAAO,EAAE,iBAAiB,EAAS,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAElD;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAC;IACd,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;;GAIG;AACH,qBAAa,eAAgB,SAAQ,MAAM;;IAKzC;;;;OAIG;gBACS,OAAO,EAAE,sBAAsB;IAK3C;;;;OAIG;IACH,MAAM,CAAC,YAAY,EAAE,YAAY;IASjC;;;;;;;;;OASG;IACG,OAAO,CAAC,OAAO,EAAE,KAAK,SAAS,OAAO,EAAE,EAC5C,kBAAkB,EAAE,iBAAiB,EACrC,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,OAAO,CAAC,EACxC,GAAG,IAAI,EAAE,KAAK,GACb,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;CAsElC"}

package/dist/policies/rate-limit-policy.js

@@ -0,0 +1,98 @@
+import { sleep } from "../utils/async.js";
+import { Policy } from "./types.js";
+/**
+ * Policy that enforces rate limits on operations.
+ *
+ * Tracks request timestamps and delays execution when the rate limit is exceeded.
+ */
+export class RateLimitPolicy extends Policy {
+    #options;
+    #requests = [];
+    /**
+     * Creates a new rate limit policy.
+     *
+     * @param options - The rate limiting configuration.
+     */
+    constructor(options) {
+        super();
+        this.#options = options;
+    }
+    /**
+     * Attaches this policy to a conversation to track its requests.
+     *
+     * @param conversation - The conversation to monitor.
+     */
+    attach(conversation) {
+        conversation.on("request_success", this.#on_request_success);
+        conversation.on("child_event", this.#on_child_event);
+        conversation.once("dispose", () => {
+            conversation.off("request_success", this.#on_request_success);
+            conversation.off("child_event", this.#on_child_event);
+        });
+    }
+    /**
+     * Executes a function with rate limiting applied.
+     *
+     * @template TResult - The return type of the function.
+     * @template TArgs - The argument types of the function.
+     * @param cancellation_token - Token for cancelling the operation.
+     * @param fn - The function to execute.
+     * @param args - Arguments to pass to the function.
+     * @returns A promise that resolves to the policy result.
+     */
+    async execute(cancellation_token, fn, ...args) {
+        const now = Date.now();
+        this.#requests = this.#requests.filter((timestamp) => now - timestamp < this.#options.period_ms);
+        const current_usage = this.#requests.length;
+        const metadata = {
+            policy: RateLimitPolicy.name,
+            limit: this.#options.limit,
+            period_ms: this.#options.period_ms,
+            current_usage,
+        };
+        const wait_time = this.#calculate_wait_time(current_usage, this.#options.limit, this.#options.period_ms);
+        if (wait_time > 0) {
+            metadata.wait_time_ms = wait_time;
+            await sleep(wait_time, cancellation_token);
+        }
+        cancellation_token.throw_if_cancellation_requested();
+        try {
+            const value = await Promise.race([fn(...args), cancellation_token.await_cancellation()]);
+            return {
+                result: true,
+                value,
+                metadata,
+            };
+        }
+        catch (error) {
+            return {
+                result: false,
+                error: error,
+                metadata,
+            };
+        }
+    }
+    #calculate_wait_time(current_usage, limit, period_ms) {
+        if (current_usage < limit) {
+            return 0;
+        }
+        const requests_over_limit = current_usage - limit + 1;
+        const time_per_request = period_ms / limit;
+        return requests_over_limit * time_per_request;
+    }
+    #on_request_success = () => {
+        const now = Date.now();
+        this.#requests.push(now);
+    };
+    #on_child_event = (event_data) => {
+        const { event_name, event_args } = event_data;
+        if (event_name === "request_success") {
+            this.#on_request_success();
+        }
+        if (event_name === "child_event") {
+            const [child_event_data] = event_args;
+            this.#on_child_event(child_event_data);
+        }
+    };
+}
+//# sourceMappingURL=rate-limit-policy.js.map

package/dist/policies/rate-limit-policy.js.map

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

package/dist/policies/retry-policy.d.ts

@@ -0,0 +1,42 @@
+import { CancellationToken } from "../utils/async.ts";
+import { Policy, PolicyErrorResult, PolicyResult } from "./types.ts";
+/**
+ * Configuration options for retry behavior.
+ */
+export interface RetryPolicyOptions {
+    /** Maximum number of attempts (including the initial attempt). */
+    max_attempts: number;
+    /** Initial backoff delay in milliseconds. */
+    initial_backoff_ms: number;
+    /** Factor by which to multiply the backoff after each retry. */
+    backoff_factor: number;
+    /** Optional function to determine if an error is retryable. */
+    retryable?: (result: PolicyErrorResult) => boolean;
+}
+export declare function defaultRetryable(result: PolicyErrorResult): boolean;
+/**
+ * Policy that retries failed operations with exponential backoff.
+ *
+ * @template _TResult - The result type of the operation.
+ */
+export declare class RetryPolicy<_TResult> extends Policy {
+    #private;
+    /**
+     * Creates a new retry policy.
+     *
+     * @param options - The retry configuration options.
+     */
+    constructor(options: RetryPolicyOptions);
+    /**
+     * Executes a function with retry logic applied.
+     *
+     * @template TResult - The return type of the function.
+     * @template TArgs - The argument types of the function.
+     * @param cancellation_token - Token for cancelling the operation.
+     * @param fn - The function to execute.
+     * @param args - Arguments to pass to the function.
+     * @returns A promise that resolves to the policy result.
+     */
+    execute<TResult, TArgs extends unknown[]>(cancellation_token: CancellationToken, fn: (...args: TArgs) => Promise<TResult>, ...args: TArgs): Promise<PolicyResult<TResult>>;
+}
+//# sourceMappingURL=retry-policy.d.ts.map

package/dist/policies/retry-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry-policy.d.ts","sourceRoot":"","sources":["../../src/policies/retry-policy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAS,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAErE;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,kEAAkE;IAClE,YAAY,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gEAAgE;IAChE,cAAc,EAAE,MAAM,CAAC;IACvB,+DAA+D;IAC/D,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,OAAO,CAAC;CACpD;AAiBD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAuCnE;AAED;;;;GAIG;AACH,qBAAa,WAAW,CAAC,QAAQ,CAAE,SAAQ,MAAM;;IAG/C;;;;OAIG;gBACS,OAAO,EAAE,kBAAkB;IAKvC;;;;;;;;;OASG;IACG,OAAO,CAAC,OAAO,EAAE,KAAK,SAAS,OAAO,EAAE,EAC5C,kBAAkB,EAAE,iBAAiB,EACrC,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,OAAO,CAAC,EACxC,GAAG,IAAI,EAAE,KAAK,GACb,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;CA0ClC"}

package/dist/policies/retry-policy.js

@@ -0,0 +1,114 @@
+import { sleep } from "../utils/async.js";
+import { Policy } from "./types.js";
+const RETRYABLE_NETWORK_ERROR_CODES = new Set([
+    "ECONNRESET",
+    "ECONNREFUSED",
+    "ECONNABORTED",
+    "ETIMEDOUT",
+    "ENETUNREACH",
+    "EHOSTUNREACH",
+    "EPIPE",
+    "EAI_AGAIN",
+    "UND_ERR_CONNECT_TIMEOUT",
+    "UND_ERR_SOCKET",
+]);
+const RETRYABLE_HTTP_STATUS_CODES = new Set([408, 429, 500, 502, 503, 504, 529]);
+export function defaultRetryable(result) {
+    const error = result.error;
+    if (error !== null && error !== undefined && typeof error === "object" && "status" in error) {
+        const status = error.status;
+        if (typeof status === "number") {
+            return RETRYABLE_HTTP_STATUS_CODES.has(status);
+        }
+    }
+    if (error !== null && error !== undefined && typeof error === "object") {
+        const code = error.code;
+        if (typeof code === "string" && RETRYABLE_NETWORK_ERROR_CODES.has(code)) {
+            return true;
+        }
+        const cause = error.cause;
+        if (cause !== null && cause !== undefined && typeof cause === "object") {
+            const causeCode = cause.code;
+            if (typeof causeCode === "string" && RETRYABLE_NETWORK_ERROR_CODES.has(causeCode)) {
+                return true;
+            }
+        }
+    }
+    if (error instanceof Error) {
+        const msg = error.message.toLowerCase();
+        if (msg.includes("timeout") ||
+            msg.includes("econnreset") ||
+            msg.includes("econnrefused") ||
+            msg.includes("socket hang up") ||
+            msg.includes("network error") ||
+            msg.includes("fetch failed")) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Policy that retries failed operations with exponential backoff.
+ *
+ * @template _TResult - The result type of the operation.
+ */
+export class RetryPolicy extends Policy {
+    #options;
+    /**
+     * Creates a new retry policy.
+     *
+     * @param options - The retry configuration options.
+     */
+    constructor(options) {
+        super();
+        this.#options = { ...options, retryable: options.retryable ?? defaultRetryable };
+    }
+    /**
+     * Executes a function with retry logic applied.
+     *
+     * @template TResult - The return type of the function.
+     * @template TArgs - The argument types of the function.
+     * @param cancellation_token - Token for cancelling the operation.
+     * @param fn - The function to execute.
+     * @param args - Arguments to pass to the function.
+     * @returns A promise that resolves to the policy result.
+     */
+    async execute(cancellation_token, fn, ...args) {
+        let attempt = 1;
+        let backoff_ms = this.#options.initial_backoff_ms;
+        const metadata = {
+            policy: RetryPolicy.name,
+            attempts: 0,
+            ...this.#options,
+        };
+        while (true) {
+            cancellation_token.throw_if_cancellation_requested();
+            try {
+                const value = await Promise.race([fn(...args), cancellation_token.await_cancellation()]);
+                metadata.attempts = attempt;
+                return {
+                    result: true,
+                    value,
+                    metadata,
+                };
+            }
+            catch (error) {
+                metadata.attempts = attempt;
+                const result = {
+                    result: false,
+                    error,
+                    metadata,
+                };
+                if (attempt >= this.#options.max_attempts || !this.#options.retryable(result)) {
+                    return result;
+                }
+                await sleep(backoff_ms, cancellation_token);
+                metadata.lastError = error;
+                metadata.lastBackoffMs = backoff_ms;
+                backoff_ms *= this.#options.backoff_factor;
+                attempt++;
+            }
+        }
+    }
+}
+//# sourceMappingURL=retry-policy.js.map

package/dist/policies/retry-policy.js.map

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