@llblab/pi-kit 0.1.13 → 0.3.0

package/node_modules/@llblab/pi-actors/dist/lib/pi.js

@@ -3,6 +3,9 @@
  * Zones: pi agent sdk boundary, extension host adapters
  * Owns direct pi SDK imports and exposes narrow pi-actors-facing helpers/types for the composition root.
  */
+import * as SessionEvidence from "./session-evidence.js";
+export const RUN_COMPLETION_BATCH_CUSTOM_TYPE = "pi-actors-run-batch";
+export const RUN_STEER_CUSTOM_TYPE = "pi-actors-run-steer";
 export function getSessionId(ctx) {
     return ctx.sessionManager.getSessionId();
 }
@@ -15,6 +18,183 @@ export function createNotificationSink(pi, ctx) {
         }),
     };
 }
+export function sendRunCompletionBatch(pi, batchId, content) {
+    pi.sendMessage({
+        customType: RUN_COMPLETION_BATCH_CUSTOM_TYPE,
+        content,
+        display: false,
+        details: {
+            pi_actors_delivery: {
+                batch_id: batchId,
+                kind: "completion_batch",
+            },
+        },
+    }, {
+        deliverAs: "followUp",
+        triggerTurn: true,
+    });
+}
+export function sendRunSteer(pi, input) {
+    pi.sendMessage({
+        customType: RUN_STEER_CUSTOM_TYPE,
+        content: input.content,
+        display: false,
+        details: {
+            pi_actors_delivery: {
+                event_id: input.eventId,
+                kind: "urgent_steer",
+                steer_id: input.steerId,
+            },
+        },
+    }, {
+        deliverAs: "steer",
+        triggerTurn: true,
+    });
+}
+function completionBatchMessage(message) {
+    if (!message || typeof message !== "object" || Array.isArray(message))
+        return undefined;
+    const record = message;
+    if (record.customType !== RUN_COMPLETION_BATCH_CUSTOM_TYPE ||
+        typeof record.content !== "string")
+        return undefined;
+    const details = record.details;
+    if (!details || typeof details !== "object" || Array.isArray(details))
+        return undefined;
+    const delivery = details.pi_actors_delivery;
+    if (!delivery || typeof delivery !== "object" || Array.isArray(delivery))
+        return undefined;
+    const envelope = delivery;
+    if (envelope.kind !== "completion_batch" ||
+        typeof envelope.batch_id !== "string" ||
+        !envelope.batch_id ||
+        envelope.batch_id.length > 128)
+        return undefined;
+    return { batchId: envelope.batch_id, content: record.content };
+}
+/** Collapse exact retry duplicates and remove conflicting delivery envelopes. */
+export function dedupeRunCompletionBatchContext(messages) {
+    const batches = new Map();
+    const conflicts = new Set();
+    for (const message of messages) {
+        const batch = completionBatchMessage(message);
+        if (!batch)
+            continue;
+        const existing = batches.get(batch.batchId);
+        if (existing !== undefined && existing !== batch.content) {
+            conflicts.add(batch.batchId);
+        }
+        else if (existing === undefined) {
+            batches.set(batch.batchId, batch.content);
+        }
+    }
+    const retained = new Set();
+    const filtered = messages.filter((message) => {
+        const batch = completionBatchMessage(message);
+        if (!batch)
+            return true;
+        if (conflicts.has(batch.batchId) || retained.has(batch.batchId))
+            return false;
+        retained.add(batch.batchId);
+        return true;
+    });
+    for (const batchId of conflicts)
+        batches.delete(batchId);
+    return { batches, conflicts, messages: filtered };
+}
+export function removeRunCompletionBatchFromContext(messages, batchId) {
+    return messages.filter((message) => completionBatchMessage(message)?.batchId !== batchId);
+}
+function steerMessage(message) {
+    if (!message || typeof message !== "object" || Array.isArray(message))
+        return undefined;
+    const record = message;
+    if (record.customType !== RUN_STEER_CUSTOM_TYPE || typeof record.content !== "string") {
+        return undefined;
+    }
+    const details = record.details;
+    if (!details || typeof details !== "object" || Array.isArray(details))
+        return undefined;
+    const delivery = details.pi_actors_delivery;
+    if (!delivery || typeof delivery !== "object" || Array.isArray(delivery))
+        return undefined;
+    const envelope = delivery;
+    if (envelope.kind !== "urgent_steer" ||
+        typeof envelope.steer_id !== "string" ||
+        !envelope.steer_id ||
+        envelope.steer_id.length > 128 ||
+        typeof envelope.event_id !== "string" ||
+        !envelope.event_id ||
+        envelope.event_id.length > 256)
+        return undefined;
+    return {
+        content: record.content,
+        eventId: envelope.event_id,
+        steerId: envelope.steer_id,
+    };
+}
+export function dedupeRunSteerContext(messages) {
+    const conflicts = new Set();
+    const steers = new Map();
+    for (const message of messages) {
+        const steer = steerMessage(message);
+        if (!steer)
+            continue;
+        const existing = steers.get(steer.steerId);
+        if (existing &&
+            (existing.content !== steer.content || existing.eventId !== steer.eventId)) {
+            conflicts.add(steer.steerId);
+        }
+        else if (!existing) {
+            steers.set(steer.steerId, {
+                content: steer.content,
+                eventId: steer.eventId,
+            });
+        }
+    }
+    const retained = new Set();
+    const filtered = messages.filter((message) => {
+        const steer = steerMessage(message);
+        if (!steer)
+            return true;
+        if (conflicts.has(steer.steerId) || retained.has(steer.steerId))
+            return false;
+        retained.add(steer.steerId);
+        return true;
+    });
+    for (const steerId of conflicts)
+        steers.delete(steerId);
+    return { conflicts, messages: filtered, steers };
+}
+export function removeRunSteerFromContext(messages, steerId) {
+    return messages.filter((message) => steerMessage(message)?.steerId !== steerId);
+}
+export function inspectRunSteerSessionEvidence(ctx, input) {
+    return SessionEvidence.inspectBoundedActiveSessionEntries({
+        getEntry: (id) => ctx.sessionManager.getEntry(id),
+        leaf: ctx.sessionManager.getLeafEntry(),
+        match: (entry) => {
+            const steer = steerMessage(entry);
+            if (!steer || steer.steerId !== input.steerId)
+                return undefined;
+            return steer.content === input.content && steer.eventId === input.eventId
+                ? "present"
+                : "conflict";
+        },
+    });
+}
+export function inspectRunCompletionBatchSessionEvidence(ctx, batchId, content) {
+    return SessionEvidence.inspectBoundedActiveSessionEntries({
+        getEntry: (id) => ctx.sessionManager.getEntry(id),
+        leaf: ctx.sessionManager.getLeafEntry(),
+        match: (entry) => {
+            const batch = completionBatchMessage(entry);
+            if (!batch || batch.batchId !== batchId)
+                return undefined;
+            return batch.content === content ? "present" : "conflict";
+        },
+    });
+}
 export function registerToolDefinitions(pi, definitions) {
     for (const definition of definitions)
         pi.registerTool(definition);

package/node_modules/@llblab/pi-actors/dist/lib/run-delivery.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Coordinator delivery persistence.
+ * Zones: owner-scoped completion batches, delivery phase fencing, bounded receipts
+ * Owns durable delivery state; excludes Run discovery, Pi scheduling, and model formatting.
+ */
+export type RunCompletionDeliveryStatus = "done" | "failed" | "killed" | "exited";
+export type RunDeliveryPhase = "pending" | "queued" | "presented";
+export interface RunCompletionBatchMember {
+    artifacts?: Record<string, string>;
+    run: string;
+    run_instance_id: string;
+    state_dir: string;
+    status: RunCompletionDeliveryStatus;
+    summary: string;
+    terminal_at: string;
+}
+export interface RunCompletionBatch {
+    attempts?: number;
+    batch_id: string;
+    created_at: string;
+    last_error?: string;
+    last_failed_at?: string;
+    members: RunCompletionBatchMember[];
+    phase: RunDeliveryPhase;
+    presented_at?: string;
+    queued_at?: string;
+}
+export interface RunSteerEnvelope {
+    attempts?: number;
+    content: string;
+    created_at: string;
+    event_id: string;
+    kind: string;
+    last_error?: string;
+    last_failed_at?: string;
+    level: "info" | "warning" | "error";
+    occurred_at: string;
+    phase: RunDeliveryPhase;
+    presented_at?: string;
+    queued_at?: string;
+    run: string;
+    run_instance_id: string;
+    state_dir: string;
+    steer_id: string;
+}
+export interface RunDeliveryReceipt {
+    delivery_id: string;
+    kind: "completion_batch" | "urgent_steer";
+    presented_at: string;
+}
+export interface RunDeliveryJournal {
+    completion_batch?: RunCompletionBatch;
+    owner_id: string;
+    receipts: RunDeliveryReceipt[];
+    schema: "run-delivery-v1";
+    steers: RunSteerEnvelope[];
+}
+export interface AdmitRunCompletionBatchInput {
+    batchId?: string;
+    members: RunCompletionBatchMember[];
+    now?: Date;
+    ownerId: string;
+    tempDir: string;
+}
+export interface RunDeliveryTransitionInput {
+    batchId: string;
+    now?: Date;
+    ownerId: string;
+    tempDir: string;
+}
+export interface AdmitRunSteerEnvelopeInput {
+    content: string;
+    eventId: string;
+    kind: string;
+    level: "info" | "warning" | "error";
+    now?: Date;
+    occurredAt: string;
+    ownerId: string;
+    run: string;
+    runInstanceId: string;
+    stateDir: string;
+    steerId?: string;
+    tempDir: string;
+}
+export interface RunSteerTransitionInput {
+    now?: Date;
+    ownerId: string;
+    steerId: string;
+    tempDir: string;
+}
+export declare function getRunDeliveryJournalPath(tempDir: string, ownerId: string): string;
+export declare function readRunDeliveryJournal(tempDir: string, ownerId: string): RunDeliveryJournal;
+export declare function admitRunCompletionBatch(input: AdmitRunCompletionBatchInput): RunCompletionBatch;
+export declare function markRunCompletionBatchQueued(input: RunDeliveryTransitionInput): boolean;
+export declare function resetRunCompletionBatchPending(input: Omit<RunDeliveryTransitionInput, "now">): boolean;
+export declare function recordRunCompletionBatchDeliveryFailure(input: RunDeliveryTransitionInput & {
+    error: unknown;
+}): boolean;
+export declare function markRunCompletionBatchPresented(input: RunDeliveryTransitionInput): boolean;
+export declare function finalizeRunCompletionBatch(input: Omit<RunDeliveryTransitionInput, "now">): boolean;
+export declare function getRunSteerDeliveryId(input: {
+    eventId: string;
+    runInstanceId: string;
+    stateDir: string;
+}): string;
+export declare function admitRunSteerEnvelope(input: AdmitRunSteerEnvelopeInput): RunSteerEnvelope | undefined;
+export declare function markRunSteerQueued(input: RunSteerTransitionInput): boolean;
+export declare function resetRunSteerPending(input: Omit<RunSteerTransitionInput, "now">): boolean;
+export declare function recordRunSteerDeliveryFailure(input: RunSteerTransitionInput & {
+    error: unknown;
+}): boolean;
+export declare function markRunSteerPresented(input: RunSteerTransitionInput): boolean;
+export declare function finalizeRunSteer(input: Omit<RunSteerTransitionInput, "now">): boolean;
+/** Format one immutable batch for a model-bound custom message. */
+export declare function formatRunCompletionBatchMessage(batch: RunCompletionBatch): string;