@retinue/agentkit 0.1.0

package/dist/worker/main.js

@@ -0,0 +1,159 @@
+export const DEFAULT_WORKER_CONFIG = {
+    concurrency: 4,
+    leaseMs: 30_000,
+    reapEveryMs: 10_000,
+    reapLimit: 20,
+    shutdownGraceMs: 20_000,
+};
+export const createWorkerRuntime = (deps) => {
+    const config = { ...DEFAULT_WORKER_CONFIG, ...deps.config };
+    const log = deps.log ?? (() => { });
+    const timer = deps.setInterval ??
+        ((fn, ms) => {
+            const handle = setInterval(fn, ms);
+            handle.unref?.(); // a reaper timer must never be the reason a process cannot exit
+            return { clear: () => clearInterval(handle) };
+        });
+    let running = false;
+    let inFlight = 0;
+    let processed = 0;
+    let reaped = 0;
+    let reaperTimer = null;
+    /** Resolves when the last in-flight handler finishes. Rebuilt each time the count returns to zero. */
+    let idle = null;
+    const markBusy = () => {
+        inFlight += 1;
+        if (idle === null) {
+            let resolve;
+            const promise = new Promise((r) => {
+                resolve = r;
+            });
+            idle = { promise, resolve };
+        }
+    };
+    const markIdle = () => {
+        inFlight -= 1;
+        if (inFlight === 0 && idle !== null) {
+            idle.resolve();
+            idle = null;
+        }
+    };
+    const handle = async (job) => {
+        markBusy();
+        try {
+            const result = await deps.worker.process(job);
+            processed += 1;
+            deps.onOutcome?.(job, result);
+        }
+        catch (error) {
+            // Swallowed at this boundary on purpose: one failing run must not take the process down, and the
+            // run's own failure state is already recorded by `process`. Surfaced through `onError` so a host
+            // can alert on it.
+            deps.onError?.(job, error);
+            log("run handler threw", { runId: job.runId, error: String(error) });
+        }
+        finally {
+            markIdle();
+        }
+    };
+    /**
+     * One recovery sweep.
+     *
+     * Re-enqueues rather than executing inline, so a reclaimed run goes through exactly the same path as
+     * a fresh one — including the queue's dedup, which is half of why AC-4 needs no reaper-level lock.
+     *
+     * Note what is deliberately *absent*: no guard against two reapers finding the same run.
+     * `reapExpired` is a pure read, so both will, and the exclusion already exists twice — #105's job id
+     * collapses the two enqueues into one job, and #93's `claim` is an atomic lease compare-and-set that
+     * admits one worker regardless. A third guard here would protect something already atomic, and a
+     * stalled holder of it would block recovery entirely.
+     */
+    const reapOnce = async () => {
+        const candidates = await deps.worker.reapExpired(config.reapLimit);
+        for (const run of candidates) {
+            try {
+                await deps.dispatcher.enqueueRun({ tenantId: run.tenantId, runId: run.id });
+                reaped += 1;
+            }
+            catch (error) {
+                // A queue that is down must not stop the sweep: the next sweep will find the same runs, since
+                // nothing has claimed them.
+                log("could not re-enqueue a reaped run", { runId: run.id, error: String(error) });
+            }
+        }
+        if (candidates.length > 0)
+            log(`reaped ${candidates.length} expired run(s)`);
+        return candidates;
+    };
+    return {
+        async start() {
+            if (running)
+                return;
+            running = true;
+            await deps.consumer.start(handle);
+            reaperTimer = timer(() => {
+                void reapOnce().catch((error) => log("reap sweep failed", { error: String(error) }));
+            }, config.reapEveryMs);
+            log("worker started", {
+                concurrency: config.concurrency,
+                leaseMs: config.leaseMs,
+                reapEveryMs: config.reapEveryMs,
+            });
+        },
+        async shutdown(reason) {
+            if (!running)
+                return { graceful: true, exitCode: 0 };
+            running = false;
+            log("shutting down", { reason });
+            // Order matters, and this is the ordering decision worth the whole file. Consumption stops
+            // first, so nothing new is accepted; the reaper stops with it, because re-enqueuing during a
+            // drain hands work to a process that is leaving. Only then do we wait.
+            reaperTimer?.clear();
+            reaperTimer = null;
+            await deps.consumer.stop(config.shutdownGraceMs);
+            let graceful = true;
+            if (inFlight > 0 && idle !== null) {
+                const deadline = new Promise((resolve) => setTimeout(() => resolve("timeout"), config.shutdownGraceMs).unref?.());
+                const outcome = await Promise.race([idle.promise.then(() => "drained"), deadline]);
+                graceful = outcome === "drained";
+            }
+            // Non-zero only on a genuine failure to drain. A rolling deploy that checkpointed a long run
+            // did its job, and a non-zero exit there would make an orchestrator treat a success as a crash.
+            log(graceful ? "drained cleanly" : "grace period elapsed with work in flight", { inFlight });
+            return { graceful, exitCode: graceful ? 0 : 1 };
+        },
+        status() {
+            return { running, inFlight, processed, reaped };
+        },
+        reapOnce,
+    };
+};
+/**
+ * Attach OS signal handlers. Separate from `createWorkerRuntime` on purpose: a library that binds to
+ * `process` merely by being constructed is hostile to embed and to test, and every test here would
+ * otherwise need real signals.
+ */
+export const installSignalHandlers = (runtime, options = {}) => {
+    const target = options.process ?? process;
+    const signals = options.signals ?? ["SIGTERM", "SIGINT"];
+    const onExit = options.onExit ?? ((code) => process.exit(code));
+    let shuttingDown = false;
+    const listeners = signals.map((signal) => {
+        const listener = () => {
+            // A second signal during shutdown is ignored rather than escalating: an impatient orchestrator
+            // sending SIGTERM twice should not abandon a run that is seconds from checkpointing.
+            if (shuttingDown)
+                return;
+            shuttingDown = true;
+            void runtime.shutdown(signal).then(({ exitCode }) => onExit(exitCode));
+        };
+        target.on(signal, listener);
+        return { signal, listener };
+    });
+    return () => {
+        for (const { signal, listener } of listeners) {
+            target.removeListener?.(signal, listener);
+        }
+    };
+};
+//# sourceMappingURL=main.js.map

