@poetic-ai/poetic 1.42.0

package/integrations/bb-plugin-poetic/src/monitor-service.ts

@@ -0,0 +1,233 @@
+/**
+ * Server-side authoritative polling for the Poetic panel.
+ *
+ * BB's background service owns the polling cadence; the frontend keeps only
+ * connection/watchdog behavior. Each tick re-reads Poetic for every repository a
+ * panel has selected, then publishes an ephemeral realtime signal so the panel
+ * refetches. The signal carries no run state: it is an invalidation hint, and it
+ * is published only AFTER authoritative polling has already happened, so a
+ * dropped signal costs a refresh, never correctness.
+ *
+ * Nothing here is a daemon or an event journal. The service lives exactly as long
+ * as the plugin load: its abort signal ends it on dispose, reload, disable, and
+ * shutdown. Per-target last-poll timestamps select active vs idle cadence so one
+ * live repository does not force a 2.5s reread on idle siblings. No run status
+ * is stored here.
+ */
+
+/** Authoritative server-side cadence while at least one run is non-terminal. */
+export const MONITOR_ACTIVE_INTERVAL_MS = 2_500;
+
+/** Cadence while every known run is terminal — enough to notice a new launch. */
+export const MONITOR_IDLE_INTERVAL_MS = 30_000;
+
+/**
+ * How long a repository stays watched after the last panel request. A panel that
+ * closed stops being polled without needing an explicit unsubscribe.
+ */
+export const MONITOR_WATCH_TTL_MS = 5 * 60 * 1000;
+
+/** Realtime channel carrying invalidation hints only. */
+export const MONITOR_CHANNEL = 'runs';
+
+export interface MonitorTarget {
+  projectId: string;
+  sourceId: string;
+}
+
+/**
+ * Ephemeral invalidation hint. It names what to refetch and nothing about
+ * outcome — deliberately no status, phase, progress, verdict, or evidence, so a
+ * client can never render run state from a signal.
+ */
+export interface MonitorInvalidation {
+  type: 'invalidate';
+  projectId: string;
+  sourceId: string;
+  /** Advisory count of runs the server saw, for watchdog display only. */
+  observedRuns: number;
+  /** Whether any observed run was non-terminal, so the panel can pace itself. */
+  active: boolean;
+  observedAt: string;
+}
+
+/** Match an untrusted realtime payload to the panel target it should wake. */
+export function isInvalidationForTarget(payload: unknown, target: MonitorTarget): boolean {
+  if (typeof payload !== 'object' || payload === null || Array.isArray(payload)) return false;
+  const candidate = payload as Record<string, unknown>;
+  return (
+    candidate.type === 'invalidate' &&
+    candidate.projectId === target.projectId &&
+    candidate.sourceId === target.sourceId
+  );
+}
+
+interface WatchEntry extends MonitorTarget {
+  key: string;
+  lastRequestedAt: number;
+  /** Last successful authoritative read for this target, if any. */
+  lastPolledAt?: number;
+  /** Whether that last successful read still had a non-terminal run. */
+  lastActive?: boolean;
+}
+
+export interface MonitorDependencies {
+  /**
+   * Authoritative read for one target. Returns the observed run cards. Narration
+   * is never requested here: background polling must not issue model calls.
+   */
+  pollTarget(target: MonitorTarget): Promise<{ terminal: boolean; runs: number }>;
+  publish(channel: string, payload: MonitorInvalidation): void;
+  log(message: string): void;
+  now?: () => number;
+  /** Injectable sleep so tests drive the loop without real timers. */
+  sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
+  activeIntervalMs?: number;
+  idleIntervalMs?: number;
+  watchTtlMs?: number;
+}
+
+function defaultSleep(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise<void>((resolve) => {
+    if (signal.aborted) {
+      resolve();
+      return;
+    }
+    const timer = setTimeout(finish, ms);
+    signal.addEventListener('abort', finish, { once: true });
+    function finish(): void {
+      clearTimeout(timer);
+      signal.removeEventListener('abort', finish);
+      resolve();
+    }
+  });
+}
+
+function watchKey(target: MonitorTarget): string {
+  return `${target.projectId}\n${target.sourceId}`;
+}
+
+/**
+ * Owns the authoritative polling cadence and the ephemeral invalidation signal.
+ *
+ * A repository is watched because a panel asked about it, and stops being watched
+ * when it goes quiet. Poll failures are logged and skipped: the next tick retries
+ * and the panel's own fetch surfaces the error, so a transient Poetic failure
+ * never stops the service or produces a fabricated card.
+ */
+export class RunMonitorService {
+  private readonly watched = new Map<string, WatchEntry>();
+  private readonly now: () => number;
+  private readonly sleep: (ms: number, signal: AbortSignal) => Promise<void>;
+  private readonly activeIntervalMs: number;
+  private readonly idleIntervalMs: number;
+  private readonly watchTtlMs: number;
+  private running = false;
+
+  constructor(private readonly deps: MonitorDependencies) {
+    this.now = deps.now ?? Date.now;
+    this.sleep = deps.sleep ?? defaultSleep;
+    this.activeIntervalMs = deps.activeIntervalMs ?? MONITOR_ACTIVE_INTERVAL_MS;
+    this.idleIntervalMs = deps.idleIntervalMs ?? MONITOR_IDLE_INTERVAL_MS;
+    this.watchTtlMs = deps.watchTtlMs ?? MONITOR_WATCH_TTL_MS;
+  }
+
+  /**
+   * Note that a panel is interested in this target. Called from every RPC that
+   * resolves a repository, so interest tracks real UI activity rather than a
+   * separate subscribe/unsubscribe protocol that could leak a watcher.
+   */
+  observe(target: MonitorTarget): void {
+    const key = watchKey(target);
+    const existing = this.watched.get(key);
+    this.watched.set(key, {
+      key,
+      projectId: target.projectId,
+      sourceId: target.sourceId,
+      lastRequestedAt: this.now(),
+      lastPolledAt: existing?.lastPolledAt,
+      lastActive: existing?.lastActive,
+    });
+  }
+
+  /** Targets currently within the watch TTL. Expired entries are dropped. */
+  activeTargets(): MonitorTarget[] {
+    const cutoff = this.now() - this.watchTtlMs;
+    for (const [key, entry] of this.watched) {
+      if (entry.lastRequestedAt < cutoff) this.watched.delete(key);
+    }
+    return [...this.watched.values()].map((entry) => ({
+      projectId: entry.projectId,
+      sourceId: entry.sourceId,
+    }));
+  }
+
+  /** True while the service loop is running. Used by teardown assertions. */
+  isRunning(): boolean {
+    return this.running;
+  }
+
+  /**
+   * Run until `signal` aborts. BB restarts a crashed service with backoff, so
+   * the loop itself never swallows an abort or spins on failure.
+   */
+  async start(signal: AbortSignal): Promise<void> {
+    this.running = true;
+    try {
+      while (!signal.aborted) {
+        const active = await this.tick();
+        if (signal.aborted) break;
+        await this.sleep(active ? this.activeIntervalMs : this.idleIntervalMs, signal);
+      }
+    } finally {
+      this.running = false;
+      this.watched.clear();
+    }
+  }
+
+  /**
+   * One authoritative pass over every watched target. Returns whether any target
+   * still has a non-terminal run, which selects the next interval.
+   */
+  async tick(): Promise<boolean> {
+    let anyActive = false;
+    const now = this.now();
+    for (const target of this.activeTargets()) {
+      const entry = this.watched.get(watchKey(target));
+      if (!entry) continue;
+      if (entry.lastActive === true) anyActive = true;
+      const interval = entry.lastActive === true ? this.activeIntervalMs : this.idleIntervalMs;
+      if (entry.lastPolledAt !== undefined && now - entry.lastPolledAt < interval) {
+        continue;
+      }
+      let observation: { terminal: boolean; runs: number };
+      try {
+        observation = await this.deps.pollTarget(target);
+      } catch (error) {
+        // The panel's own fetch reports the error to the user; the service keeps
+        // its cadence rather than inventing state or stopping.
+        this.deps.log(
+          `Poetic run monitor could not read ${target.projectId}/${target.sourceId}: ${
+            error instanceof Error ? error.message : String(error)
+          }`
+        );
+        continue;
+      }
+      const active = !observation.terminal;
+      entry.lastPolledAt = this.now();
+      entry.lastActive = active;
+      if (active) anyActive = true;
+      // Published after the authoritative read, so a client that refetches on
+      // this hint sees state at least as fresh as the read that triggered it.
+      this.deps.publish(MONITOR_CHANNEL, {
+        type: 'invalidate',
+        projectId: target.projectId,
+        sourceId: target.sourceId,
+        observedRuns: observation.runs,
+        active,
+        observedAt: new Date(this.now()).toISOString(),
+      });
+    }
+    return anyActive;
+  }
+}

