@xmemory/temporal 1.0.0

package/dist/errors.js

@@ -0,0 +1,247 @@
+"use strict";
+/**
+ * Translate xmemory API errors into Temporal failures.
+ *
+ * Temporal owns retries, so this is the one place an `XmemoryAPIError` becomes an
+ * `ApplicationFailure` with a retryability verdict.
+ *
+ * Rules: branch on `.code`, not the HTTP status; an unrecognized code never raises
+ * and keeps its own type, so a newer server cannot break this client mid-deploy,
+ * while whether to retry it comes from the status — a 401 or 404 is terminal
+ * whatever the code says; never echo the raw exception string, which can embed
+ * internal hostnames.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NON_RETRYABLE_TYPES = exports.TYPE_WRITE_TIMEOUT = exports.TYPE_WRITE_NOT_FOUND = exports.TYPE_WRITE_FAILED = exports.TYPE_UNKNOWN = exports.TYPE_UNAVAILABLE = exports.TYPE_SERVER_ERROR = exports.TYPE_SCHEMA_REJECTED = exports.TYPE_RATE_LIMITED = exports.TYPE_QUOTA_EXCEEDED = exports.TYPE_NO_DEADLINE = exports.TYPE_NOT_FOUND = exports.TYPE_NOT_BOUND = exports.TYPE_MONTHLY_QUOTA_EXCEEDED = exports.TYPE_DEADLINE_EXPIRED = exports.TYPE_DAILY_QUOTA_EXCEEDED = exports.TYPE_BAD_REQUEST = exports.TYPE_BAD_OPTIONS = exports.TYPE_AUTH_FAILED = void 0;
+exports.toApplicationFailure = toApplicationFailure;
+const common_1 = require("@temporalio/common");
+const xmemory_1 = require("xmemory");
+const names_1 = require("./names");
+Object.defineProperty(exports, "TYPE_AUTH_FAILED", { enumerable: true, get: function () { return names_1.TYPE_AUTH_FAILED; } });
+Object.defineProperty(exports, "TYPE_BAD_OPTIONS", { enumerable: true, get: function () { return names_1.TYPE_BAD_OPTIONS; } });
+Object.defineProperty(exports, "TYPE_BAD_REQUEST", { enumerable: true, get: function () { return names_1.TYPE_BAD_REQUEST; } });
+Object.defineProperty(exports, "TYPE_DAILY_QUOTA_EXCEEDED", { enumerable: true, get: function () { return names_1.TYPE_DAILY_QUOTA_EXCEEDED; } });
+Object.defineProperty(exports, "TYPE_DEADLINE_EXPIRED", { enumerable: true, get: function () { return names_1.TYPE_DEADLINE_EXPIRED; } });
+Object.defineProperty(exports, "TYPE_MONTHLY_QUOTA_EXCEEDED", { enumerable: true, get: function () { return names_1.TYPE_MONTHLY_QUOTA_EXCEEDED; } });
+Object.defineProperty(exports, "TYPE_NOT_BOUND", { enumerable: true, get: function () { return names_1.TYPE_NOT_BOUND; } });
+Object.defineProperty(exports, "TYPE_NOT_FOUND", { enumerable: true, get: function () { return names_1.TYPE_NOT_FOUND; } });
+Object.defineProperty(exports, "TYPE_NO_DEADLINE", { enumerable: true, get: function () { return names_1.TYPE_NO_DEADLINE; } });
+Object.defineProperty(exports, "TYPE_QUOTA_EXCEEDED", { enumerable: true, get: function () { return names_1.TYPE_QUOTA_EXCEEDED; } });
+Object.defineProperty(exports, "TYPE_RATE_LIMITED", { enumerable: true, get: function () { return names_1.TYPE_RATE_LIMITED; } });
+Object.defineProperty(exports, "TYPE_SCHEMA_REJECTED", { enumerable: true, get: function () { return names_1.TYPE_SCHEMA_REJECTED; } });
+Object.defineProperty(exports, "TYPE_SERVER_ERROR", { enumerable: true, get: function () { return names_1.TYPE_SERVER_ERROR; } });
+Object.defineProperty(exports, "TYPE_UNAVAILABLE", { enumerable: true, get: function () { return names_1.TYPE_UNAVAILABLE; } });
+Object.defineProperty(exports, "TYPE_UNKNOWN", { enumerable: true, get: function () { return names_1.TYPE_UNKNOWN; } });
+Object.defineProperty(exports, "TYPE_WRITE_FAILED", { enumerable: true, get: function () { return names_1.TYPE_WRITE_FAILED; } });
+Object.defineProperty(exports, "TYPE_WRITE_NOT_FOUND", { enumerable: true, get: function () { return names_1.TYPE_WRITE_NOT_FOUND; } });
+Object.defineProperty(exports, "TYPE_WRITE_TIMEOUT", { enumerable: true, get: function () { return names_1.TYPE_WRITE_TIMEOUT; } });
+exports.NON_RETRYABLE_TYPES = [
+    names_1.TYPE_MONTHLY_QUOTA_EXCEEDED,
+    names_1.TYPE_QUOTA_EXCEEDED,
+    names_1.TYPE_AUTH_FAILED,
+    names_1.TYPE_NOT_FOUND,
+    names_1.TYPE_BAD_REQUEST,
+    names_1.TYPE_SCHEMA_REJECTED,
+    names_1.TYPE_WRITE_FAILED,
+    names_1.TYPE_WRITE_NOT_FOUND,
+    names_1.TYPE_WRITE_TIMEOUT,
+    names_1.TYPE_BAD_OPTIONS,
+    names_1.TYPE_NOT_BOUND,
+    names_1.TYPE_NO_DEADLINE,
+];
+/**
+ * A server-supplied code, if this package recognises it.
+ *
+ * The code outlives the request in the Worker log and in failure `details`, which
+ * Temporal persists in the clear — and a shape test is no defence, since a leaked
+ * key looks exactly like an identifier. So only codes this module branches on are
+ * echoed; the rest become a fixed marker, not a digest (an unsalted hash of a
+ * low-entropy value is recoverable, and leaks equality). Matching uses the raw value.
+ */
+const UNRECOGNIZED = '<unrecognized>';
+function safeCode(code) {
+    if (typeof code !== 'string')
+        return null;
+    return KNOWN_CODES.has(code) ? code : UNRECOGNIZED;
+}
+// Fixed, history-safe messages. Never include the raw exception string.
+const MESSAGES = {
+    [names_1.TYPE_UNAVAILABLE]: 'xmemory is unreachable',
+    [names_1.TYPE_SERVER_ERROR]: 'xmemory returned a server error',
+    [names_1.TYPE_RATE_LIMITED]: 'xmemory rate-limited the request',
+    [names_1.TYPE_DAILY_QUOTA_EXCEEDED]: 'xmemory daily quota exceeded',
+    [names_1.TYPE_MONTHLY_QUOTA_EXCEEDED]: 'xmemory monthly quota exceeded',
+    [names_1.TYPE_QUOTA_EXCEEDED]: 'xmemory quota exceeded',
+    [names_1.TYPE_AUTH_FAILED]: 'xmemory rejected the credentials',
+    [names_1.TYPE_NOT_FOUND]: 'xmemory resource not found',
+    [names_1.TYPE_BAD_REQUEST]: 'xmemory rejected the request as invalid',
+    [names_1.TYPE_SCHEMA_REJECTED]: 'xmemory rejected the schema change',
+    [names_1.TYPE_UNKNOWN]: 'xmemory returned an unrecognized error',
+};
+// 9999-12-31T23:59:59Z, where protobuf's Timestamp ends: a retry scheduled past it
+// cannot be represented, and the server refuses the failure that carries it.
+const MAX_TIMESTAMP_MS = 253_402_300_799_000;
+const RETRYABLE_CODES = new Set(['INTERNAL_ERROR', 'SERVICE_UNAVAILABLE']);
+const AUTH_CODES = new Set(['UNAUTHORIZED', 'FORBIDDEN']);
+const BAD_REQUEST_CODES = new Set(['VALIDATION_ERROR', 'INVALID_INPUT', 'ALREADY_EXISTS', 'CONFLICT']);
+// A queued write that exhausted its own retry budget; retrying cannot help.
+const EXHAUSTED_CODES = new Set(['MAX_RETRIES_EXCEEDED']);
+const SCHEMA_CODES = new Set([
+    'stale_proposal_version',
+    'stale_schema_version',
+    'dependency_closure_failed',
+    'destructive_confirmation_required',
+    'non_additive_change_requires_plan',
+    'migration_not_found',
+    'instance_not_initialised',
+]);
+/**
+ * The server's pacing hint in milliseconds, or `undefined` when Temporal cannot
+ * carry it. Never clamped — the Activity's own policy bounds the retrying.
+ *
+ * Sent as a number, not a `<n>s` string: the string form goes through a duration
+ * parser that rejects exponent notation. Dropped only when unusable — `Infinity`,
+ * past `MAX_SAFE_INTEGER` milliseconds where the int64 conversion saturates, or a
+ * delay landing past protobuf's 9999-12-31 Timestamp ceiling, which the server
+ * rejects when the failure is reported.
+ */
+// Every code this module branches on. Nothing else is ever echoed.
+const KNOWN_CODES = new Set([
+    ...RETRYABLE_CODES,
+    ...AUTH_CODES,
+    ...BAD_REQUEST_CODES,
+    ...EXHAUSTED_CODES,
+    ...SCHEMA_CODES,
+    'QUOTA_EXCEEDED',
+    'RATE_LIMITED',
+    'NOT_FOUND',
+]);
+function retryDelayMs(err) {
+    const detail = (err.details ?? {});
+    // Each source judged on its own: preferring the header and validating afterwards
+    // discarded a good structured hint whenever the header was unusable.
+    for (const hint of [err.retryAfter, detail.retry_after_seconds]) {
+        const ms = usableDelayMs(hint);
+        if (ms !== undefined)
+            return ms;
+    }
+    return undefined;
+}
+/** A hint in milliseconds, or `undefined` when Temporal could not carry it. */
+function usableDelayMs(hint) {
+    if (typeof hint !== 'number' || hint <= 0)
+        return undefined;
+    const ms = Math.round(hint * 1000);
+    if (!Number.isSafeInteger(ms) || ms < 1)
+        return undefined;
+    if (ms > MAX_TIMESTAMP_MS - Date.now())
+        return undefined;
+    return ms;
+}
+function quotaVerdict(err) {
+    const detail = (err.details ?? {});
+    const kind = detail.kind;
+    // A daily window resets within hours and is worth retrying; a monthly one is not.
+    // An unknown kind falls back to non-retryable.
+    if (kind === 'daily_quota_exceeded')
+        return { type: names_1.TYPE_DAILY_QUOTA_EXCEEDED, retryable: true };
+    if (kind === 'monthly_quota_exceeded')
+        return { type: names_1.TYPE_MONTHLY_QUOTA_EXCEEDED, retryable: false };
+    return { type: names_1.TYPE_QUOTA_EXCEEDED, retryable: false };
+}
+function verdictFromStatus(status) {
+    if (status === undefined)
+        return { type: names_1.TYPE_UNAVAILABLE, retryable: true };
+    if (status === 408 || status >= 500)
+        return { type: names_1.TYPE_SERVER_ERROR, retryable: true };
+    if (status === 429)
+        return { type: names_1.TYPE_RATE_LIMITED, retryable: true };
+    if (status === 401 || status === 403)
+        return { type: names_1.TYPE_AUTH_FAILED, retryable: false };
+    if (status === 404)
+        return { type: names_1.TYPE_NOT_FOUND, retryable: false };
+    if (status >= 400)
+        return { type: names_1.TYPE_BAD_REQUEST, retryable: false };
+    return { type: names_1.TYPE_UNKNOWN, retryable: true };
+}
+function build(type, retryable, code = null, status = null, delayMs) {
+    return common_1.ApplicationFailure.create({
+        message: MESSAGES[type] ?? 'xmemory request failed',
+        type,
+        nonRetryable: !retryable,
+        // `retryAfterSeconds` rides in details as well as in nextRetryDelay: the SDK
+        // encodes the latter for the server's retry scheduling but drops it when
+        // decoding the failure back into workflow code, where the durable-write loop
+        // needs it to pace its own polling. Details survive that round trip.
+        details: [{ code, status, ...(delayMs !== undefined ? { retryAfterSeconds: delayMs / 1000 } : {}) }],
+        nextRetryDelay: retryable && delayMs !== undefined ? delayMs : undefined,
+    });
+}
+/**
+ * Whether a non-API error is a `fetch` network failure rather than a bug.
+ *
+ * Undici raises `TypeError('fetch failed', { cause })` for DNS failures,
+ * refused connections, and resets; a programming TypeError carries no `cause`.
+ * An `AbortError` from the client's own timeout is a `DOMException`, so it does
+ * not reach here.
+ */
+function isNetworkError(err) {
+    return err instanceof TypeError && Object.hasOwn(err, 'cause');
+}
+/**
+ * Whether this is the client's own API error. `instanceof` alone is not enough:
+ * xmemory ships CJS and ESM builds, so a handle from the other half throws a
+ * different class object and an auth failure looked like a transport blip.
+ */
+function isApiError(err) {
+    return err instanceof xmemory_1.XmemoryAPIError || (err instanceof Error && err.name === 'XmemoryAPIError');
+}
+/** Map any client-raised error onto a Temporal `ApplicationFailure`. */
+function toApplicationFailure(err) {
+    if (!isApiError(err)) {
+        // Not an API error: a transport failure (retryable) or a deterministic
+        // client-side error (non-retryable — a retry replays the same input). The
+        // raw message is never echoed (it may embed internal transport details).
+        //
+        // `fetch` rejects a network failure (DNS, refused, reset) with a TypeError,
+        // and the client does not wrap it, so a bare `instanceof TypeError` would
+        // make a transient blip permanently fatal. Undici sets `cause` on those and
+        // never on a programming TypeError, which is the discriminator.
+        if (isNetworkError(err))
+            return build(names_1.TYPE_UNAVAILABLE, true);
+        if (err instanceof TypeError || err instanceof RangeError || err instanceof SyntaxError) {
+            return build(names_1.TYPE_BAD_REQUEST, false);
+        }
+        return build(names_1.TYPE_UNAVAILABLE, true);
+    }
+    const { code, status } = err;
+    let verdict;
+    if (code === 'QUOTA_EXCEEDED')
+        verdict = quotaVerdict(err);
+    else if (code === 'RATE_LIMITED')
+        verdict = { type: names_1.TYPE_RATE_LIMITED, retryable: true };
+    else if (code && RETRYABLE_CODES.has(code))
+        verdict = { type: names_1.TYPE_SERVER_ERROR, retryable: true };
+    else if (code && AUTH_CODES.has(code))
+        verdict = { type: names_1.TYPE_AUTH_FAILED, retryable: false };
+    else if (code === 'NOT_FOUND')
+        verdict = { type: names_1.TYPE_NOT_FOUND, retryable: false };
+    else if (code && BAD_REQUEST_CODES.has(code))
+        verdict = { type: names_1.TYPE_BAD_REQUEST, retryable: false };
+    else if (code && EXHAUSTED_CODES.has(code))
+        verdict = { type: names_1.TYPE_WRITE_FAILED, retryable: false };
+    else if (code && SCHEMA_CODES.has(code))
+        verdict = { type: names_1.TYPE_SCHEMA_REJECTED, retryable: false };
+    else if (code) {
+        // Almost certainly a newer server: keep the type so the gap is findable, but
+        // take retryability from the status — a 401 is terminal whatever the code says.
+        // No status at all still gets the benefit of the doubt.
+        console.warn(`xmemory returned an unrecognized error code ${JSON.stringify(safeCode(code))} (HTTP ${status})`);
+        verdict = { type: names_1.TYPE_UNKNOWN, retryable: verdictFromStatus(status).retryable };
+    }
+    else {
+        verdict = verdictFromStatus(status);
+    }
+    const delay = verdict.retryable ? retryDelayMs(err) : undefined;
+    return build(verdict.type, verdict.retryable, safeCode(code), status ?? null, delay);
+}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Temporal plugin for xmemory — durable agent memory as Temporal Activities.
+ *
+ * Add {@link XmemoryPlugin} to your Temporal Worker. Workflow code imports its
+ * side of the API from `@xmemory/temporal/workflow`, a leaf that pulls in no
+ * Activity or client code, so Temporal's workflow bundler accepts it.
+ */
+export { XmemoryPlugin, PLUGIN_NAME } from './plugin';
+export type { XmemoryPluginOptions } from './plugin';
+export type { XmemoryConfig } from './config';
+export { DEFAULT_TIMEOUTS, DEFAULT_CLIENT_MARGIN_MS } from './defaults';
+export type { XmemoryTimeouts } from './defaults';
+export type { WorkflowXmemory, WorkflowXmemoryOptions, WriteDurableOptions, WriteStatusRetry } from './workflow';
+export type { AutoCaptureConfig } from './interceptor';
+export { TYPE_AUTH_FAILED, TYPE_BAD_OPTIONS, TYPE_BAD_REQUEST, TYPE_DAILY_QUOTA_EXCEEDED, TYPE_DEADLINE_EXPIRED, TYPE_MONTHLY_QUOTA_EXCEEDED, TYPE_NOT_BOUND, TYPE_NOT_FOUND, TYPE_NO_DEADLINE, TYPE_QUOTA_EXCEEDED, TYPE_RATE_LIMITED, TYPE_SCHEMA_REJECTED, TYPE_SERVER_ERROR, TYPE_UNAVAILABLE, TYPE_UNKNOWN, TYPE_WRITE_FAILED, TYPE_WRITE_NOT_FOUND, TYPE_WRITE_TIMEOUT, } from './errors';