package/package.json

@@ -0,0 +1,187 @@
+{
+  "name": "@retinue/agentkit",
+  "version": "0.1.0",
+  "description": "A provider-neutral, durable AI agent runtime for TypeScript: agents, tools, approvals, context, knowledge and persistence behind ports.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./runtime": {
+      "types": "./dist/entries/runtime.d.ts",
+      "default": "./dist/entries/runtime.js"
+    },
+    "./tools": {
+      "types": "./dist/entries/tools.d.ts",
+      "default": "./dist/entries/tools.js"
+    },
+    "./flows": {
+      "types": "./dist/entries/flows.d.ts",
+      "default": "./dist/entries/flows.js"
+    },
+    "./persistence": {
+      "types": "./dist/entries/persistence.d.ts",
+      "default": "./dist/entries/persistence.js"
+    },
+    "./context": {
+      "types": "./dist/entries/context.d.ts",
+      "default": "./dist/entries/context.js"
+    },
+    "./knowledge": {
+      "types": "./dist/entries/knowledge.d.ts",
+      "default": "./dist/entries/knowledge.js"
+    },
+    "./hitl": {
+      "types": "./dist/entries/hitl.d.ts",
+      "default": "./dist/entries/hitl.js"
+    },
+    "./usage": {
+      "types": "./dist/entries/usage.d.ts",
+      "default": "./dist/entries/usage.js"
+    },
+    "./mcp": {
+      "types": "./dist/entries/mcp.d.ts",
+      "default": "./dist/entries/mcp.js"
+    },
+    "./observability": {
+      "types": "./dist/entries/observability.d.ts",
+      "default": "./dist/entries/observability.js"
+    },
+    "./providers": {
+      "types": "./dist/entries/providers.d.ts",
+      "default": "./dist/entries/providers.js"
+    },
+    "./adapters/postgres": {
+      "types": "./dist/entries/adapters-postgres.d.ts",
+      "default": "./dist/entries/adapters-postgres.js"
+    },
+    "./adapters/redis": {
+      "types": "./dist/entries/adapters-redis.d.ts",
+      "default": "./dist/entries/adapters-redis.js"
+    },
+    "./adapters/bullmq": {
+      "types": "./dist/entries/adapters-bullmq.d.ts",
+      "default": "./dist/entries/adapters-bullmq.js"
+    },
+    "./adapters/otel": {
+      "types": "./dist/entries/adapters-otel.d.ts",
+      "default": "./dist/entries/adapters-otel.js"
+    },
+    "./package.json": "./package.json",
+    "./server": {
+      "types": "./dist/entries/server.d.ts",
+      "default": "./dist/entries/server.js"
+    }
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "README.md",
+    "!dist/**/*.map"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc -b",
+    "test": "vitest run",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "prepublishOnly": "node ../scripts/publish-guard.mjs"
+  },
+  "dependencies": {
+    "ai": "^7.0.66",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@ai-sdk/anthropic": "^4.0.42",
+    "@ai-sdk/azure": "^4.0.49",
+    "@ai-sdk/google": "^4.0.51",
+    "@ai-sdk/mistral": "^4.0.33",
+    "@ai-sdk/openai": "^4.0.47",
+    "@ai-sdk/openai-compatible": "^3.0.37",
+    "@electric-sql/pglite": "^0.5.5",
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/resources": "^2.10.0",
+    "@opentelemetry/sdk-metrics": "^2.10.0",
+    "@opentelemetry/sdk-trace-base": "^2.10.0",
+    "@types/node": "^20",
+    "@types/pg": "^8.23.0",
+    "@whatwg-node/server": "^0.11.0",
+    "bullmq": "^6.2.2",
+    "graphql": "^16.14.2",
+    "graphql-sse": "^2.6.0",
+    "graphql-yoga": "^5.22.0",
+    "ioredis": "^6.0.0",
+    "pg": "^8.23.0",
+    "typescript": "^5",
+    "vitest": "^4.1.9"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "peerDependencies": {
+    "@ai-sdk/anthropic": "^4.0.39",
+    "@ai-sdk/azure": "^4.0.43",
+    "@ai-sdk/google": "^4.0.44",
+    "@ai-sdk/mistral": "^4.0.29",
+    "@ai-sdk/openai": "^4.0.42",
+    "@ai-sdk/openai-compatible": "^3.0.31",
+    "@whatwg-node/server": "^0.11.0",
+    "bullmq": "^6.2.0",
+    "graphql": "^16.9.0",
+    "graphql-yoga": "^5.10.0",
+    "ioredis": "^6.0.0",
+    "pg": "^8.23.0"
+  },
+  "peerDependenciesMeta": {
+    "pg": {
+      "optional": true
+    },
+    "ioredis": {
+      "optional": true
+    },
+    "bullmq": {
+      "optional": true
+    },
+    "@ai-sdk/anthropic": {
+      "optional": true
+    },
+    "@ai-sdk/azure": {
+      "optional": true
+    },
+    "@ai-sdk/google": {
+      "optional": true
+    },
+    "@ai-sdk/mistral": {
+      "optional": true
+    },
+    "@ai-sdk/openai": {
+      "optional": true
+    },
+    "@ai-sdk/openai-compatible": {
+      "optional": true
+    },
+    "graphql": {
+      "optional": true
+    },
+    "graphql-yoga": {
+      "optional": true
+    },
+    "@whatwg-node/server": {
+      "optional": true
+    }
+  },
+  "sideEffects": false,
+  "author": "Rise Experts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Rise-Experts/retinue.git",
+    "directory": "backend"
+  },
+  "homepage": "https://github.com/Rise-Experts/retinue#readme",
+  "bugs": {
+    "url": "https://github.com/Rise-Experts/retinue/issues"
+  }
+}