package/integrations/bb-plugin-poetic/src/panel-read-ux.ts

@@ -0,0 +1,97 @@
+/**
+ * Presentation helpers for BB panel read latency: poll cadence flags and
+ * stale-card hops. No Poetic commands, caches, or repository writes.
+ */
+
+export type PanelVisibility = 'visible' | 'hidden' | 'prerender';
+
+export type PollRunsTrigger =
+  | 'ready'
+  | 'invalidate'
+  | 'reconnect'
+  | 'refresh'
+  | 'visible'
+  | 'watchdog';
+
+export interface PollRunsFlags {
+  observe: boolean;
+  fresh: boolean;
+  narrate: boolean;
+}
+
+/**
+ * Stable ready-target key. Same project+source while the repository is present
+ * and not blocked, regardless of object identity from later setRepository calls.
+ */
+export function targetReadyIdentity(
+  target: { projectId: string; sourceId: string } | null,
+  repository: { projectId: string; sourceId: string; state: string } | null
+): string | null {
+  if (!target || !repository || repository.state === 'blocked') return null;
+  if (repository.projectId !== target.projectId || repository.sourceId !== target.sourceId) {
+    return null;
+  }
+  return `${target.projectId}\n${target.sourceId}`;
+}
+
+/**
+ * Flags for one pollRuns call. Hidden invalidate and hidden watchdog return
+ * null so the panel does not call pollRuns at all.
+ */
+export function pollRunsFlags(
+  trigger: PollRunsTrigger,
+  visibility: PanelVisibility
+): PollRunsFlags | null {
+  const visible = visibility === 'visible';
+  switch (trigger) {
+    case 'invalidate':
+      if (!visible) return null;
+      return { observe: true, fresh: false, narrate: true };
+    case 'watchdog':
+      if (!visible) return null;
+      return { observe: true, fresh: false, narrate: false };
+    case 'reconnect':
+      return { observe: visible, fresh: true, narrate: visible };
+    case 'refresh':
+      return { observe: true, fresh: true, narrate: true };
+    case 'visible':
+      return { observe: true, fresh: true, narrate: true };
+    case 'ready':
+      return { observe: visible, fresh: false, narrate: visible };
+  }
+}
+
+export interface EntityHopInput {
+  displayedId: string | null;
+  requestedId: string | null;
+  inFlight: boolean;
+}
+
+export interface EntityHopView {
+  actionsDisabled: boolean;
+  showingPrevious: boolean;
+  banner: string | null;
+}
+
+/**
+ * Stale-card hop presentation. Keep the previous entity on screen, label it,
+ * and disable mutations until the displayed id is the requested id.
+ */
+export function entityHopView(input: EntityHopInput): EntityHopView {
+  const { displayedId, requestedId, inFlight } = input;
+  if (requestedId === null) {
+    return { actionsDisabled: false, showingPrevious: false, banner: null };
+  }
+  const showingPrevious = displayedId !== null && displayedId !== requestedId;
+  const actionsDisabled = inFlight || displayedId !== requestedId;
+  return {
+    actionsDisabled,
+    showingPrevious,
+    banner: showingPrevious ? `Showing previous item while reading ${requestedId}` : null,
+  };
+}
+
+/** Keep a held card across hops and failed reads; only a first load has none. */
+export function keepDisplayedCard(displayedId: string | null): boolean {
+  return displayedId !== null;
+}