package/dist/index.js

@@ -0,0 +1,38 @@
+"use strict";
+/**
+ * Temporal plugin for xmemory — durable agent memory as Temporal Activities.
+ *
+ * Add {@link XmemoryPlugin} to your Temporal Worker. Workflow code imports its
+ * side of the API from `@xmemory/temporal/workflow`, a leaf that pulls in no
+ * Activity or client code, so Temporal's workflow bundler accepts it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TYPE_WRITE_TIMEOUT = exports.TYPE_WRITE_NOT_FOUND = exports.TYPE_WRITE_FAILED = exports.TYPE_UNKNOWN = exports.TYPE_UNAVAILABLE = exports.TYPE_SERVER_ERROR = exports.TYPE_SCHEMA_REJECTED = exports.TYPE_RATE_LIMITED = exports.TYPE_QUOTA_EXCEEDED = exports.TYPE_NO_DEADLINE = exports.TYPE_NOT_FOUND = exports.TYPE_NOT_BOUND = exports.TYPE_MONTHLY_QUOTA_EXCEEDED = exports.TYPE_DEADLINE_EXPIRED = exports.TYPE_DAILY_QUOTA_EXCEEDED = exports.TYPE_BAD_REQUEST = exports.TYPE_BAD_OPTIONS = exports.TYPE_AUTH_FAILED = exports.DEFAULT_CLIENT_MARGIN_MS = exports.DEFAULT_TIMEOUTS = exports.PLUGIN_NAME = exports.XmemoryPlugin = void 0;
+var plugin_1 = require("./plugin");
+Object.defineProperty(exports, "XmemoryPlugin", { enumerable: true, get: function () { return plugin_1.XmemoryPlugin; } });
+Object.defineProperty(exports, "PLUGIN_NAME", { enumerable: true, get: function () { return plugin_1.PLUGIN_NAME; } });
+var defaults_1 = require("./defaults");
+Object.defineProperty(exports, "DEFAULT_TIMEOUTS", { enumerable: true, get: function () { return defaults_1.DEFAULT_TIMEOUTS; } });
+Object.defineProperty(exports, "DEFAULT_CLIENT_MARGIN_MS", { enumerable: true, get: function () { return defaults_1.DEFAULT_CLIENT_MARGIN_MS; } });
+// The `type` strings themselves, so a consumer can match on them in a
+// RetryPolicy without hard-coding literals. The export map has no deep-import
+// escape hatch, so anything a caller needs has to leave through here.
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "TYPE_AUTH_FAILED", { enumerable: true, get: function () { return errors_1.TYPE_AUTH_FAILED; } });
+Object.defineProperty(exports, "TYPE_BAD_OPTIONS", { enumerable: true, get: function () { return errors_1.TYPE_BAD_OPTIONS; } });
+Object.defineProperty(exports, "TYPE_BAD_REQUEST", { enumerable: true, get: function () { return errors_1.TYPE_BAD_REQUEST; } });
+Object.defineProperty(exports, "TYPE_DAILY_QUOTA_EXCEEDED", { enumerable: true, get: function () { return errors_1.TYPE_DAILY_QUOTA_EXCEEDED; } });
+Object.defineProperty(exports, "TYPE_DEADLINE_EXPIRED", { enumerable: true, get: function () { return errors_1.TYPE_DEADLINE_EXPIRED; } });
+Object.defineProperty(exports, "TYPE_MONTHLY_QUOTA_EXCEEDED", { enumerable: true, get: function () { return errors_1.TYPE_MONTHLY_QUOTA_EXCEEDED; } });
+Object.defineProperty(exports, "TYPE_NOT_BOUND", { enumerable: true, get: function () { return errors_1.TYPE_NOT_BOUND; } });
+Object.defineProperty(exports, "TYPE_NOT_FOUND", { enumerable: true, get: function () { return errors_1.TYPE_NOT_FOUND; } });
+Object.defineProperty(exports, "TYPE_NO_DEADLINE", { enumerable: true, get: function () { return errors_1.TYPE_NO_DEADLINE; } });
+Object.defineProperty(exports, "TYPE_QUOTA_EXCEEDED", { enumerable: true, get: function () { return errors_1.TYPE_QUOTA_EXCEEDED; } });
+Object.defineProperty(exports, "TYPE_RATE_LIMITED", { enumerable: true, get: function () { return errors_1.TYPE_RATE_LIMITED; } });
+Object.defineProperty(exports, "TYPE_SCHEMA_REJECTED", { enumerable: true, get: function () { return errors_1.TYPE_SCHEMA_REJECTED; } });
+Object.defineProperty(exports, "TYPE_SERVER_ERROR", { enumerable: true, get: function () { return errors_1.TYPE_SERVER_ERROR; } });
+Object.defineProperty(exports, "TYPE_UNAVAILABLE", { enumerable: true, get: function () { return errors_1.TYPE_UNAVAILABLE; } });
+Object.defineProperty(exports, "TYPE_UNKNOWN", { enumerable: true, get: function () { return errors_1.TYPE_UNKNOWN; } });
+Object.defineProperty(exports, "TYPE_WRITE_FAILED", { enumerable: true, get: function () { return errors_1.TYPE_WRITE_FAILED; } });
+Object.defineProperty(exports, "TYPE_WRITE_NOT_FOUND", { enumerable: true, get: function () { return errors_1.TYPE_WRITE_NOT_FOUND; } });
+Object.defineProperty(exports, "TYPE_WRITE_TIMEOUT", { enumerable: true, get: function () { return errors_1.TYPE_WRITE_TIMEOUT; } });

package/dist/interceptor.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Opt-in auto-capture of activity results into xmemory.
+ *
+ * An *activity* interceptor, not a workflow one: workflow interceptors re-run on
+ * every replay, so I/O there breaks determinism.
+ *
+ * Guardrails: `project` decides what to remember, `sampleRate` bounds fan-out,
+ * capture is clamped to what is left of the activity's deadline, and a capture
+ * failure never fails that activity.
+ */
+import type { ActivityInboundCallsInterceptor } from '@temporalio/worker';
+import type { InstanceHolder } from './activities';
+import type { XmemoryConfig } from './config';
+export interface AutoCaptureConfig {
+    /**
+     * What to remember from a completed activity, or `undefined` to skip it.
+     *
+     * No default: raw payloads are JSON blobs the extraction engine cannot use.
+     */
+    project: (activityName: string, result: unknown) => string | undefined | null;
+    /** Fraction of eligible activities to capture, in [0, 1]. Defaults to 1. */
+    sampleRate?: number;
+    extractionLogic?: 'fast' | 'deep';
+    /**
+     * Ceiling (ms) a capture may add to the wrapped activity. Lowered further when
+     * less than this is left of the activity's deadline.
+     */
+    captureTimeoutMs?: number;
+}
+/**
+ * Milliseconds capture may take, or `null` when it must be skipped.
+ *
+ * Capture spends the wrapped Activity's deadline, so an Activity that has nearly
+ * used its budget would be pushed past it and retried, discarding a result it had
+ * already produced.
+ */
+export declare function captureBudgetMs(remainingMs: number, ceilingMs: number, marginMs: number): number | null;
+export declare function createAutoCaptureInterceptor(holder: InstanceHolder, config: XmemoryConfig, autoCapture: AutoCaptureConfig): ActivityInboundCallsInterceptor;

