@methodts/runtime 0.1.0

package/dist/event-bus/webhook-connector.test.js

@@ -0,0 +1,214 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Unit tests for WebhookConnector (PRD 026 Phase 5).
+ */
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { createServer } from 'node:http';
+import { WebhookConnector } from './webhook-connector.js';
+// ── Test helpers ───────────────────────────────────────────────
+function makeEvent(seq, overrides = {}) {
+    return {
+        id: `evt-${seq}`,
+        version: 1,
+        timestamp: new Date().toISOString(),
+        sequence: seq,
+        domain: 'session',
+        type: 'session.spawned',
+        severity: 'info',
+        payload: { test: true },
+        source: 'test',
+        ...overrides,
+    };
+}
+/** Create a simple HTTP server that records received requests. */
+function createMockServer() {
+    const requests = [];
+    let statusCode = 200;
+    const server = createServer((req, res) => {
+        const chunks = [];
+        req.on('data', (chunk) => chunks.push(chunk));
+        req.on('end', () => {
+            requests.push({
+                method: req.method ?? 'UNKNOWN',
+                body: Buffer.concat(chunks).toString('utf-8'),
+                headers: req.headers,
+            });
+            res.writeHead(statusCode);
+            res.end();
+        });
+    });
+    return {
+        server,
+        port: 0,
+        requests,
+        setStatus: (code) => { statusCode = code; },
+        start: () => new Promise((resolve) => {
+            server.listen(0, '127.0.0.1', () => {
+                const addr = server.address();
+                const port = typeof addr === 'object' && addr ? addr.port : 0;
+                resolve(port);
+            });
+        }),
+        stop: () => new Promise((resolve) => {
+            server.close(() => resolve());
+        }),
+    };
+}
+// ── Tests ──────────────────────────────────────────────────────
+describe('WebhookConnector', () => {
+    let mock;
+    let connector;
+    beforeEach(async () => {
+        mock = createMockServer();
+        const port = await mock.start();
+        connector = new WebhookConnector({
+            url: `http://127.0.0.1:${port}/events`,
+            maxRetries: 1,
+            retryBaseMs: 10, // Fast retries for tests
+            timeoutMs: 2000,
+        });
+    });
+    afterEach(async () => {
+        await connector.disconnect();
+        await mock.stop();
+    });
+    describe('connect / disconnect / health', () => {
+        it('connect marks as connected when URL reachable', async () => {
+            await connector.connect();
+            const h = connector.health();
+            assert.equal(h.connected, true);
+            assert.equal(h.errorCount, 0);
+            assert.equal(h.lastEventAt, null);
+        });
+        it('connect marks as not connected when URL unreachable', async () => {
+            await mock.stop();
+            const unreachable = new WebhookConnector({
+                url: 'http://127.0.0.1:1/unreachable',
+                timeoutMs: 100,
+            });
+            await unreachable.connect();
+            assert.equal(unreachable.health().connected, false);
+        });
+        it('disconnect sets connected to false', async () => {
+            await connector.connect();
+            await connector.disconnect();
+            assert.equal(connector.health().connected, false);
+        });
+    });
+    describe('onEvent', () => {
+        it('POSTs event as JSON to configured URL', async () => {
+            await connector.connect();
+            const event = makeEvent(1);
+            connector.onEvent(event);
+            // Wait for async POST
+            await new Promise((r) => setTimeout(r, 200));
+            // First request is HEAD from connect(), second is POST from onEvent
+            const posts = mock.requests.filter((r) => r.method === 'POST');
+            assert.equal(posts.length, 1);
+            const body = JSON.parse(posts[0].body);
+            assert.equal(body.id, 'evt-1');
+            assert.equal(body.type, 'session.spawned');
+            assert.equal(posts[0].headers['content-type'], 'application/json');
+        });
+        it('updates lastEventAt on successful POST', async () => {
+            await connector.connect();
+            connector.onEvent(makeEvent(1));
+            await new Promise((r) => setTimeout(r, 200));
+            const h = connector.health();
+            assert.ok(h.lastEventAt !== null);
+            assert.equal(h.errorCount, 0);
+        });
+    });
+    describe('filtering', () => {
+        it('skips events not matching filter', async () => {
+            await mock.stop();
+            const port = await mock.start();
+            connector = new WebhookConnector({
+                url: `http://127.0.0.1:${port}/events`,
+                filter: { domain: 'strategy' },
+            });
+            await connector.connect();
+            connector.onEvent(makeEvent(1, { domain: 'session' }));
+            connector.onEvent(makeEvent(2, { domain: 'strategy' }));
+            await new Promise((r) => setTimeout(r, 200));
+            const posts = mock.requests.filter((r) => r.method === 'POST');
+            assert.equal(posts.length, 1);
+            assert.equal(JSON.parse(posts[0].body).domain, 'strategy');
+        });
+        it('filters by severity', async () => {
+            await mock.stop();
+            const port = await mock.start();
+            connector = new WebhookConnector({
+                url: `http://127.0.0.1:${port}/events`,
+                filter: { severity: ['error', 'critical'] },
+            });
+            await connector.connect();
+            connector.onEvent(makeEvent(1, { severity: 'info' }));
+            connector.onEvent(makeEvent(2, { severity: 'error' }));
+            await new Promise((r) => setTimeout(r, 200));
+            const posts = mock.requests.filter((r) => r.method === 'POST');
+            assert.equal(posts.length, 1);
+        });
+    });
+    describe('retry', () => {
+        it('retries on server error and succeeds', async () => {
+            let callCount = 0;
+            mock.server.removeAllListeners('request');
+            mock.server.on('request', (req, res) => {
+                const chunks = [];
+                req.on('data', (c) => chunks.push(c));
+                req.on('end', () => {
+                    callCount++;
+                    // Fail first POST, succeed second
+                    if (req.method === 'POST' && callCount <= 2) {
+                        res.writeHead(500);
+                    }
+                    else {
+                        res.writeHead(200);
+                    }
+                    res.end();
+                });
+            });
+            await connector.connect();
+            connector.onEvent(makeEvent(1));
+            await new Promise((r) => setTimeout(r, 500));
+            // Should have retried: HEAD (connect) + POST (fail) + POST (success)
+            assert.ok(callCount >= 2, `Expected >= 2 calls, got ${callCount}`);
+            assert.equal(connector.health().errorCount, 0);
+        });
+        it('increments errorCount after all retries exhausted', async () => {
+            mock.setStatus(500);
+            await connector.connect();
+            connector.onEvent(makeEvent(1));
+            await new Promise((r) => setTimeout(r, 500));
+            assert.equal(connector.health().errorCount, 1);
+            assert.equal(connector.health().connected, false);
+        });
+    });
+    describe('rate limiting', () => {
+        it('drops events exceeding rate limit', async () => {
+            await mock.stop();
+            const port = await mock.start();
+            connector = new WebhookConnector({
+                url: `http://127.0.0.1:${port}/events`,
+                maxEventsPerSecond: 3,
+                maxRetries: 0,
+            });
+            await connector.connect();
+            // Send 6 events rapidly
+            for (let i = 0; i < 6; i++) {
+                connector.onEvent(makeEvent(i));
+            }
+            await new Promise((r) => setTimeout(r, 500));
+            const posts = mock.requests.filter((r) => r.method === 'POST');
+            assert.ok(posts.length <= 3, `Expected <= 3 POSTs, got ${posts.length}`);
+        });
+    });
+    describe('name', () => {
+        it('derives name from URL hostname', () => {
+            assert.ok(connector.name.startsWith('webhook:'));
+        });
+    });
+});
+//# sourceMappingURL=webhook-connector.test.js.map

