@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

package/src/harness-chat-lifecycle.ts

@@ -0,0 +1,170 @@
+import type { HarnessChatSession, HarnessChatSnapshot } from './harness-chat-types';
+
+export type HarnessChatLifecycleKind =
+  | 'idle'
+  | 'offline'
+  | 'mirror'
+  | 'mirror-reconnecting'
+  | 'live-terminal'
+  | 'editor'
+  | 'resumed'
+  | 'branched';
+
+export interface HarnessChatLifecycle {
+  kind: HarnessChatLifecycleKind;
+  label: string;
+  detail: string;
+  canCompose: boolean;
+  controlAction: 'detach' | 'openTerminal' | null;
+  controlActionLabel: string | null;
+}
+
+/**
+ * One presentation vocabulary over Supercode's authoritative connection
+ * state. This is deliberately derived: VGAI does not own a second session
+ * state machine and cannot drift from the runtime semantics.
+ */
+export function harnessChatLifecycle(snapshot: HarnessChatSnapshot): HarnessChatLifecycle {
+  if (snapshot.status === 'unavailable' || snapshot.status === 'error') {
+    return {
+      kind: 'offline',
+      label: 'OFFLINE',
+      detail: 'The local coding runtime is unavailable.',
+      canCompose: false,
+      controlAction: null,
+      controlActionLabel: null,
+    };
+  }
+  if (snapshot.mode === 'observe') {
+    const retrying = snapshot.connection.follow === 'retrying';
+    return {
+      kind: retrying ? 'mirror-reconnecting' : 'mirror',
+      label: retrying ? 'MIRROR · RECONNECTING' : 'MIRROR · READ ONLY',
+      detail: retrying
+        ? 'The saved transcript is temporarily unavailable; Supercode is retrying.'
+        : 'Following the saved transcript without controlling its process.',
+      canCompose: false,
+      controlAction: null,
+      controlActionLabel: null,
+    };
+  }
+  if (snapshot.mode !== 'control') {
+    return {
+      kind: 'idle',
+      label: 'READY',
+      detail: 'Start a new chat or open an existing session.',
+      canCompose: true,
+      controlAction: null,
+      controlActionLabel: null,
+    };
+  }
+  switch (snapshot.connection.strategy) {
+    case 'attach':
+      return {
+        kind: 'live-terminal',
+        label: 'LIVE · TERMINAL',
+        detail: 'The editor and another frontend share one live runtime.',
+        canCompose: snapshot.availableActions.send || snapshot.turn.state !== 'idle',
+        controlAction: 'detach',
+        controlActionLabel: 'Disconnect live',
+      };
+    case 'resume':
+      return {
+        kind: 'resumed',
+        label: 'RESUMED HERE',
+        detail: 'The editor controls a continuation of the saved conversation.',
+        canCompose: snapshot.availableActions.send || snapshot.turn.state !== 'idle',
+        controlAction: 'openTerminal',
+        controlActionLabel: 'Open in terminal',
+      };
+    case 'branch':
+      return {
+        kind: 'branched',
+        label: 'BRANCHED',
+        detail: 'This is an independent continuation of the source conversation.',
+        canCompose: snapshot.availableActions.send || snapshot.turn.state !== 'idle',
+        controlAction: 'openTerminal',
+        controlActionLabel: 'Open in terminal',
+      };
+    default:
+      return {
+        kind: 'editor',
+        label: 'EDITOR · LIVE',
+        detail: 'This live runtime was started and is controlled by the editor.',
+        canCompose: snapshot.availableActions.send || snapshot.turn.state !== 'idle',
+        controlAction: 'openTerminal',
+        controlActionLabel: 'Open in terminal',
+      };
+  }
+}
+
+export interface HarnessChatReconnectPreference {
+  workspace: string;
+  sessionIdentity: string;
+  connection: 'observe' | 'attach';
+}
+
+// v2 stores Supercode's opaque identity. Do not read the former v1 values:
+// they contained reversible locator fingerprints from the pre-v3 wire contract.
+const RECONNECT_KEY = 'vgai:harness-chat:reconnect:v2';
+
+function preferenceRecord(value: unknown): Record<string, HarnessChatReconnectPreference> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return {};
+  const result: Record<string, HarnessChatReconnectPreference> = {};
+  for (const [workspace, candidate] of Object.entries(value)) {
+    if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate)) continue;
+    const item = candidate as Partial<HarnessChatReconnectPreference>;
+    if (
+      item.workspace === workspace &&
+      typeof item.sessionIdentity === 'string' &&
+      /^scs_[a-f0-9]{64}$/.test(item.sessionIdentity) &&
+      (item.connection === 'observe' || item.connection === 'attach')
+    ) {
+      result[workspace] = item as HarnessChatReconnectPreference;
+    }
+  }
+  return result;
+}
+
+export function readHarnessChatReconnectPreference(
+  storage: Pick<Storage, 'getItem'>,
+  workspace: string,
+): HarnessChatReconnectPreference | null {
+  try {
+    const raw = storage.getItem(RECONNECT_KEY);
+    if (!raw) return null;
+    return preferenceRecord(JSON.parse(raw))[workspace] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export function writeHarnessChatReconnectPreference(
+  storage: Pick<Storage, 'getItem' | 'setItem'>,
+  preference: HarnessChatReconnectPreference,
+): void {
+  try {
+    const raw = storage.getItem(RECONNECT_KEY);
+    const current = raw ? preferenceRecord(JSON.parse(raw)) : {};
+    current[preference.workspace] = preference;
+    storage.setItem(RECONNECT_KEY, JSON.stringify(current));
+  } catch {
+    // Browser persistence is an enhancement. A denied/quota-limited storage
+    // backend must not disable the live chat itself.
+  }
+}
+
+export function reconnectPreferenceForSnapshot(
+  snapshot: HarnessChatSnapshot,
+  session: HarnessChatSession | null,
+): HarnessChatReconnectPreference | null {
+  if (!snapshot.workspace || !session || snapshot.activeSessionId !== session.id) return null;
+  return {
+    workspace: snapshot.workspace,
+    sessionIdentity: session.identity,
+    connection:
+      snapshot.mode === 'control' && snapshot.connection.strategy === 'attach'
+        ? 'attach'
+        : 'observe',
+  };
+}

package/src/harness-chat-reconnect.ts

@@ -0,0 +1,85 @@
+import { useEffect, useRef } from 'react';
+import {
+  type HarnessChatReconnectPreference,
+  readHarnessChatReconnectPreference,
+  reconnectPreferenceForSnapshot,
+  writeHarnessChatReconnectPreference,
+} from './harness-chat-lifecycle';
+import type {
+  HarnessChatAction,
+  HarnessChatSession,
+  HarnessChatSnapshot,
+} from './harness-chat-types';
+
+interface ReconnectTracker {
+  generation: number;
+  preference: HarnessChatReconnectPreference | null;
+  attempted: boolean;
+}
+
+type RunAction = (action: HarnessChatAction) => Promise<HarnessChatSnapshot | null>;
+
+function readyForReconnect(snapshot: HarnessChatSnapshot): snapshot is HarnessChatSnapshot & {
+  workspace: string;
+} {
+  return (
+    Boolean(snapshot.workspace) &&
+    (snapshot.status === 'ready' || snapshot.status === 'working') &&
+    snapshot.operation === null
+  );
+}
+
+function resetTracker(
+  tracker: ReconnectTracker,
+  snapshot: HarnessChatSnapshot & { workspace: string },
+): void {
+  tracker.generation = snapshot.workspaceGeneration;
+  tracker.preference = readHarnessChatReconnectPreference(localStorage, snapshot.workspace);
+  tracker.attempted = false;
+}
+
+function synchronizeReconnect(
+  tracker: ReconnectTracker,
+  snapshot: HarnessChatSnapshot,
+  session: HarnessChatSession | null,
+  actionInFlight: boolean,
+  runAction: RunAction,
+): void {
+  if (!readyForReconnect(snapshot)) return;
+  if (tracker.generation !== snapshot.workspaceGeneration) resetTracker(tracker, snapshot);
+
+  if (!tracker.attempted && tracker.preference) {
+    if (!actionInFlight) {
+      tracker.attempted = true;
+      void runAction({
+        type: 'restore',
+        sessionIdentity: tracker.preference.sessionIdentity,
+        connection: tracker.preference.connection,
+      });
+    }
+    return;
+  }
+  if (actionInFlight) return;
+
+  const preference = reconnectPreferenceForSnapshot(snapshot, session);
+  if (preference) writeHarnessChatReconnectPreference(localStorage, preference);
+}
+
+/** Restore one exact session after browser/server reload, then remember later
+ * explicit selection changes. Runtime ownership remains in Supercode. */
+export function useHarnessChatReconnect(
+  snapshot: HarnessChatSnapshot,
+  session: HarnessChatSession | null,
+  actionInFlight: boolean,
+  runAction: RunAction,
+): void {
+  const tracker = useRef<ReconnectTracker>({
+    generation: -1,
+    preference: null,
+    attempted: false,
+  });
+  useEffect(
+    () => synchronizeReconnect(tracker.current, snapshot, session, actionInFlight, runAction),
+    [actionInFlight, runAction, session, snapshot],
+  );
+}

package/src/harness-chat-types.ts

@@ -0,0 +1,409 @@
+/**
+ * Browser/server contract for the permanent coding-agent surface.
+ *
+ * Supercode owns harness, session, transcript, and runtime semantics. This
+ * wire mirrors its frontend state instead of inventing a second state
+ * machine; VGAI adds only editor-specific presentation and context.
+ */
+
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+export type HarnessChatMode = 'none' | 'observe' | 'control';
+export type HarnessChatStatus = 'loading' | 'ready' | 'working' | 'error' | 'unavailable';
+/** Mirrors Supercode's passive/handshake authentication posture exactly. */
+export type HarnessChatAuthState = 'ready' | 'configured' | 'required' | 'unknown';
+export type HarnessChatRuntimeState = 'ready' | 'degraded' | 'unavailable';
+export type HarnessChatOperation =
+  | 'refresh'
+  | 'observe'
+  | 'start'
+  | 'resume'
+  | 'attach'
+  | 'branch'
+  | 'restore'
+  | 'detach'
+  | 'openTerminal'
+  | 'send'
+  | 'interrupt'
+  | 'respond'
+  | 'load'
+  | 'import'
+  | 'export'
+  | 'translate'
+  | 'handoff'
+  | 'workspace'
+  | 'close'
+  | null;
+
+export interface HarnessChatCapabilities {
+  startSession: boolean;
+  resumeSession: boolean;
+  attachExistingProcess: boolean;
+  sendInput: boolean;
+  streamEvents: boolean;
+  interrupt: boolean;
+  respondToRequests: boolean;
+}
+
+export interface HarnessChatHarness {
+  id: string;
+  label: string;
+  installed: boolean;
+  auth: HarnessChatAuthState;
+  runtime: HarnessChatRuntimeState;
+  protocol: string;
+  capabilities: HarnessChatCapabilities;
+  availableActions: {
+    start: boolean;
+    resume: boolean;
+    attach: boolean;
+    send: boolean;
+    interrupt: boolean;
+    respond: boolean;
+  };
+  reason: string | null;
+  repair: string | null;
+}
+
+export interface HarnessChatSession {
+  /** Opaque, controller-scoped key used by actions. */
+  id: string;
+  /** Stable, non-display identity used only to restore this exact selection. */
+  identity: string;
+  /** Harness-native identity, display/diagnostics only. */
+  nativeId?: string;
+  harness: string;
+  title: string;
+  cwd: string | null;
+  updatedAt: number | null;
+  messageCount: number | null;
+  model: string | null;
+  storage: 'file' | 'sqlite';
+  /** The trusted host has a reachable endpoint receipt for this session. */
+  attachable: boolean;
+}
+
+export interface HarnessChatMessageEntry {
+  id: string;
+  kind: 'message';
+  role: 'user' | 'assistant' | 'system';
+  text: string;
+  content?: JsonValue;
+  metadata: Record<string, string>;
+  visibility: 'conversation' | 'context';
+}
+
+export interface HarnessChatToolEntry {
+  id: string;
+  kind: 'tool';
+  callId: string | null;
+  name: string | null;
+  arguments: string | null;
+  resultText: string;
+  resultContent?: JsonValue;
+  status: 'pending' | 'completed' | 'error';
+  metadata: Record<string, string>;
+}
+
+export interface HarnessChatReasoningEntry {
+  id: string;
+  kind: 'reasoning';
+  text: string;
+  streaming: boolean;
+}
+
+export interface HarnessChatRequestOption {
+  optionId: string;
+  name: string;
+  kind: 'allow_once' | 'allow_always' | 'reject_once' | 'reject_always' | 'other';
+}
+
+export interface HarnessChatRequestEntry {
+  id: string;
+  kind: 'request';
+  requestId: JsonValue;
+  requestKind: string;
+  payload: JsonValue;
+  options: HarnessChatRequestOption[];
+  cancellable: boolean;
+  status: 'pending' | 'responded';
+  resolution: { optionId: string | null; name: string; kind: string } | null;
+}
+
+export interface HarnessChatNoticeEntry {
+  id: string;
+  kind: 'notice';
+  code: string;
+  text: string;
+}
+
+export type HarnessChatConversationEntry =
+  | HarnessChatMessageEntry
+  | HarnessChatToolEntry
+  | HarnessChatReasoningEntry
+  | HarnessChatRequestEntry
+  | HarnessChatNoticeEntry;
+
+export interface HarnessChatAvailableActions {
+  refresh: boolean;
+  observe: boolean;
+  start: boolean;
+  resume: boolean;
+  attach: boolean;
+  branch: boolean;
+  detach: boolean;
+  openTerminal: boolean;
+  send: boolean;
+  interrupt: boolean;
+  respond: boolean;
+}
+
+export interface HarnessChatPromptContext {
+  id: string;
+  label: string;
+  detail: string;
+}
+
+export interface HarnessChatError {
+  code: string;
+  message: string;
+  operation: Exclude<HarnessChatOperation, null> | 'runtime' | 'follow';
+  recoverable: boolean;
+}
+
+export interface HarnessChatSnapshot {
+  schema: 'vgai.harness-chat.v3';
+  revision: number;
+  /** Monotonic host generation. Revisions are only comparable within it. */
+  workspaceGeneration: number;
+  workspace: string | null;
+  status: HarnessChatStatus;
+  mode: HarnessChatMode;
+  operation: HarnessChatOperation;
+  harnesses: HarnessChatHarness[];
+  sessions: HarnessChatSession[];
+  activeHarness: string | null;
+  activeSessionId: string | null;
+  connection: {
+    strategy: 'start' | 'resume' | 'attach' | 'branch' | null;
+    follow: 'inactive' | 'following' | 'retrying';
+    ownsRuntime: boolean;
+  };
+  turn: {
+    state: 'idle' | 'running' | 'interrupting' | 'reconciling';
+    id: string | null;
+    startedAt: number | null;
+  };
+  conversation: HarnessChatConversationEntry[];
+  requests: HarnessChatRequestEntry[];
+  availableActions: HarnessChatAvailableActions;
+  error: HarnessChatError | null;
+  terminalCommand: string | null;
+}
+
+export type HarnessChatAction =
+  | { type: 'refresh' }
+  | { type: 'create'; harness: string }
+  | { type: 'observe'; sessionId: string }
+  | { type: 'resume'; sessionId: string }
+  | { type: 'attach'; sessionId: string }
+  | { type: 'branch'; sessionId: string }
+  | { type: 'restore'; sessionIdentity: string; connection: 'observe' | 'attach' }
+  | { type: 'detach' }
+  | { type: 'openTerminal' }
+  | { type: 'prompt'; text: string; context?: HarnessChatPromptContext[] }
+  | { type: 'interrupt' }
+  | { type: 'respond'; requestId: JsonValue; optionId: string | null }
+  | { type: 'respond'; requestId: JsonValue; response: JsonValue };
+
+function actionRecord(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('A harness Chat action is required.');
+  }
+  return value as Record<string, unknown>;
+}
+
+function actionString(record: Record<string, unknown>, key: string, max: number): string {
+  const value = record[key];
+  if (typeof value !== 'string' || !value.trim() || value.length > max) {
+    throw new Error(`Harness Chat action field \`${key}\` is invalid.`);
+  }
+  return value;
+}
+
+function parsePromptAction(
+  record: Record<string, unknown>,
+): Extract<HarnessChatAction, { type: 'prompt' }> {
+  const context = record['context'];
+  if (context !== undefined && !Array.isArray(context)) {
+    throw new Error('Harness Chat prompt context is invalid.');
+  }
+  const parsedContext = (context ?? []).map((item) => {
+    const entry = actionRecord(item);
+    return {
+      id: actionString(entry, 'id', 128),
+      label: actionString(entry, 'label', 200),
+      detail: actionString(entry, 'detail', 20_000),
+    };
+  });
+  if (parsedContext.length > 20) throw new Error('Harness Chat prompt context is too large.');
+  return {
+    type: 'prompt',
+    text: actionString(record, 'text', 200_000),
+    ...(parsedContext.length > 0 ? { context: parsedContext } : {}),
+  };
+}
+
+function parseRespondAction(
+  record: Record<string, unknown>,
+): Extract<HarnessChatAction, { type: 'respond' }> {
+  if (!Object.hasOwn(record, 'requestId')) throw new Error('Harness Chat requestId is required.');
+  if (Object.hasOwn(record, 'optionId')) {
+    const optionId = record['optionId'];
+    if (optionId !== null && (typeof optionId !== 'string' || optionId.length > 4_096)) {
+      throw new Error('Harness Chat optionId is invalid.');
+    }
+    return { type: 'respond', requestId: record['requestId'] as JsonValue, optionId };
+  }
+  if (Object.hasOwn(record, 'response')) {
+    return {
+      type: 'respond',
+      requestId: record['requestId'] as JsonValue,
+      response: record['response'] as JsonValue,
+    };
+  }
+  throw new Error('Harness Chat response is required.');
+}
+
+/** Runtime validation for the local HTTP trust boundary. */
+export function parseHarnessChatAction(value: unknown): HarnessChatAction {
+  const record = actionRecord(value);
+  const type = actionString(record, 'type', 32);
+  if (type === 'refresh' || type === 'detach' || type === 'openTerminal' || type === 'interrupt')
+    return { type };
+  if (type === 'create') return { type, harness: actionString(record, 'harness', 128) };
+  if (type === 'prompt') return parsePromptAction(record);
+  if (type === 'observe' || type === 'resume' || type === 'attach' || type === 'branch') {
+    return { type, sessionId: actionString(record, 'sessionId', 4_096) };
+  }
+  if (type === 'restore') {
+    const connection = actionString(record, 'connection', 16);
+    const sessionIdentity = actionString(record, 'sessionIdentity', 256);
+    if (connection !== 'observe' && connection !== 'attach') {
+      throw new Error('Harness Chat restore connection is invalid.');
+    }
+    if (!/^scs_[a-f0-9]{64}$/.test(sessionIdentity)) {
+      throw new Error('Harness Chat session identity is invalid.');
+    }
+    return {
+      type,
+      sessionIdentity,
+      connection,
+    };
+  }
+  if (type === 'respond') return parseRespondAction(record);
+  throw new Error(`Unknown harness Chat action: ${type}`);
+}
+
+/** Reject malformed/stale-version wire payloads before they enter React state. */
+export function parseHarnessChatSnapshot(value: unknown): HarnessChatSnapshot {
+  const record = actionRecord(value);
+  const connection = actionRecord(record['connection']);
+  const turn = actionRecord(record['turn']);
+  const actions = actionRecord(record['availableActions']);
+  const actionNames: Array<keyof HarnessChatAvailableActions> = [
+    'refresh',
+    'observe',
+    'start',
+    'resume',
+    'attach',
+    'branch',
+    'detach',
+    'openTerminal',
+    'send',
+    'interrupt',
+    'respond',
+  ];
+  if (
+    record['schema'] !== 'vgai.harness-chat.v3' ||
+    typeof record['revision'] !== 'number' ||
+    typeof record['workspaceGeneration'] !== 'number' ||
+    !['loading', 'ready', 'working', 'error', 'unavailable'].includes(String(record['status'])) ||
+    !['none', 'observe', 'control'].includes(String(record['mode'])) ||
+    !Array.isArray(record['harnesses']) ||
+    !Array.isArray(record['sessions']) ||
+    !record['sessions'].every((session) => {
+      if (!session || typeof session !== 'object' || Array.isArray(session)) return false;
+      const item = session as Record<string, unknown>;
+      return (
+        typeof item['id'] === 'string' &&
+        typeof item['identity'] === 'string' &&
+        /^scs_[a-f0-9]{64}$/.test(item['identity'])
+      );
+    }) ||
+    !Array.isArray(record['conversation']) ||
+    !['inactive', 'following', 'retrying'].includes(String(connection['follow'])) ||
+    typeof connection['ownsRuntime'] !== 'boolean' ||
+    !['idle', 'running', 'interrupting', 'reconciling'].includes(String(turn['state'])) ||
+    !actionNames.every((name) => typeof actions[name] === 'boolean') ||
+    (record['terminalCommand'] !== null && typeof record['terminalCommand'] !== 'string')
+  ) {
+    throw new Error('Malformed Harness Chat snapshot.');
+  }
+  return value as HarnessChatSnapshot;
+}
+
+export function unavailableHarnessChatSnapshot(error: string): HarnessChatSnapshot {
+  return {
+    schema: 'vgai.harness-chat.v3',
+    revision: 0,
+    workspaceGeneration: 0,
+    workspace: null,
+    status: 'unavailable',
+    mode: 'none',
+    operation: null,
+    harnesses: [],
+    sessions: [],
+    activeHarness: null,
+    activeSessionId: null,
+    connection: { strategy: null, follow: 'inactive', ownsRuntime: false },
+    turn: { state: 'idle', id: null, startedAt: null },
+    conversation: [],
+    requests: [],
+    availableActions: {
+      refresh: false,
+      observe: false,
+      start: false,
+      resume: false,
+      attach: false,
+      branch: false,
+      detach: false,
+      openTerminal: false,
+      send: false,
+      interrupt: false,
+      respond: false,
+    },
+    error: error
+      ? { code: 'unavailable', message: error, operation: 'load', recoverable: true }
+      : null,
+    terminalCommand: null,
+  };
+}
+
+/** Accept only authoritative forward progress for the same workspace. */
+export function shouldAcceptHarnessChatSnapshot(
+  current: HarnessChatSnapshot,
+  next: HarnessChatSnapshot,
+): boolean {
+  if (next.workspaceGeneration !== current.workspaceGeneration) {
+    return next.workspaceGeneration > current.workspaceGeneration;
+  }
+  if (current.workspace !== next.workspace) return false;
+  return next.revision >= current.revision;
+}