package/dist/interceptor.js

@@ -0,0 +1,113 @@
+"use strict";
+/**
+ * Opt-in auto-capture of activity results into xmemory.
+ *
+ * An *activity* interceptor, not a workflow one: workflow interceptors re-run on
+ * every replay, so I/O there breaks determinism.
+ *
+ * Guardrails: `project` decides what to remember, `sampleRate` bounds fan-out,
+ * capture is clamped to what is left of the activity's deadline, and a capture
+ * failure never fails that activity.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.captureBudgetMs = captureBudgetMs;
+exports.createAutoCaptureInterceptor = createAutoCaptureInterceptor;
+const activity_1 = require("@temporalio/activity");
+const deadline_1 = require("./deadline");
+const defaults_1 = require("./defaults");
+// Never capture our own writes, or capture recurses. This also skips a user
+// activity named `xmemory_*` — see the README's auto-capture section.
+const OWN_ACTIVITY_PREFIX = 'xmemory_';
+/**
+ * Milliseconds capture may take, or `null` when it must be skipped.
+ *
+ * Capture spends the wrapped Activity's deadline, so an Activity that has nearly
+ * used its budget would be pushed past it and retried, discarding a result it had
+ * already produced.
+ */
+function captureBudgetMs(remainingMs, ceilingMs, marginMs) {
+    // A margin of zero or less would leave no completion gap, or hand capture more
+    // time than the Activity has left. Fall back to a proportional reserve.
+    const usable = Number.isFinite(marginMs) && marginMs > 0 ? remainingMs - marginMs : remainingMs * 0.8;
+    if (usable <= 0 || !(ceilingMs > 0))
+        return null;
+    // Capped like every client budget: a Node timer past it fires after 1ms.
+    return Math.min(ceilingMs, usable, defaults_1.MAX_DURATION_MS);
+}
+function createAutoCaptureInterceptor(holder, config, autoCapture) {
+    const sampleRate = autoCapture.sampleRate ?? 1;
+    const extractionLogic = autoCapture.extractionLogic ?? 'fast';
+    const ceilingMs = autoCapture.captureTimeoutMs ?? 5000;
+    const marginMs = config.clientMarginMs ?? defaults_1.DEFAULT_CLIENT_MARGIN_MS;
+    return {
+        async execute(input, next) {
+            const started = performance.now();
+            const result = await next(input);
+            try {
+                await maybeCapture(result, started);
+            }
+            catch {
+                // Capture must never fail the wrapped activity: errors and timeouts alike.
+                console.warn('xmemory auto-capture skipped; the wrapped activity is unaffected');
+            }
+            return result;
+        },
+    };
+    async function maybeCapture(result, started) {
+        const info = activity_1.Context.current().info;
+        const name = info.activityType;
+        if (name.startsWith(OWN_ACTIVITY_PREFIX))
+            return;
+        if (!shouldSample())
+            return;
+        // Budget before projecting: `project` is the caller's code and can itself be
+        // slow enough to push the Activity past its deadline.
+        const budgetMs = captureBudgetMs(remainingMs(info, started), ceilingMs, marginMs);
+        if (budgetMs === null)
+            return;
+        const text = autoCapture.project(name, result);
+        if (!text)
+            return;
+        if (typeof text !== 'string') {
+            // `writeAsync` is overloaded on its first argument, so an array would be
+            // applied as structured mutations rather than remembered. Skipped, like every
+            // capture problem: it never affects the wrapped Activity.
+            console.warn(`xmemory auto-capture skipped: project() returned a ${typeof text}, expected a string`);
+            return;
+        }
+        // Re-checked, because the projector just spent some of the same budget.
+        const enqueueMs = captureBudgetMs(remainingMs(info, started), ceilingMs, marginMs);
+        if (enqueueMs === null)
+            return;
+        // Enqueue, not a full write: waiting for extraction would add its latency to
+        // the activity's budget. Two bounds because `timeoutMs` stops at headers and
+        // `withDeadline` caps the total.
+        await (0, deadline_1.withDeadline)(holder.get().writeAsync(text, { extractionLogic, timeoutMs: enqueueMs }), enqueueMs);
+    }
+    /**
+     * What is left of the wrapped Activity's deadline, or zero when it has none.
+     *
+     * `started` is stamped before the Activity runs, so the elapsed figure covers it
+     * and every interceptor inside this one. Handed to `activityBudgetMs` rather than
+     * subtracted here, since only the start-to-close bound needs it.
+     */
+    function remainingMs(info, started) {
+        return (0, deadline_1.activityBudgetMs)(info, performance.now() - started) ?? 0;
+    }
+    function shouldSample() {
+        if (sampleRate >= 1)
+            return true;
+        if (sampleRate <= 0)
+            return false;
+        // Keyed on the run as well as the activity: `activityId` restarts at "1" in
+        // every workflow, so hashing it alone bucketed them all together.
+        const info = activity_1.Context.current().info;
+        const id = `${info.workflowExecution?.runId ?? ''}/${info.activityId}`;
+        let hash = 0;
+        for (let i = 0; i < id.length; i++)
+            hash = (hash * 31 + id.charCodeAt(i)) >>> 0;
+        // A million buckets, so a rate below 1/1000 still works. Low bits: this
+        // accumulator mixes them well, its high bits barely move across similar ids.
+        return (hash % 1_000_000) / 1_000_000 < sampleRate;
+    }
+}

