@autonome-research/thread-phase 3.0.0

package/dist/triggers/run-trigger.js

@@ -0,0 +1,146 @@
+/**
+ * runTrigger — the canonical Trigger consumer.
+ *
+ * Reads events from a `Trigger`, calls a user-supplied factory to produce
+ * `{ phases, ctx }` per event, and dispatches each pipeline. If a
+ * `JobRunner` is supplied, dispatch is persisted (job rows, event log,
+ * cancellation); otherwise the pipeline runs inline via
+ * `runPipelineToSummary` and events are discarded after dispatch.
+ *
+ * Resolves when the trigger generator exhausts, the abort signal fires,
+ * or `stop()` is called via the returned handle.
+ *
+ * Concurrency cap is a blocking semaphore. When `maxConcurrency` pipelines
+ * are in flight, the loop awaits a slot before pulling the next event
+ * from the trigger. The trigger's generator naturally pauses production
+ * — no events are dropped, no unbounded queue grows.
+ *
+ * Pipeline failures are isolated — one failing pipeline does not stop
+ * the trigger loop. Errors go through `onError` (or default stderr log)
+ * and the next event is still dispatched.
+ *
+ * Cancellation: each in-flight dispatch owns an `AbortController`. Call
+ * `handle.cancel(triggerEventId)` to abort that specific pipeline; the
+ * signal flows into `runPipelineToSummary` (inline) or `jobRunner.cancel`
+ * (persisted). Returns `true` if the pipeline was found and aborted,
+ * `false` if the event id is unknown or already completed.
+ *
+ * Observability: `onCapacityFull(event)` fires when an event arrives
+ * while the concurrency cap is full (the loop blocks on `Promise.race`
+ * before pulling the event, so this is the moment backpressure starts).
+ * `onDispatchStart(event)` fires immediately when a dispatch begins,
+ * before the user-supplied factory runs.
+ */
+import { runPipelineToSummary } from '../orchestrator.js';
+export function runTrigger(trigger, pipelineFactory, options = {}) {
+    const maxConcurrency = options.maxConcurrency ?? 1;
+    const pipelineName = options.pipelineName ?? trigger.name;
+    const onError = options.onError ??
+        ((event, err) => {
+            console.error(`[trigger:${trigger.name}] event ${event.id} failed:`, err.message);
+        });
+    const inflight = new Map();
+    let aborted = false;
+    const dispatch = (event) => {
+        options.onDispatchStart?.(event);
+        const controller = new AbortController();
+        const { phases, ctx } = pipelineFactory(event.input, event);
+        // Wire the per-dispatch signal into ctx so phases can observe it for
+        // mid-phase cancellation (in addition to runPipeline's between-phase
+        // check via the same signal forwarded below).
+        ctx.signal = controller.signal;
+        let jobId;
+        const work = (async () => {
+            try {
+                if (options.jobRunner) {
+                    jobId = await options.jobRunner.create(pipelineName, {
+                        triggerName: trigger.name,
+                        triggerEventId: event.id,
+                        occurredAt: event.occurredAt,
+                        input: event.input,
+                        metadata: event.metadata,
+                    });
+                }
+                options.onStart?.(event, jobId);
+                if (options.jobRunner && jobId) {
+                    // JobRunner has its own controller per job (signalFor / cancel).
+                    // The dispatch's AbortController is wired so handle.cancel(eventId)
+                    // delegates to jobRunner.cancel(jobId).
+                    const jobIdAtRun = jobId;
+                    controller.signal.addEventListener('abort', () => {
+                        options.jobRunner.cancel(jobIdAtRun, controller.signal.reason ?? 'cancelled');
+                    }, { once: true });
+                    await options.jobRunner.run(jobId, phases, ctx);
+                }
+                else {
+                    // Inline path: forward the signal to runPipelineToSummary so
+                    // phase code that observes it (or the orchestrator's pre-phase
+                    // check) can unwind cleanly.
+                    await runPipelineToSummary(phases, ctx, { signal: controller.signal });
+                }
+                options.onComplete?.(event, jobId);
+            }
+            catch (err) {
+                const error = err instanceof Error ? err : new Error(String(err));
+                onError(event, error, jobId);
+            }
+        })();
+        inflight.set(event.id, { controller, promise: work, jobId });
+        work.finally(() => inflight.delete(event.id));
+        return work;
+    };
+    const stop = async () => {
+        if (aborted)
+            return;
+        aborted = true;
+        await trigger.stop();
+    };
+    if (options.signal) {
+        if (options.signal.aborted) {
+            void stop();
+        }
+        else {
+            options.signal.addEventListener('abort', () => void stop(), { once: true });
+        }
+    }
+    const loop = async () => {
+        const gen = trigger.start();
+        try {
+            for await (const event of gen) {
+                if (aborted)
+                    break;
+                // Block until a concurrency slot is available — backpressure flows
+                // back to the trigger by way of the generator pausing. If we have
+                // to wait, fire onCapacityFull so the user knows.
+                if (inflight.size >= maxConcurrency) {
+                    options.onCapacityFull?.(event);
+                }
+                while (inflight.size >= maxConcurrency && !aborted) {
+                    await Promise.race(Array.from(inflight.values()).map((d) => d.promise));
+                }
+                if (aborted)
+                    break;
+                void dispatch(event);
+            }
+        }
+        finally {
+            // Wait for any in-flight pipelines to settle before resolving.
+            await Promise.allSettled(Array.from(inflight.values()).map((d) => d.promise));
+        }
+    };
+    const cancel = (triggerEventId) => {
+        const dispatchRec = inflight.get(triggerEventId);
+        if (!dispatchRec)
+            return false;
+        if (dispatchRec.controller.signal.aborted)
+            return false;
+        dispatchRec.controller.abort('cancelled by handle');
+        return true;
+    };
+    return {
+        done: loop(),
+        stop,
+        cancel,
+    };
+}
+//# sourceMappingURL=run-trigger.js.map

