opencode-swarm 7.164.9 → 7.164.11

package/dist/hooks/system-guidance-carrier.d.ts

@@ -0,0 +1,112 @@
+/**
+ * System-guidance carrier (issue #2526).
+ *
+ * The OpenCode host's `toModelMessagesEffect` (pinned @opencode-ai 1.18.3 —
+ * anomalyco/opencode@v1.18.3, packages/opencode/src/session/message-v2.ts:195-244,
+ * commit 127bdb30784d508cc556c71a0f32b508a3061517) branches ONLY on `user` and
+ * `assistant` with no `else`, and dereferences `msg.parts` unconditionally.
+ * Synthetic `role:'system'` entries spliced into `experimental.chat.messages.transform`
+ * were therefore silently discarded (and flat entries without `parts` crashed the
+ * host prompt build with a TypeError) while delivery telemetry recorded them as
+ * delivered.
+ *
+ * This module is the single source of truth for the fix: model-only guidance rides
+ * a USER-role message — which the host renders unconditionally — carrying an explicit
+ * provenance fence so the model can tell injected directives apart from real user
+ * speech. Detection is by `info.id` prefix, never by text sniffing.
+ *
+ * Host-render contract for a carrier (message-v2.ts user branch, :198-242):
+ *   - `info.role === 'user'` and `info.id` a string (copied verbatim; treated as opaque)
+ *   - ≥1 part `{type:'text', text !== ''}` (empty-string text parts are dropped; a
+ *     message whose every part is dropped is not pushed)
+ *   - `parts.length === 0` entries are skipped before the role branch — an EMPTY
+ *     carrier (zero parts) is therefore truly inert and never renders.
+ *
+ * Carriers live only inside a single request's transform array: the host rebuilds
+ * that array from persisted (user/assistant-only) messages each turn, so carriers
+ * never persist, accumulate, or pollute the stored conversation.
+ */
+/**
+ * Structural message shape the carrier helpers operate on. Every consumer's
+ * local message type (knowledge `MessageWithParts`, the guardrails transform's
+ * local shape, memory's cast arrays) is assignable to this; arrays are passed
+ * BY REFERENCE and mutated in place (issue #1619 discipline).
+ */
+export interface GuidanceMessage {
+    info: {
+        role?: string;
+        /** String when plugin-built; every read goes through a typeof check. */
+        id?: unknown;
+    };
+    parts: Array<{
+        type: string;
+        text?: string;
+    }>;
+}
+/** Identity prefix for guidance carriers. Detection = role user + this id prefix. */
+export declare const GUIDANCE_CARRIER_ID_PREFIX = "swarm-guidance:";
+export declare function guidanceCarrierId(kind: string): string;
+/**
+ * Wrap guidance text in the provenance fence (null for empty/whitespace text).
+ * Shared by every carrier-construction path so the fence format cannot drift.
+ * Embedded fence markup is neutralized (see {@link neutralizeFenceMarkup}).
+ */
+export declare function fenceGuidanceText(kind: string, text: string): string | null;
+/**
+ * True for a guidance carrier entry (role user + id prefix — no text
+ * sniffing). Accepts `unknown` so every consumer's local message type can be
+ * tested without casts.
+ */
+export declare function isGuidanceCarrier(message: unknown): boolean;
+/** All guidance carriers in the array, in order. */
+export declare function findGuidanceCarriers(messages: GuidanceMessage[]): GuidanceMessage[];
+/**
+ * Joined text of a message's text parts (empty string when none). Used by
+ * dedupe predicates that must not re-inject a block already present in the
+ * carrier body.
+ */
+export declare function messageTextOf(message: GuidanceMessage | undefined | null): string;
+/**
+ * Build a filled carrier. Returns null for empty/whitespace text — there is
+ * nothing to deliver, and an empty carrier must not be created by value sites
+ * (find-or-create sites use {@link ensureGuidanceCarrier} instead).
+ *
+ * `extraInfo` (e.g. agent/sessionID) is merged into info alongside id/role.
+ */
+export declare function buildGuidanceCarrier(kind: string, text: string, extraInfo?: Record<string, unknown>): GuidanceMessage | null;
+/**
+ * Find the first guidance carrier, or `unshift` a new EMPTY one (zero parts —
+ * inert under the host's `parts.length === 0` continue; it renders nothing until
+ * a producer fills it, and it is never fence-only, because a fence-only text part
+ * WOULD render).
+ */
+export declare function ensureGuidanceCarrier(messages: GuidanceMessage[], kind: string): GuidanceMessage;
+/**
+ * Prepend a block to the carrier's directive body (top-of-body, preserving the
+ * historical `block + existing` order the system-message sites used). The first
+ * fill creates the single text part with fence + body + close; later prepends
+ * insert inside the existing fence. Never produces a second fence.
+ *
+ * Returns the delivered block, or null when the block is empty/whitespace
+ * (nothing changed — the carrier stays exactly as it was).
+ */
+export declare function prependGuidanceText(carrier: GuidanceMessage, kind: string, block: string): string | null;
+/**
+ * Splice a filled carrier at `atIndex`. Returns the inserted entry, or null when
+ * the text is empty/whitespace (nothing inserted).
+ */
+export declare function insertGuidanceCarrier(messages: GuidanceMessage[], kind: string, text: string, atIndex: number, extraInfo?: Record<string, unknown>): GuidanceMessage | null;
+/** Push a filled carrier at the end. Returns the appended entry or null (empty text). */
+export declare function appendGuidanceCarrier(messages: GuidanceMessage[], kind: string, text: string, extraInfo?: Record<string, unknown>): GuidanceMessage | null;
+/**
+ * Host-render SHAPE predicate: the entry is in the exact shape the pinned host
+ * renders into the model request (user branch of toModelMessagesEffect).
+ */
+export declare function isRenderableGuidance(entry: GuidanceMessage | null | undefined): boolean;
+/**
+ * Delivery gate for producer telemetry (replaces the pre-#2526 self-referential
+ * "I appended it to my own array" predicate). Delivery is recorded only when
+ * this call produced a non-empty (trimmed) delta AND the resulting entry is in
+ * the host-renderable shape. Pinned end-to-end by the host-contract tests.
+ */
+export declare function deliveredGuidanceDelta(entry: GuidanceMessage | null | undefined, delta: string | null): boolean;