package/dist/names.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Activity name constants, in a leaf module with no client imports.
+ *
+ * The workflow bundle imports these; keeping them here (rather than in
+ * `activities.ts`, which imports the xmemory client) keeps the client out of
+ * the workflow sandbox bundle.
+ */
+export declare const ACTIVITY_READ = "xmemory_read";
+export declare const ACTIVITY_WRITE = "xmemory_write";
+export declare const ACTIVITY_WRITE_START = "xmemory_write_start";
+export declare const ACTIVITY_WRITE_STATUS = "xmemory_write_status";
+export declare const TYPE_WRITE_FAILED = "XmemoryWriteFailed";
+export declare const TYPE_WRITE_NOT_FOUND = "XmemoryWriteNotFound";
+export declare const TYPE_WRITE_TIMEOUT = "XmemoryWriteTimeout";
+export declare const TYPE_BAD_OPTIONS = "XmemoryBadOptions";
+export declare const TYPE_UNAVAILABLE = "XmemoryUnavailable";
+export declare const TYPE_SERVER_ERROR = "XmemoryServerError";
+export declare const TYPE_RATE_LIMITED = "XmemoryRateLimited";
+export declare const TYPE_DAILY_QUOTA_EXCEEDED = "XmemoryDailyQuotaExceeded";
+export declare const TYPE_MONTHLY_QUOTA_EXCEEDED = "XmemoryMonthlyQuotaExceeded";
+export declare const TYPE_QUOTA_EXCEEDED = "XmemoryQuotaExceeded";
+export declare const TYPE_AUTH_FAILED = "XmemoryAuthFailed";
+export declare const TYPE_NOT_FOUND = "XmemoryNotFound";
+export declare const TYPE_BAD_REQUEST = "XmemoryBadRequest";
+export declare const TYPE_SCHEMA_REJECTED = "XmemorySchemaRejected";
+export declare const TYPE_NOT_BOUND = "XmemoryNotBound";
+export declare const TYPE_NO_DEADLINE = "XmemoryNoDeadline";
+export declare const TYPE_DEADLINE_EXPIRED = "XmemoryDeadlineExpired";
+export declare const TYPE_UNKNOWN = "XmemoryUnknown";