package/dist/triggers/run-trigger.js.map

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

package/dist/triggers/timer-trigger.d.ts

@@ -0,0 +1,46 @@
+/**
+ * TimerTrigger — fires at a fixed interval.
+ *
+ * The canonical scheduled-pipeline source. Replaces `setInterval(() => ..., 60_000)`
+ * with the Trigger protocol so the same pipeline-dispatch code works for
+ * timer-, webhook-, and queue-driven flows.
+ *
+ * No cron expression support in core — keep the impl tiny. For cron, wrap
+ * a cron parser (e.g. `croner`) and produce events on its schedule;
+ * `examples/triggers/timer-with-cron.ts` shows the shape.
+ */
+import type { Trigger, TriggerEvent } from './types.js';
+export interface TimerTriggerOptions<TInput = void> {
+    /** Interval between fires, in milliseconds. */
+    intervalMs: number;
+    /**
+     * Payload to attach to each event. Defaults to `undefined`. If a
+     * function, called each fire to produce a fresh payload (e.g. the
+     * current time, a counter, a snapshot from somewhere).
+     */
+    payload?: TInput | (() => TInput) | (() => Promise<TInput>);
+    /**
+     * If true, fires immediately on `start()` before the first interval
+     * elapses. Default: false (first event arrives after one interval).
+     */
+    fireImmediately?: boolean;
+    /** Stable identifier used for logs. Default: `timer:${intervalMs}ms`. */
+    name?: string;
+}
+export declare class TimerTrigger<TInput = void> implements Trigger<TInput> {
+    readonly name: string;
+    private readonly intervalMs;
+    private readonly payload;
+    private readonly fireImmediately;
+    private seq;
+    private stopped;
+    private pendingTimer;
+    private notifyStop;
+    constructor(options: TimerTriggerOptions<TInput>);
+    start(): AsyncGenerator<TriggerEvent<TInput>, void>;
+    stop(): Promise<void>;
+    private makeEvent;
+    /** Returns true if the interval elapsed normally, false if stop() fired first. */
+    private waitOrStop;
+}
+//# sourceMappingURL=timer-trigger.d.ts.map