package/integrations/bb-plugin-poetic/src/patch-preview-schema.ts

@@ -0,0 +1,166 @@
+/**
+ * Wire schemas for BB's narrow, read-only patch-preview path.
+ *
+ * A preview request never carries a path, a URL, an executable, argv, a cwd, or
+ * an environment. It identifies the selected repository, the run, and one
+ * reference that must still be present in a freshly reread canonical evidence
+ * set. Only a reference whose canonical kind is `patch` may reach preview
+ * resolution; every other kind is refused before any file is opened.
+ *
+ * Kept in its own module, like `repository-schema.ts`, so the shapes can be
+ * validated without loading the BB plugin SDK.
+ */
+
+import { z } from 'zod';
+import { type EvidenceReferenceView, resultRunIdSchema } from './result-readback-schema.js';
+
+/** Fixed byte ceiling for one preview body. Reads never exceed it. */
+export const PATCH_PREVIEW_MAX_BYTES = 262_144;
+
+/** Bound on the reference value a caller may submit for lookup. */
+export const PATCH_PREVIEW_MAX_REFERENCE_CHARS = 4_096;
+
+export const PATCH_PREVIEW_VIEW_VERSION = '1.0.0' as const;
+
+/**
+ * The canonical evidence kinds a caller may name. Requests are accepted for
+ * every kind so that a non-patch kind receives an explicit refusal rather than
+ * an opaque validation error, but only `patch` can reach resolution.
+ */
+const CANONICAL_EVIDENCE_KINDS = [
+  'artifact',
+  'branch',
+  'changed_file',
+  'commit',
+  'delivery',
+  'judge',
+  'patch',
+  'synthesis',
+  'verification',
+  'worktree',
+] as const satisfies readonly EvidenceReferenceView['kind'][];
+
+/** `never` while the list above still covers every canonical evidence kind. */
+type UncoveredEvidenceKind = Exclude<
+  EvidenceReferenceView['kind'],
+  (typeof CANONICAL_EVIDENCE_KINDS)[number]
+>;
+
+/** `'complete'` only while no canonical evidence kind is missing above. */
+export type PatchPreviewKindCoverage = [UncoveredEvidenceKind] extends [never]
+  ? 'complete'
+  : UncoveredEvidenceKind;
+
+export const patchPreviewReferenceSchema = z
+  .object({
+    kind: z.enum(CANONICAL_EVIDENCE_KINDS),
+    value: z.string().min(1).max(PATCH_PREVIEW_MAX_REFERENCE_CHARS),
+    variant: z.string().min(1).max(200).optional(),
+  })
+  .strict();
+
+export const patchPreviewInputSchema = z
+  .object({
+    projectId: z.string().min(1),
+    sourceId: z.string().min(1),
+    runId: resultRunIdSchema,
+    kind: z.enum(['competition', 'fusion', 'backlog-execute']),
+    reference: patchPreviewReferenceSchema,
+  })
+  .strict();
+
+/** Refusals this feature decides itself, each without disclosing a host path. */
+export const patchPreviewRefusalReasonSchema = z.enum([
+  'invalid-request',
+  'cross-repository',
+  'cross-run',
+  'unknown-reference',
+  'unsupported-kind',
+  'unsafe-path',
+  'symlink',
+  'not-a-regular-file',
+  'missing',
+  'compressed',
+  'binary',
+]);
+
+/** States where canonical evidence, not the request, is the blocker. */
+export const patchPreviewUnavailableReasonSchema = z.enum([
+  'evidence-unavailable',
+  'incompatible-evidence',
+  'read-failed',
+]);
+
+const previewIdentity = {
+  projectId: z.string(),
+  sourceId: z.string(),
+  runId: z.string(),
+} as const;
+
+const previewedReferenceSchema = z
+  .object({
+    kind: z.literal('patch'),
+    value: z.string(),
+    variant: z.string().nullable(),
+  })
+  .strict();
+
+/**
+ * Preview responses carry bounded text plus metadata only. The selected
+ * repository's absolute path is deliberately absent: this feature adds no host
+ * path disclosure of its own.
+ */
+export const patchPreviewResultSchema = z.discriminatedUnion('state', [
+  z
+    .object({
+      ...previewIdentity,
+      state: z.literal('previewed'),
+      reference: previewedReferenceSchema,
+      byteLength: z.number().int().nonnegative().max(PATCH_PREVIEW_MAX_BYTES),
+      truncated: z.boolean(),
+      lineCount: z.number().int().nonnegative(),
+      text: z.string(),
+    })
+    .strict(),
+  z
+    .object({
+      ...previewIdentity,
+      state: z.literal('refused'),
+      reason: patchPreviewRefusalReasonSchema,
+      message: z.string(),
+    })
+    .strict(),
+  z
+    .object({
+      ...previewIdentity,
+      state: z.literal('unavailable'),
+      reason: patchPreviewUnavailableReasonSchema,
+      message: z.string(),
+    })
+    .strict(),
+]);
+
+export const patchPreviewViewSchema = z
+  .object({
+    viewVersion: z.literal(PATCH_PREVIEW_VIEW_VERSION),
+    state: z.enum(['previewed', 'truncated', 'unavailable', 'refused']),
+    runId: z.string(),
+    headline: z.string(),
+    reference: previewedReferenceSchema.nullable(),
+    rows: z
+      .array(z.object({ id: z.string(), label: z.string(), value: z.string() }).strict())
+      .readonly(),
+    /** Bounded patch text when previewed; null in every other state. */
+    body: z.string().nullable(),
+    notices: z.array(z.string()).readonly(),
+    /** This surface intentionally has no apply, write, or merge controls. */
+    controls: z.tuple([]).readonly(),
+  })
+  .strict();
+
+export type PatchPreviewInput = z.infer<typeof patchPreviewInputSchema>;
+export type PatchPreviewReference = z.infer<typeof patchPreviewReferenceSchema>;
+export type PatchPreviewRefusalReason = z.infer<typeof patchPreviewRefusalReasonSchema>;
+export type PatchPreviewUnavailableReason = z.infer<typeof patchPreviewUnavailableReasonSchema>;
+export type PatchPreviewResult = z.infer<typeof patchPreviewResultSchema>;
+export type PatchPreviewView = z.infer<typeof patchPreviewViewSchema>;