package/dist/names.js

@@ -0,0 +1,47 @@
+"use strict";
+/**
+ * Activity name constants, in a leaf module with no client imports.
+ *
+ * The workflow bundle imports these; keeping them here (rather than in
+ * `activities.ts`, which imports the xmemory client) keeps the client out of
+ * the workflow sandbox bundle.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TYPE_UNKNOWN = exports.TYPE_DEADLINE_EXPIRED = exports.TYPE_NO_DEADLINE = exports.TYPE_NOT_BOUND = exports.TYPE_SCHEMA_REJECTED = exports.TYPE_BAD_REQUEST = exports.TYPE_NOT_FOUND = exports.TYPE_AUTH_FAILED = exports.TYPE_QUOTA_EXCEEDED = exports.TYPE_MONTHLY_QUOTA_EXCEEDED = exports.TYPE_DAILY_QUOTA_EXCEEDED = exports.TYPE_RATE_LIMITED = exports.TYPE_SERVER_ERROR = exports.TYPE_UNAVAILABLE = exports.TYPE_BAD_OPTIONS = exports.TYPE_WRITE_TIMEOUT = exports.TYPE_WRITE_NOT_FOUND = exports.TYPE_WRITE_FAILED = exports.ACTIVITY_WRITE_STATUS = exports.ACTIVITY_WRITE_START = exports.ACTIVITY_WRITE = exports.ACTIVITY_READ = void 0;
+exports.ACTIVITY_READ = 'xmemory_read';
+exports.ACTIVITY_WRITE = 'xmemory_write';
+exports.ACTIVITY_WRITE_START = 'xmemory_write_start';
+exports.ACTIVITY_WRITE_STATUS = 'xmemory_write_status';
+// Job-level write outcomes raised by the durable poll loop (workflow.ts). A
+// public `RetryPolicy.nonRetryableErrorTypes` contract; kept in this client-free
+// leaf so the workflow bundle can import them without pulling the client in, and
+// re-exported from errors.ts so the full type= set lives in one logical place.
+exports.TYPE_WRITE_FAILED = 'XmemoryWriteFailed';
+exports.TYPE_WRITE_NOT_FOUND = 'XmemoryWriteNotFound';
+exports.TYPE_WRITE_TIMEOUT = 'XmemoryWriteTimeout';
+// A caller's own durable-write options are unusable. Non-retryable: the same
+// arguments would be rejected identically on every attempt.
+exports.TYPE_BAD_OPTIONS = 'XmemoryBadOptions';
+// Stable `type` strings — a public contract for
+// `RetryPolicy.nonRetryableErrorTypes`. Renaming one is a breaking change.
+exports.TYPE_UNAVAILABLE = 'XmemoryUnavailable';
+exports.TYPE_SERVER_ERROR = 'XmemoryServerError';
+exports.TYPE_RATE_LIMITED = 'XmemoryRateLimited';
+exports.TYPE_DAILY_QUOTA_EXCEEDED = 'XmemoryDailyQuotaExceeded';
+exports.TYPE_MONTHLY_QUOTA_EXCEEDED = 'XmemoryMonthlyQuotaExceeded';
+exports.TYPE_QUOTA_EXCEEDED = 'XmemoryQuotaExceeded';
+exports.TYPE_AUTH_FAILED = 'XmemoryAuthFailed';
+exports.TYPE_NOT_FOUND = 'XmemoryNotFound';
+exports.TYPE_BAD_REQUEST = 'XmemoryBadRequest';
+exports.TYPE_SCHEMA_REJECTED = 'XmemorySchemaRejected';
+exports.TYPE_NOT_BOUND = 'XmemoryNotBound';
+// Worker-side misconfiguration raised by activities.ts, kept distinct from
+// NotBound because the remedy differs: one is a missing plugin registration, the
+// other an activity scheduled with neither close timeout.
+exports.TYPE_NO_DEADLINE = 'XmemoryNoDeadline';
+// The Activity's deadline is already spent. Retryable: Temporal decides whether
+// another attempt still fits, and failing here only avoids a doomed request.
+exports.TYPE_DEADLINE_EXPIRED = 'XmemoryDeadlineExpired';
+exports.TYPE_UNKNOWN = 'XmemoryUnknown';
+// Re-export the durable-write outcome types (defined in the client-free leaf) so
+// the full `type=` set is reachable from one module.

package/dist/plugin.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `XmemoryPlugin` — the single line a Temporal user adds to their Worker.
+ *
+ * `configureWorker` injects the activities (and the auto-capture interceptor,
+ * if enabled); `runWorker` opens one xmemory client for the Worker's lifetime.
+ * Installs no data converter: one would rewrite every payload on the Worker,
+ * not just xmemory's.
+ *
+ * Use one plugin instance per Worker. The bound client lives in a per-plugin
+ * holder, so reusing one object across Workers is last-bind-wins.
+ */
+import type { Worker, WorkerOptions, WorkerPlugin } from '@temporalio/worker';
+import { type XmemoryConfig } from './config';
+import { type AutoCaptureConfig } from './interceptor';
+export declare const PLUGIN_NAME = "xmemory";
+export interface XmemoryPluginOptions {
+    /** Provide the API key in-process instead of via the env var. */
+    apiKey?: string;
+    /** Enable auto-capture of activity results into memory. Off by default. */
+    autoCapture?: AutoCaptureConfig;
+}
+export declare class XmemoryPlugin implements WorkerPlugin {
+    #private;
+    readonly name = "xmemory";
+    constructor(config: XmemoryConfig, options?: XmemoryPluginOptions);
+    /** The in-process key, if one was supplied. Never serialized with the plugin. */
+    private apiKey;
+    configureWorker(options: WorkerOptions): WorkerOptions;
+    runWorker(worker: Worker, next: (w: Worker) => Promise<void>): Promise<void>;
+    private buildInstance;
+}