package/dist/triggers/timer-trigger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timer-trigger.d.ts","sourceRoot":"","sources":["../../src/triggers/timer-trigger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAExD,MAAM,WAAW,mBAAmB,CAAC,MAAM,GAAG,IAAI;IAChD,+CAA+C;IAC/C,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,GAAG,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;IAC5D;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,yEAAyE;IACzE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,qBAAa,YAAY,CAAC,MAAM,GAAG,IAAI,CAAE,YAAW,OAAO,CAAC,MAAM,CAAC;IACjE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyC;IACjE,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAU;IAE1C,OAAO,CAAC,GAAG,CAAK;IAChB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,YAAY,CAA8C;IAClE,OAAO,CAAC,UAAU,CAA6B;gBAEnC,OAAO,EAAE,mBAAmB,CAAC,MAAM,CAAC;IAOzC,KAAK,IAAI,cAAc,CAAC,YAAY,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC;IAepD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;YAWb,SAAS;IAavB,kFAAkF;IAClF,OAAO,CAAC,UAAU;CAUnB"}

package/dist/triggers/timer-trigger.js

@@ -0,0 +1,74 @@
+/**
+ * TimerTrigger — fires at a fixed interval.
+ *
+ * The canonical scheduled-pipeline source. Replaces `setInterval(() => ..., 60_000)`
+ * with the Trigger protocol so the same pipeline-dispatch code works for
+ * timer-, webhook-, and queue-driven flows.
+ *
+ * No cron expression support in core — keep the impl tiny. For cron, wrap
+ * a cron parser (e.g. `croner`) and produce events on its schedule;
+ * `examples/triggers/timer-with-cron.ts` shows the shape.
+ */
+export class TimerTrigger {
+    name;
+    intervalMs;
+    payload;
+    fireImmediately;
+    seq = 0;
+    stopped = false;
+    pendingTimer = null;
+    notifyStop = null;
+    constructor(options) {
+        this.intervalMs = options.intervalMs;
+        this.payload = options.payload;
+        this.fireImmediately = options.fireImmediately ?? false;
+        this.name = options.name ?? `timer:${options.intervalMs}ms`;
+    }
+    async *start() {
+        if (this.stopped)
+            return;
+        if (this.fireImmediately) {
+            yield await this.makeEvent();
+            if (this.stopped)
+                return;
+        }
+        while (!this.stopped) {
+            const waited = await this.waitOrStop();
+            if (!waited)
+                return;
+            yield await this.makeEvent();
+        }
+    }
+    async stop() {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        if (this.pendingTimer) {
+            clearTimeout(this.pendingTimer);
+            this.pendingTimer = null;
+        }
+        this.notifyStop?.();
+        this.notifyStop = null;
+    }
+    async makeEvent() {
+        const input = typeof this.payload === 'function'
+            ? await this.payload()
+            : this.payload;
+        return {
+            id: ++this.seq,
+            occurredAt: new Date().toISOString(),
+            input,
+        };
+    }
+    /** Returns true if the interval elapsed normally, false if stop() fired first. */
+    waitOrStop() {
+        return new Promise((resolve) => {
+            this.pendingTimer = setTimeout(() => {
+                this.pendingTimer = null;
+                resolve(true);
+            }, this.intervalMs);
+            this.notifyStop = () => resolve(false);
+        });
+    }
+}
+//# sourceMappingURL=timer-trigger.js.map