package/dist/event-bus/webhook-connector.test.js.map

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

package/dist/executors/cortex-job-backed-executor.d.ts

@@ -0,0 +1,137 @@
+/**
+ * CortexJobBackedExecutor — Wave 1 impl of the JobBackedExecutor port.
+ *
+ * PRD-062 / S5. Wave 1 scope: `fresh-per-continuation` budget strategy only.
+ * `batched-held` and `predictive-prereserve` throw
+ * `BudgetStrategyNotImplemented` with a link to Cortex Open Question O1
+ * (`ctx.llm.reserve()/settle()` API).
+ *
+ * The executor:
+ *   1. Registers exactly ONE `method.pact.continue` handler per app (S5 §3,
+ *      gate G-ONE-HANDLER).
+ *   2. Dispatches by `pactKey` via an in-process factory map (O(1)).
+ *   3. Consults SessionStore's `lastAckedTurn` (stored in snapshot metadata
+ *      per S5 §6) before executing any turn — idempotent under at-least-once
+ *      delivery (gate G-IDEMPOTENCY).
+ *   4. Acks-without-executing when the envelope's `turnIndex` has already
+ *      been processed.
+ *   5. Refuses envelopes whose `budgetRef.expiresAt` is in the past
+ *      (terminal, emits `PactDeadLetterEvent`).
+ *   6. Coordinates DLQ emission so exactly one `PactDeadLetterEvent`
+ *      fires per `sessionId` regardless of inline + external paths
+ *      (gate G-DLQ-SINGLE-EMIT).
+ *
+ * Out of Wave 1: the executor does NOT run real pact turns. Wiring pacta's
+ * `createAgent` into the continuation loop is a Wave 2 deliverable — this
+ * PRD ships the port boundaries, envelope plumbing, idempotency check,
+ * and DLQ contract. The `executeTurn` hook is injectable so Wave 2 can
+ * substitute a real runner without touching the envelope plumbing.
+ */
+import type { PactDeadLetterEvent } from '@methodts/pacta';
+import type { BudgetRef, ContinuationEnvelope, NextAction } from '../ports/continuation-envelope.js';
+import type { JobBackedExecutor, JobClient, PactFactory, PactStartInput } from '../ports/job-backed-executor.js';
+import type { SessionStore } from '../ports/session-store.js';
+/**
+ * Outcome of one executed turn. The runner returns this to the executor
+ * which decides whether to enqueue a continuation or finalise the session.
+ */
+export type TurnOutcome = {
+    kind: 'yield';
+    nextAction: NextAction;
+    checkpointId: string;
+    checkpointHash: string;
+    checkpointSizeBytes: number;
+    nextBudgetRef: BudgetRef;
+} | {
+    kind: 'complete';
+} | {
+    kind: 'dead_letter';
+    error: string;
+};
+/**
+ * The injected runner signature. Wave 1 ships a no-op runner for tests;
+ * Wave 2 will wire pacta's `createAgent` loop.
+ */
+export type TurnRunner = (args: {
+    envelope: ContinuationEnvelope;
+    factory: PactFactory;
+    fencingToken: string;
+    checkpoint: unknown;
+    initialContext: Record<string, unknown>;
+}) => Promise<TurnOutcome>;
+export interface CortexJobBackedExecutorOptions {
+    sessionStore: SessionStore;
+    workerId: string;
+    /** Optional host-level event sink — receives `PactDeadLetterEvent`s. */
+    emitAgentEvent?: (event: PactDeadLetterEvent) => void;
+    /**
+     * Turn runner. Wave 1 default = a stub that emits a single-turn
+     * complete outcome. Wave 2 will pass a pacta-backed runner.
+     */
+    runner?: TurnRunner;
+    /** Clock injection for tests. Defaults to `Date.now`. */
+    now?: () => number;
+}
+/**
+ * CortexJobBackedExecutor.
+ *
+ * Wave 1 ships the port-surface implementation: attach, registerPact,
+ * start, yield, stop; a single `method.pact.continue` handler; full
+ * envelope parsing/validation; idempotency via SessionSnapshot metadata;
+ * DLQ single-emit coordination; `fresh-per-continuation` budget strategy.
+ */
+export declare class CortexJobBackedExecutor implements JobBackedExecutor {
+    private readonly store;
+    private readonly workerId;
+    private readonly runner;
+    private readonly now;
+    private readonly emitAgentEvent?;
+    private readonly factories;
+    private readonly dlqEmitted;
+    private jobs;
+    private handlerAttached;
+    private stopped;
+    constructor(options: CortexJobBackedExecutorOptions);
+    attach(jobs: JobClient): Promise<void>;
+    registerPact(key: string, factory: PactFactory): void;
+    start(input: PactStartInput): Promise<{
+        sessionId: string;
+        traceId: string;
+    }>;
+    yield(envelope: ContinuationEnvelope): Promise<void>;
+    stop(_timeoutMs: number): Promise<void>;
+    /**
+     * Single `method.pact.continue` handler — S5 §3, gate G-ONE-HANDLER.
+     *
+     * Responsibilities (in order, each step durable before ack per S5 §6):
+     *   1. Parse envelope (version check) or recognise scheduled-pact-tick.
+     *   2. Validate `budgetRef.expiresAt` — refuse past-deadline envelopes.
+     *   3. Load session snapshot — reject if unknown.
+     *   4. Idempotency check against `lastAckedTurn` + `turnIndex`.
+     *   5. Acquire lease via SessionStore.resume.
+     *   6. Load latest checkpoint.
+     *   7. Dispatch to factory-produced pact via the injected runner.
+     *   8. Classify outcome → yield / complete / dead_letter.
+     *   9. Persist checkpoint + `lastAckedTurn` with fencing token.
+     *  10. Release lease, enqueue next envelope (if yielding), or finalise.
+     */
+    private dispatch;
+    private completeTurn;
+    private enqueueNext;
+    /**
+     * Emit a `PactDeadLetterEvent` once per sessionId. Coordinated via
+     * a metadata flag on the snapshot so subsequent inline or external
+     * DLQ triggers for the same session are silently suppressed.
+     *
+     * Gate G-DLQ-SINGLE-EMIT (see dlq/dlq-observer.test.ts).
+     */
+    emitInlineDeadLetter(envelope: ContinuationEnvelope, lastError: string, attempts: number): Promise<PactDeadLetterEvent | null>;
+    /** Used by the CortexDlqObserver to coordinate single-emit. */
+    isDlqEmitted(sessionId: string): Promise<boolean>;
+    private coerceToEnvelope;
+    private synthesiseFromSchedule;
+    private buildInitialEnvelope;
+    private assertStrategyImplemented;
+    private enforceEnvelopeSize;
+}
+//# sourceMappingURL=cortex-job-backed-executor.d.ts.map

package/dist/executors/cortex-job-backed-executor.d.ts.map

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