@graphrefly/graphrefly 0.45.0 → 0.46.0

package/dist/utils/orchestration/index.d.ts

@@ -0,0 +1,233 @@
+import { Node } from '@graphrefly/pure-ts/core';
+import { NodeInput } from '@graphrefly/pure-ts/extra';
+import { MessagingHubGraph, JsonSchema, TopicGraph, SubscriptionGraph } from '../messaging/index.js';
+export { C as CatchOptions, a as ClassifyResult, D as Decision, b as DecisionAction, G as GateController, c as GateOptions, P as PipelineGraph, S as StepRef, T as TerminalCause, d as decisionKeyOf, p as pipelineGraph } from '../../pipeline-graph-DXCwY9vG.js';
+import '../../base/mutation/index.js';
+import '@graphrefly/pure-ts/graph';
+
+/**
+ * Phase 13.F — `humanInput<T>` sibling preset.
+ *
+ * Source: `archive/docs/SESSION-human-llm-intervention-primitives.md` §5
+ * "Sibling presets on the substrate" + §9 Phase 2.
+ *
+ * **Role.** LLM↔human runtime Q&A channel. The agent (or any consumer)
+ * reactively asks for human input by emitting a prompt; humanInput
+ * publishes a {@link Message} envelope to the well-known
+ * {@link PROMPTS_TOPIC} on the hub and watches {@link RESPONSES_TOPIC} for
+ * the matching `correlationId`. When the response arrives, humanInput's
+ * output Node emits the typed payload `T`.
+ *
+ * **Sibling to `approvalGate`** ([pipeline-graph.ts](pipeline-graph.ts)):
+ * approvalGate is design-time veto on a topology edge; humanInput is a
+ * runtime Q&A channel. They share substrate (hub + envelope) but differ
+ * in role and initiator.
+ *
+ * **No imperative `.run()` / `.ask()`** — caller writes to `prompt` (any
+ * `NodeInput<string>`) and reads `humanInput()`'s output Node.
+ *
+ * **Multi-prompt.** Each new `prompt` DATA mints a fresh correlationId
+ * and a new pending request. The output Node's emission tracks the latest
+ * correlationId — earlier in-flight requests are abandoned (switchMap
+ * semantics). To run parallel requests, instantiate two humanInput nodes.
+ */
+
+/** Outbound prompt envelope payload. */
+interface HumanPromptPayload {
+    readonly prompt: string;
+    readonly schema?: JsonSchema;
+}
+/**
+ * Options for {@link humanInput}.
+ */
+interface HumanInputOpts {
+    /**
+     * Messaging hub. {@link PROMPTS_TOPIC} is created lazily for outbound
+     * prompts; {@link RESPONSES_TOPIC} is read for incoming responses.
+     */
+    readonly hub: MessagingHubGraph;
+    /**
+     * Reactive prompt source. Any `NodeInput<string>` is accepted (Node,
+     * Promise, AsyncIterable, scalar) — coerced via `fromAny`. Each new
+     * DATA on this input mints a fresh request.
+     */
+    readonly prompt: NodeInput<string>;
+    /**
+     * Optional response-shape schema. Carried in the prompt envelope for
+     * UI / consumer-side validation. Caller-supplied validators (ajv,
+     * zod, valibot) consume this field; the substrate doesn't validate.
+     */
+    readonly schema?: JsonSchema;
+    /**
+     * Optional ID generator for the per-prompt correlationId. Default is
+     * a monotonic counter derived from a tight closure (sufficient for
+     * in-process correlation; cross-process consumers should supply UUID
+     * / ULID generation).
+     */
+    readonly idGenerator?: () => string;
+}
+/**
+ * Constructs a reactive human-input request channel. Each DATA on
+ * `prompt` mints a fresh request:
+ *
+ * 1. Mints a fresh `correlationId` (via `opts.idGenerator` if provided).
+ * 2. Publishes `TopicMessage<HumanPromptPayload>` to {@link PROMPTS_TOPIC}
+ *    (`{ id, schema?, correlationId, payload: { prompt, schema? } }`).
+ * 3. Watches {@link RESPONSES_TOPIC} for an envelope whose
+ *    `correlationId` matches.
+ * 4. When matched, emits the response payload as the output Node's DATA.
+ *
+ * **Switchmap semantics.** A new prompt arriving before the prior
+ * response abandons the prior wait. Output Node emits the response for
+ * the latest in-flight request only.
+ *
+ * **Output type `T`** is the response payload type. Caller is responsible
+ * for ensuring the response producer (UI / human-side) sends the right
+ * shape — `schema` is the wire-level convention for validation.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   humanInput,
+ *   messagingHub,
+ *   PROMPTS_TOPIC,
+ *   RESPONSES_TOPIC,
+ * } from "@graphrefly/graphrefly-ts";
+ *
+ * const hub = messagingHub("hub");
+ * const promptN = state<string>("prompt");
+ * const reply = humanInput<{ ok: boolean; reason: string }>({
+ *   hub,
+ *   prompt: promptN,
+ *   schema: { type: "object", required: ["ok", "reason"] },
+ * });
+ *
+ * // UI / human side: subscribe to PROMPTS_TOPIC, present, then publish to
+ * // RESPONSES_TOPIC with the matching correlationId.
+ * promptN.emit("Approve change?");
+ * const decision = await awaitSettled(reply);  // resolves when human responds
+ * ```
+ *
+ * @category patterns
+ */
+declare function humanInput<T>(opts: HumanInputOpts): Node<T>;
+
+/**
+ * Phase 13.F — `tracker` sibling preset.
+ *
+ * Source: `archive/docs/SESSION-human-llm-intervention-primitives.md` §5
+ * "Sibling presets on the substrate" + `archive/docs/SKETCH-reactive-tracker-factory.md`
+ * + `project_reactive_tracker` memory.
+ *
+ * **Role.** Park-as-deferred queue consumer. The tracker is the
+ * cursor-based read surface over the well-known {@link DEFERRED_TOPIC}
+ * — items the harness (or any consumer) defers for later attention.
+ * Sibling to `humanInput` and `approvalGate`; all three share substrate
+ * (hub + envelope + reactive cursor) but differ in role.
+ *
+ * **Cursor handle.** Per the SESSION's "Cursor handle" return — tracker
+ * exposes the cursor-based pull / ack surface so the consumer (a
+ * dashboard, a post-run review, an LLM watcher) can iterate over
+ * unconsumed items in order.
+ *
+ * **Naming locked (open question §11 #3 resolved):** `tracker`. The
+ * SESSION mentioned `tracker` vs `parkedQueue` vs `deferredTracker`;
+ * `tracker` is the simplest and most general — the deferred-queue
+ * semantic is a recipe, not a name overload. Other use cases (issue
+ * tracker, todo tracker, retrospective tracker per
+ * `project_reactive_tracker`) reuse the same primitive.
+ */
+
+/**
+ * Bundle returned by {@link tracker}. Wraps a topic + cursor-based
+ * subscription with imperative `add` / `ack` helpers.
+ */
+interface TrackerBundle<T> {
+    /**
+     * The underlying topic. Either freshly minted on the hub at
+     * `topicName` (default {@link DEFERRED_TOPIC}) or reused if the topic
+     * already exists.
+     */
+    readonly topic: TopicGraph<T>;
+    /** Cursor-based subscription view over `topic.events`. */
+    readonly subscription: SubscriptionGraph<T>;
+    /**
+     * Items beyond the current cursor — i.e. the deferred queue's
+     * "pending" head. Reactive `Node<readonly T[]>`.
+     */
+    readonly pending: Node<readonly T[]>;
+    /** Current cursor position (number of items already acked). */
+    readonly cursor: Node<number>;
+    /**
+     * Reactive total count of items added since construction (matches the
+     * topic's retained-events length until the topic's retention cap is
+     * reached).
+     */
+    readonly total: Node<number>;
+    /** Append an item to the deferred queue. */
+    add(item: T): void;
+    /**
+     * Advance the cursor past `n` items (default 1). Acks the next batch
+     * of pending items; subsequent reads of `pending` exclude them.
+     */
+    ack(n?: number): void;
+    /**
+     * Pull-and-ack at most `limit` items in one shot. Returns the items
+     * + the new cursor position (matches `subscription.pullAndAck`).
+     */
+    pullAndAck(limit?: number): {
+        items: readonly T[];
+        cursor: number;
+    };
+}
+/**
+ * Options for {@link tracker}.
+ */
+interface TrackerOpts {
+    /**
+     * Messaging hub. The tracker creates / reuses a topic on this hub
+     * named `topicName` (default {@link DEFERRED_TOPIC}).
+     */
+    readonly hub: MessagingHubGraph;
+    /**
+     * Topic name on the hub. Default {@link DEFERRED_TOPIC}. Override to
+     * use a non-deferred topic (e.g. a custom domain queue).
+     */
+    readonly topicName?: string;
+    /**
+     * Subscription graph name. Default `"tracker"`. Multiple trackers on
+     * the same hub topic must use distinct names.
+     */
+    readonly name?: string;
+    /**
+     * Initial cursor. Forwarded to the underlying subscription. See
+     * {@link SubscriptionOptions.from}.
+     */
+    readonly from?: "now" | "retained" | number;
+}
+/**
+ * Mints a tracker bundle over a hub topic.
+ *
+ * @example
+ * ```ts
+ * import { messagingHub, tracker } from "@graphrefly/graphrefly-ts";
+ *
+ * const hub = messagingHub("hub");
+ * const issues = tracker<{ summary: string }>({ hub });
+ *
+ * issues.add({ summary: "investigate flaky test" });
+ * issues.add({ summary: "follow up on auth refactor" });
+ *
+ * // Subscribe to the pending queue (for a dashboard, watcher, etc.)
+ * issues.pending.subscribe((msgs) => { ... });
+ *
+ * // Imperative pull + ack
+ * const next = issues.pullAndAck(1);
+ * console.log(next.items[0]?.summary);
+ * ```
+ *
+ * @category patterns
+ */
+declare function tracker<T>(opts: TrackerOpts): TrackerBundle<T>;
+
+export { type HumanInputOpts, type HumanPromptPayload, type TrackerBundle, type TrackerOpts, humanInput, tracker };

package/dist/utils/orchestration/index.js

@@ -0,0 +1,19 @@
+import {
+  PipelineGraph,
+  decisionKeyOf,
+  humanInput,
+  pipelineGraph,
+  tracker
+} from "../../chunk-CGHORL6G.js";
+import "../../chunk-Q3EYOCZB.js";
+import "../../chunk-FMPF42Q4.js";
+import "../../chunk-BXGZFGZ4.js";
+import "../../chunk-AZDQPQ3V.js";
+export {
+  PipelineGraph,
+  decisionKeyOf,
+  humanInput,
+  pipelineGraph,
+  tracker
+};
+//# sourceMappingURL=index.js.map

package/dist/utils/orchestration/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}