package/dist/triggers/timer-trigger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timer-trigger.js","sourceRoot":"","sources":["../../src/triggers/timer-trigger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAsBH,MAAM,OAAO,YAAY;IACd,IAAI,CAAS;IAEL,UAAU,CAAS;IACnB,OAAO,CAAyC;IAChD,eAAe,CAAU;IAElC,GAAG,GAAG,CAAC,CAAC;IACR,OAAO,GAAG,KAAK,CAAC;IAChB,YAAY,GAAyC,IAAI,CAAC;IAC1D,UAAU,GAAwB,IAAI,CAAC;IAE/C,YAAY,OAAoC;QAC9C,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;QACrC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAC/B,IAAI,CAAC,eAAe,GAAG,OAAO,CAAC,eAAe,IAAI,KAAK,CAAC;QACxD,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,SAAS,OAAO,CAAC,UAAU,IAAI,CAAC;IAC9D,CAAC;IAED,KAAK,CAAC,CAAC,KAAK;QACV,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO;QAEzB,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;YACzB,MAAM,MAAM,IAAI,CAAC,SAAS,EAAE,CAAC;YAC7B,IAAI,IAAI,CAAC,OAAO;gBAAE,OAAO;QAC3B,CAAC;QAED,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YACrB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC;YACvC,IAAI,CAAC,MAAM;gBAAE,OAAO;YACpB,MAAM,MAAM,IAAI,CAAC,SAAS,EAAE,CAAC;QAC/B,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAI;QACR,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO;QACzB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YACtB,YAAY,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YAChC,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;QAC3B,CAAC;QACD,IAAI,CAAC,UAAU,EAAE,EAAE,CAAC;QACpB,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;IACzB,CAAC;IAEO,KAAK,CAAC,SAAS;QACrB,MAAM,KAAK,GACT,OAAO,IAAI,CAAC,OAAO,KAAK,UAAU;YAChC,CAAC,CAAC,MAAO,IAAI,CAAC,OAA0C,EAAE;YAC1D,CAAC,CAAE,IAAI,CAAC,OAAkB,CAAC;QAE/B,OAAO;YACL,EAAE,EAAE,EAAE,IAAI,CAAC,GAAG;YACd,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACpC,KAAK;SACN,CAAC;IACJ,CAAC;IAED,kFAAkF;IAC1E,UAAU;QAChB,OAAO,IAAI,OAAO,CAAU,CAAC,OAAO,EAAE,EAAE;YACtC,IAAI,CAAC,YAAY,GAAG,UAAU,CAAC,GAAG,EAAE;gBAClC,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;gBACzB,OAAO,CAAC,IAAI,CAAC,CAAC;YAChB,CAAC,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;YAEpB,IAAI,CAAC,UAAU,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACzC,CAAC,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/triggers/types.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Trigger protocol — the entry-point abstraction.
+ *
+ * A `Trigger` is a signal source that yields typed events. A consumer
+ * (typically `runTrigger`) reads the generator and dispatches a pipeline
+ * for each event. Triggers do not know about pipelines, ctx, or the
+ * JobStore — they only know about producing events.
+ *
+ * Concrete impls in this package: `TimerTrigger`. Anything else
+ * (HTTP webhooks, queue consumers, file watchers, message brokers)
+ * lives outside core. The `examples/triggers/` tree shows how to
+ * adapt arbitrary signal sources into this interface.
+ *
+ * Design properties:
+ *   - The generator yields forever until `stop()` resolves or the
+ *     underlying source exhausts.
+ *   - `stop()` returns a promise so resource cleanup (closing servers,
+ *     clearing timers, draining buffers) can be awaited.
+ *   - Each event carries an `id` monotonic within the trigger instance
+ *     so consumers can deduplicate or correlate without a separate seq.
+ */
+/**
+ * One event produced by a trigger.
+ *
+ * `input` is the structured payload the pipeline factory will consume.
+ * `metadata` is for transport-level info (HTTP headers, source IP,
+ * queue message id, file path) that the pipeline may want for logging
+ * or auditing but doesn't shape the work.
+ */
+export interface TriggerEvent<TInput = unknown> {
+    /** Monotonically increasing id within this trigger instance, starting at 1. */
+    readonly id: number;
+    /** ISO timestamp at the moment the trigger observed the event. */
+    readonly occurredAt: string;
+    /** Structured payload. Pipeline factory consumes this. */
+    readonly input: TInput;
+    /** Transport-level info: headers, source IP, message id, file path, etc. */
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/**
+ * A signal source that fires pipelines.
+ *
+ * `start()` returns an async generator yielding events. The consumer
+ * controls pacing — back-pressure is the consumer's responsibility.
+ *
+ * `stop()` must idempotently clean up resources. After `stop()` resolves,
+ * the generator returned by `start()` must complete (no more yields).
+ *
+ * Implementations are single-consumer. To fan one trigger's events out
+ * to multiple consumers, build the multiplexer in user code — keeping
+ * the protocol single-consumer keeps shutdown semantics simple.
+ */
+export interface Trigger<TInput = unknown> {
+    /** Stable identifier used for logs and error messages. */
+    readonly name: string;
+    /** Async iterable of events. Yields until `stop()` resolves. */
+    start(): AsyncGenerator<TriggerEvent<TInput>, void>;
+    /** Release resources. Idempotent. */
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/triggers/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/triggers/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY,CAAC,MAAM,GAAG,OAAO;IAC5C,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,kEAAkE;IAClE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACvD;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,OAAO,CAAC,MAAM,GAAG,OAAO;IACvC,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gEAAgE;IAChE,KAAK,IAAI,cAAc,CAAC,YAAY,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,CAAC;IACpD,qCAAqC;IACrC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB"}

package/dist/triggers/types.js

@@ -0,0 +1,23 @@
+/**
+ * Trigger protocol — the entry-point abstraction.
+ *
+ * A `Trigger` is a signal source that yields typed events. A consumer
+ * (typically `runTrigger`) reads the generator and dispatches a pipeline
+ * for each event. Triggers do not know about pipelines, ctx, or the
+ * JobStore — they only know about producing events.
+ *
+ * Concrete impls in this package: `TimerTrigger`. Anything else
+ * (HTTP webhooks, queue consumers, file watchers, message brokers)
+ * lives outside core. The `examples/triggers/` tree shows how to
+ * adapt arbitrary signal sources into this interface.
+ *
+ * Design properties:
+ *   - The generator yields forever until `stop()` resolves or the
+ *     underlying source exhausts.
+ *   - `stop()` returns a promise so resource cleanup (closing servers,
+ *     clearing timers, draining buffers) can be awaited.
+ *   - Each event carries an `id` monotonic within the trigger instance
+ *     so consumers can deduplicate or correlate without a separate seq.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/triggers/types.js.map

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

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@autonome-research/thread-phase",
+  "version": "3.0.0",
+  "description": "TypeScript substrate for building automation workflows that coordinate AI agents. Phase ordering, typed shared state, persistence, fanout, event flow.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./patterns": "./dist/patterns/index.js",
+    "./context": "./dist/context/index.js",
+    "./session": "./dist/session/index.js",
+    "./tools": "./dist/tools/index.js",
+    "./agents": "./dist/agents/index.js",
+    "./agents/test-utils": "./dist/agents/test-utils/index.js",
+    "./triggers": "./dist/triggers/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "smoke": "tsx examples/smoke.ts"
+  },
+  "dependencies": {
+    "ajv": "^8.17.0",
+    "better-sqlite3": "^11.5.0",
+    "openai": "^4.77.0"
+  },
+  "devDependencies": {
+    "@honcho-ai/sdk": "^2.1.1",
+    "@types/better-sqlite3": "^7.6.11",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "peerDependencies": {
+    "cron-parser": "^4.0.0 || ^5.0.0",
+    "vitest": "^2.1.0"
+  },
+  "peerDependenciesMeta": {
+    "cron-parser": {
+      "optional": true
+    },
+    "vitest": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Code4me2/thread-phase.git",
+    "directory": "packages/thread-phase"
+  }
+}