package/dist/plugin.js

@@ -0,0 +1,81 @@
+"use strict";
+/**
+ * `XmemoryPlugin` — the single line a Temporal user adds to their Worker.
+ *
+ * `configureWorker` injects the activities (and the auto-capture interceptor,
+ * if enabled); `runWorker` opens one xmemory client for the Worker's lifetime.
+ * Installs no data converter: one would rewrite every payload on the Worker,
+ * not just xmemory's.
+ *
+ * Use one plugin instance per Worker. The bound client lives in a per-plugin
+ * holder, so reusing one object across Workers is last-bind-wins.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.XmemoryPlugin = exports.PLUGIN_NAME = void 0;
+const xmemory_1 = require("xmemory");
+const activities_1 = require("./activities");
+const config_1 = require("./config");
+const defaults_1 = require("./defaults");
+const interceptor_1 = require("./interceptor");
+exports.PLUGIN_NAME = 'xmemory';
+class XmemoryPlugin {
+    name = exports.PLUGIN_NAME;
+    // ECMAScript private fields throughout: TypeScript `private` is an ordinary
+    // enumerable property at runtime, so JSON.stringify(plugin) printed the API key,
+    // the endpoint, and anything an injected instance carried.
+    #holder = new activities_1.InstanceHolder();
+    #apiKey;
+    #options;
+    #config;
+    constructor(config, options = {}) {
+        this.#config = config;
+        const { apiKey, ...rest } = options;
+        this.#apiKey = apiKey;
+        this.#options = rest;
+    }
+    /** The in-process key, if one was supplied. Never serialized with the plugin. */
+    apiKey() {
+        return this.#apiKey;
+    }
+    configureWorker(options) {
+        const ourActivities = (0, activities_1.createActivities)(this.#holder, this.#config);
+        // Refused, not merged over: replacing an identically-named Activity would
+        // change what the caller's workflows execute. `hasOwn`, not `in`, so an
+        // Activity named `constructor` is not a false collision.
+        const taken = Object.keys(options.activities ?? {}).filter((name) => Object.hasOwn(ourActivities, name));
+        if (taken.length > 0) {
+            throw new Error(`xmemory plugin: the Worker already registers ${taken.join(', ')}. ` +
+                'Those names belong to this plugin; rename the conflicting activities.');
+        }
+        const activities = { ...(options.activities ?? {}), ...ourActivities };
+        // Only auto-capture registers an interceptor, and only when enabled.
+        if (!this.#options.autoCapture)
+            return { ...options, activities };
+        const autoCapture = this.#options.autoCapture;
+        const holder = this.#holder;
+        const config = this.#config;
+        const interceptors = {
+            ...options.interceptors,
+            activityInbound: [
+                () => (0, interceptor_1.createAutoCaptureInterceptor)(holder, config, autoCapture),
+                ...(options.interceptors?.activityInbound ?? []),
+            ],
+        };
+        return { ...options, activities, interceptors };
+    }
+    async runWorker(worker, next) {
+        this.#holder.bind(this.#options.instance ?? this.buildInstance());
+        await next(worker);
+    }
+    buildInstance() {
+        const client = new xmemory_1.XmemoryClient({
+            apiKey: (0, config_1.resolveApiKey)(this.#config, this.apiKey()),
+            // Always explicit — see `resolveEndpoint`.
+            url: (0, config_1.resolveEndpoint)(this.#config),
+            // A fallback only: every activity overrides this per call.
+            timeoutMs: (0, defaults_1.clientTimeoutMs)(defaults_1.DEFAULT_TIMEOUTS.readMs, this.#config.clientMarginMs),
+        });
+        return client.instance(this.#config.instanceId);
+    }
+}
+exports.XmemoryPlugin = XmemoryPlugin;