React AWS Strands meeting preview

// eslint-disable-next-line @nx/enforce-module-boundaries -- The isolated consumer copies this internal example layout.
import { ExampleFooter, ExampleLayout } from '../../../../shared/react-example';
import { useEffect, useLayoutEffect, useState } from 'react';
import { projectTextTranscript } from '@threadplane/ag-ui';
import { useAgent } from '@threadplane/react';
import {
  ApprovalCard,
  ChatInput,
  TextTranscript,
} from '@threadplane/react/chat';
import {
  createConnectedApplication,
  type strandsConnection,
} from './connection';
import type { Meeting } from './approval-policy';
 
export const MEETING_PRESET =
  'This is a fictional demo meeting. Check availability for Tuesday, then book Q3 roadmap review for Tuesday 10:00 after my approval.';
function MeetingDetails({
  meeting,
}: {
  readonly meeting: Readonly<Partial<Meeting>>;
}) {
  return (
    <dl className="meeting-details">
      <dt>Topic</dt>
      <dd>{meeting.topic ?? 'Not observed'}</dd>
      <dt>Slot</dt>
      <dd>{meeting.slot ?? 'Not observed'}</dd>
    </dl>
  );
}
 
export function StrandsDemo({
  connection,
  onReady,
}: {
  readonly connection: ReturnType<typeof strandsConnection>;
  readonly onReady: () => void;
}) {
  // Applications are lazy: construction allocates neither a thread nor a Session.
  // The stable owner survives StrictMode effect rehearsal; disposed applications do not.
  type Application = ReturnType<typeof createConnectedApplication>;
  const [owner] = useState<{
    current?: Application;
    connection: typeof connection;
  }>(() => ({ connection }));
  const [application, setApplication] = useState<Application | null>(null);
  useLayoutEffect(() => {
    if (!owner.current || owner.current.getSnapshot().status === 'disposed')
      owner.current = createConnectedApplication(owner.connection);
    const acquired = owner.current;
    setApplication(acquired);
    return () => {
      void acquired.dispose().catch(() => undefined);
    };
  }, [owner]);
  return application ? (
    <StrandsPresentation
      application={application}
      label={owner.connection.label}
      onReady={onReady}
    />
  ) : (
    <p role="status">Starting meeting preview…</p>
  );
}
 
function StrandsPresentation({
  application,
  label,
  onReady,
}: {
  readonly application: ReturnType<typeof createConnectedApplication>;
  readonly label: ReturnType<typeof strandsConnection>['label'];
  readonly onReady: () => void;
}) {
  const [draft, setDraft] = useState('');
  const snapshot = useAgent(application);
  const generation = snapshot.generation;
  const approval = snapshot.approval;
  useEffect(() => {
    if (application.getSnapshot().status !== 'disposed') onReady();
  }, [application, onReady]);
  useEffect(() => {
    setDraft('');
  }, [generation]);
  const status = {
    ready: 'Ready.',
    running: 'Checking the meeting…',
    pending: 'Awaiting your decision.',
    approved: 'Fictional meeting booked.',
    declined: 'Meeting declined.',
    unconfirmed: 'Meeting unconfirmed. Start a new conversation.',
    'cleanup-failed': 'Conversation could not close. Reload the preview.',
    replacing: 'Starting new conversation…',
    disposed: 'Preview closed.',
  }[snapshot.status];
  return (
    <ExampleLayout className="strands-demo">
      <header>
        <div>
          <h1>AWS Strands meetings</h1>
        </div>
        <button
          type="button"
          disabled={
            snapshot.status === 'replacing' ||
            snapshot.status === 'disposed' ||
            snapshot.status === 'cleanup-failed'
          }
          onClick={() => {
            void application.newConversation();
          }}
        >
          New conversation
        </button>
      </header>
      <p>
        Review a fictional meeting, then approve or decline it. No real meeting
        is booked.
      </p>
      <p className="preview-note">Source-build preview · {label}</p>
      <button
        type="button"
        className="preset"
        disabled={!snapshot.canSend}
        onClick={() => setDraft(MEETING_PRESET)}
      >
        Q3 roadmap review
      </button>
      <TextTranscript
        messages={projectTextTranscript(snapshot.rows)}
        label="Conversation"
      />
      <section
        aria-label="Last observed schedule"
        className="observed-schedule"
      >
        <h2>Last observed schedule</h2>
        <p>
          The last snapshot can still show pending after the meeting tool
          finishes. See the separate backend result for the confirmed decision.
        </p>
        {snapshot.schedule?.availability ? (
          <p>
            Availability · {snapshot.schedule.availability.day}:{' '}
            {snapshot.schedule.availability.slots.join(', ') ||
              'No slots observed'}
          </p>
        ) : (
          <p>No availability observed yet.</p>
        )}
        {snapshot.schedule?.booking ? (
          <>
            <MeetingDetails meeting={snapshot.schedule.booking} />
            <p>
              Observed booking status:{' '}
              {snapshot.schedule.booking.status ?? 'Not observed'}
            </p>
          </>
        ) : (
          <p>No booking observed yet.</p>
        )}
      </section>
      {approval && (
        <ApprovalCard
          title="Meeting approval"
          disabled={snapshot.busy || !snapshot.canRespond}
          actions={[
            {
              id: 'approve',
              label: 'Approve',
              onSelect: () => {
                void application.decide(approval, 'approve', generation);
              },
            },
            {
              id: 'decline',
              label: 'Decline',
              onSelect: () => {
                void application.decide(approval, 'decline', generation);
              },
            },
          ]}
        >
          <MeetingDetails meeting={approval.meeting} />
          <p>This decision applies only to the fictional meeting shown here.</p>
        </ApprovalCard>
      )}
      {snapshot.result !== null && (
        <section
          aria-label="Observed backend result"
          className="backend-result"
        >
          <h2>Observed backend result</h2>
          <p>The meeting tool returned this exact text:</p>
          <pre>{snapshot.result}</pre>
        </section>
      )}
      <ExampleFooter>
        {snapshot.error && <p role="alert">{snapshot.error}</p>}
        <section aria-label="Compose message">
          <ChatInput
            label="Message"
            placeholder="Ask about a fictional meeting…"
            value={draft}
            onValueChange={setDraft}
            disabled={!snapshot.canSend}
            busy={snapshot.busy}
            onStop={
              snapshot.busy &&
              snapshot.status !== 'replacing' &&
              snapshot.status !== 'cleanup-failed'
                ? () => {
                    void application.stop();
                  }
                : undefined
            }
            onSubmit={(text) => {
              void application.submit(text, generation);
              const current = application.getSnapshot();
              return (
                current.generation === generation &&
                current.busy &&
                current.status === 'running'
              );
            }}
          />
        </section>
        <p role="status">{status}</p>
      </ExampleFooter>
    </ExampleLayout>
  );
}

import type { Session } from '@threadplane/ag-ui';
export type NativeSnapshot = ReturnType<Session['getSnapshot']>;
type Transcript = NativeSnapshot['transcript'];
export interface Meeting {
  readonly topic: string;
  readonly slot: string;
}
export interface OwnedTurn {
  readonly threadId: string;
  readonly runId: string;
  readonly human: Transcript[number];
  readonly prefix: Transcript;
}
export interface MeetingApproval {
  readonly threadId: string;
  readonly sourceRunId: string;
  /** Keep the original opaque branded occurrence, never decode an interrupt identifier. */
  readonly pause: Parameters<Session['resume']>[0];
  readonly interruptId: string;
  readonly toolCallId: string;
  readonly meeting: Meeting;
  readonly transcript: Transcript;
  readonly observation: NativeSnapshot;
}
export function record(value: unknown): Record<string, unknown> | undefined {
  return value !== null && typeof value === 'object' && !Array.isArray(value)
    ? (value as Record<string, unknown>)
    : undefined;
}
/** Reject accessors/cycles and bound both traversal and retained text. Recheck after every proxy trap. */
export function ownData(value: unknown, valid = () => true): unknown {
  let nodes = 100000,
    characters = 1000000;
  const seen = new Set<object>();
  function copy(input: unknown, depth: number): unknown {
    if (!valid() || --nodes < 0 || depth > 32)
      throw Error('Revoked or oversized observation');
    if (typeof input === 'string') {
      characters -= input.length;
      if (characters < 0) throw Error('Oversized text');
      return input;
    }
    if (input === null || input === undefined || typeof input === 'boolean')
      return input;
    if (typeof input === 'number' && Number.isFinite(input)) return input;
    if (typeof input !== 'object' || seen.has(input))
      throw Error('Not plain data');
    const array = Array.isArray(input),
      prototype = Object.getPrototypeOf(input);
    if (
      !valid() ||
      (!array && prototype !== Object.prototype && prototype !== null)
    )
      throw Error('Not plain data');
    let arrayLength: number | undefined;
    if (array) {
      const descriptor = Object.getOwnPropertyDescriptor(input, 'length');
      if (
        !valid() ||
        !descriptor ||
        !('value' in descriptor) ||
        !Number.isSafeInteger(descriptor.value) ||
        descriptor.value < 0 ||
        descriptor.value > nodes
      )
        throw Error('Revoked or oversized array');
      arrayLength = descriptor.value as number;
    }
    seen.add(input);
    const output: Record<string, unknown> | unknown[] = array ? [] : {};
    const keys = Reflect.ownKeys(input);
    if (!valid() || keys.length > nodes)
      throw Error('Revoked or oversized keys');
    if (arrayLength !== undefined) {
      // Reject sparse arrays instead of retaining uncharged logical slots.
      // Check bounds too: a proxy may under-report its writable length.
      let slots = 0;
      for (const key of keys) {
        if (typeof key !== 'string') throw Error('Not plain data');
        const index = Number(key);
        if (
          Number.isInteger(index) &&
          index >= 0 &&
          index < 4294967295 &&
          String(index) === key
        ) {
          if (index >= arrayLength) throw Error('Array index exceeds length');
          slots++;
        }
      }
      if (slots !== arrayLength) throw Error('Sparse array');
    }
    for (const key of keys) {
      if (!valid() || typeof key !== 'string') throw Error('Not plain data');
      characters -= key.length;
      if (characters < 0) throw Error('Oversized keys');
      if (array && key === 'length') continue;
      const descriptor = Object.getOwnPropertyDescriptor(input, key);
      if (!valid() || !descriptor || !('value' in descriptor))
        throw Error('Accessor data');
      Object.defineProperty(output, key, {
        value: copy(descriptor.value, depth + 1),
        enumerable: true,
      });
    }
    seen.delete(input);
    if (!valid()) throw Error('Revoked');
    return Object.freeze(output);
  }
  return copy(value, 0);
}
export function ownSnapshot(
  value: NativeSnapshot,
  valid = () => true
): NativeSnapshot | undefined {
  try {
    return ownData(value, valid) as NativeSnapshot;
  } catch {
    return undefined;
  }
}
export function same(left: unknown, right: unknown): boolean {
  function canonical(value: unknown): unknown {
    if (Array.isArray(value)) return value.map(canonical);
    const r = record(value);
    return r
      ? Object.fromEntries(
          Object.keys(r)
            .sort()
            .map((k) => [k, canonical(r[k])])
        )
      : value;
  }
  return JSON.stringify(canonical(left)) === JSON.stringify(canonical(right));
}
function rootRows(s: NativeSnapshot): Transcript | undefined {
  if (!Array.isArray(s.transcript) || !Array.isArray(s.subagents)) return;
  const ids = new Set<string>(),
    calls = new Set<string>();
  for (const message of s.transcript) {
    const m = record(message);
    if (!m || typeof m['id'] !== 'string' || !m['id'] || ids.has(m['id']))
      return;
    ids.add(m['id']);
    if (
      m['subagentRunId'] !== undefined &&
      (typeof m['subagentRunId'] !== 'string' || !m['subagentRunId'])
    )
      return;
    const roles =
      typeof m['subagentRunId'] === 'string'
        ? [
            'user',
            'assistant',
            'tool',
            'developer',
            'system',
            'activity',
            'reasoning',
          ]
        : ['user', 'assistant', 'tool'];
    if (!roles.includes(m['role'] as string)) return;
    if (m['toolCalls'] !== undefined) {
      if (m['role'] !== 'assistant' || !Array.isArray(m['toolCalls'])) return;
      for (const call of m['toolCalls']) {
        const c = record(call),
          f = record(c?.['function']);
        if (
          !c ||
          typeof c['id'] !== 'string' ||
          !c['id'] ||
          calls.has(c['id']) ||
          c['type'] !== 'function' ||
          !f ||
          typeof f['name'] !== 'string' ||
          typeof f['arguments'] !== 'string'
        )
          return;
        calls.add(c['id']);
      }
    }
  }
  const rows = s.transcript.filter((m) => m.subagentRunId === undefined);
  const rootCalls = new Set<string>(),
    results = new Set<string>();
  for (const m of rows) {
    if (m.role === 'assistant')
      for (const call of m.toolCalls ?? []) rootCalls.add(call.id);
    else if (m.role === 'tool') {
      // A result can only belong to a root declaration already observed before it.
      if (!rootCalls.has(m.toolCallId) || results.has(m.toolCallId)) return;
      results.add(m.toolCallId);
    }
  }
  return Object.freeze(rows);
}
function semantic(message: Transcript[number]) {
  if (message.role !== 'assistant') return message;
  return {
    ...message,
    content: message.content ?? '',
    toolCalls: message.toolCalls?.map((c) => ({
      ...c,
      function: { ...c.function, arguments: parse(c.function.arguments) },
    })),
  };
}
function history(past: Transcript, current: Transcript) {
  let next = 0;
  for (const message of current) {
    if (next === past.length) break;
    const retained = past[next];
    if (message.id !== retained.id) continue;
    if (!same(semantic(retained), semantic(message))) return false;
    next++;
  }
  // New observations may interleave retained rows, but never reorder them.
  return next === past.length;
}
export function captureTurn(
  snapshot: NativeSnapshot,
  threadId: string,
  previous: string | undefined,
  prefix: Transcript,
  valid = () => true
): OwnedTurn | undefined {
  const s = ownSnapshot(snapshot, valid),
    rows = s && rootRows(s);
  if (
    !s ||
    !rows ||
    s.status !== 'running' ||
    s.decision ||
    typeof threadId !== 'string' ||
    !threadId ||
    typeof s.run?.id !== 'string' ||
    !s.run.id ||
    s.run.id === previous ||
    s.run.outcome !== undefined ||
    rows.length !== prefix.length + 1 ||
    !history(prefix, rows)
  )
    return;
  const human = rows.at(-1);
  if (
    !human ||
    human.role !== 'user' ||
    typeof human.content !== 'string' ||
    !human.content.trim() ||
    !valid()
  )
    return;
  return Object.freeze({
    threadId,
    runId: s.run.id,
    human,
    prefix: Object.freeze([...prefix]),
  });
}
function parse(value: string): unknown {
  try {
    return JSON.parse(value);
  } catch {
    return undefined;
  }
}
export function boundedText(value: unknown, maximum = 500): value is string {
  return typeof value === 'string' && !!value.trim() && value.length <= maximum;
}
export function meetingValue(value: unknown): Meeting | undefined {
  const m = record(value);
  if (
    !m ||
    Object.keys(m).length !== 2 ||
    !boundedText(m['topic']) ||
    !boundedText(m['slot'])
  )
    return;
  return Object.freeze({ topic: m['topic'], slot: m['slot'] });
}
function lookupArgs(value: unknown) {
  const a = record(value);
  return !!a && Object.keys(a).length === 1 && boundedText(a['day']);
}
function submitCalls(rows: Transcript) {
  return rows.flatMap((m) => (m.role === 'assistant' ? m.toolCalls ?? [] : []));
}
function nativeInterrupt(value: unknown, now: number) {
  const i = record(value);
  if (
    !i ||
    !boundedText(i['id'], 2000) ||
    i['reason'] !== 'book_meeting' ||
    i['toolCallId'] !== undefined ||
    i['responseSchema'] !== undefined ||
    i['subagentRunId'] !== undefined
  )
    return;
  const expiry = i['expiresAt'];
  if (
    expiry !== undefined &&
    (typeof expiry !== 'string' ||
      !Number.isFinite(Date.parse(expiry)) ||
      Date.parse(expiry) <= now)
  )
    return;
  return i;
}
export function captureApproval(
  snapshot: NativeSnapshot,
  turn: OwnedTurn,
  valid = () => true
): MeetingApproval | undefined {
  const s = ownSnapshot(snapshot, valid),
    rows = s && rootRows(s);
  if (!s || !rows || !turn) return;
  const d = s.decision,
    r = s.run,
    t = r?.terminal;
  if (
    s.status !== 'idle' ||
    r?.id !== turn.runId ||
    r.outcome !== 'paused' ||
    d?.kind !== 'native' ||
    !boundedText(d.id, 4000) ||
    d.attempt ||
    d.sourceRunId !== turn.runId ||
    !Array.isArray(d.interrupts) ||
    d.interrupts.length !== 1 ||
    t?.type !== 'RUN_FINISHED' ||
    record(t)?.['subagentRunId'] !== undefined ||
    t.threadId !== turn.threadId ||
    t.runId !== turn.runId ||
    t.outcome?.type !== 'interrupt' ||
    !Array.isArray(t.outcome.interrupts) ||
    t.outcome.interrupts.length !== 1 ||
    !history([...turn.prefix, turn.human], rows)
  )
    return;
  const i = nativeInterrupt(d.interrupts[0], Date.now()),
    end = nativeInterrupt(t.outcome.interrupts[0], Date.now());
  if (!i || !end || !same(i, end)) return;
  const metadata = record(i['metadata']),
    meeting = meetingValue(metadata?.['reason']);
  if (!meeting) return;
  const previousCalls = submitCalls(turn.prefix),
    calls = submitCalls(rows).filter(
      (c) => !previousCalls.some((p) => p.id === c.id)
    ),
    books = calls.filter((c) => c.function.name === 'book_meeting'),
    lookups = calls.filter((c) => c.function.name === 'check_availability');
  const humanIndex = rows.findIndex((m) => m.id === turn.human.id);
  if (
    humanIndex < 0 ||
    submitCalls(rows.slice(0, humanIndex + 1)).some((c) =>
      calls.some((current) => current.id === c.id)
    )
  )
    return;
  if (
    books.length !== 1 ||
    lookups.length > 1 ||
    calls.length !== books.length + lookups.length ||
    !same(parse(books[0].function.arguments), meeting) ||
    lookups.some((c) => !lookupArgs(parse(c.function.arguments))) ||
    rows.some(
      (m) =>
        m.role === 'tool' && m.error && calls.some((c) => c.id === m.toolCallId)
    ) ||
    rows.some((m) => m.role === 'tool' && m.toolCallId === books[0].id) ||
    !same(
      rows.filter((m) => m.role === 'user'),
      [...turn.prefix.filter((m) => m.role === 'user'), turn.human]
    ) ||
    !valid()
  )
    return;
  try {
    const original = Object.getOwnPropertyDescriptor(
      snapshot,
      'decision'
    )?.value;
    if (!valid()) return;
    const pause =
      original &&
      (Object.getOwnPropertyDescriptor(original, 'id')?.value as Parameters<
        Session['resume']
      >[0]);
    if (!valid() || pause !== d.id) return;
    return Object.freeze({
      threadId: turn.threadId,
      sourceRunId: turn.runId,
      pause,
      interruptId: i['id'] as string,
      toolCallId: books[0].id,
      meeting,
      transcript: rows,
      observation: s,
    });
  } catch {
    return;
  }
}
export function sameApproval(a: MeetingApproval, b: MeetingApproval): boolean {
  return (
    a.pause === b.pause &&
    a.threadId === b.threadId &&
    a.sourceRunId === b.sourceRunId &&
    a.interruptId === b.interruptId &&
    a.toolCallId === b.toolCallId &&
    same(a.meeting, b.meeting) &&
    same(a.transcript.map(semantic), b.transcript.map(semantic)) &&
    same(a.observation.decision, b.observation.decision) &&
    same(a.observation.run, b.observation.run)
  );
}
export function confirmResume(
  snapshot: NativeSnapshot,
  approval: MeetingApproval,
  runId: string,
  approved: boolean,
  valid = () => true
): { readonly transcript: Transcript; readonly result: string } | undefined {
  const s = ownSnapshot(snapshot, valid),
    rows = s && rootRows(s);
  if (
    !s ||
    !rows ||
    !approval ||
    !runId ||
    runId === approval.sourceRunId ||
    s.status !== 'idle' ||
    s.decision ||
    s.run?.id !== runId ||
    s.run.outcome !== 'success'
  )
    return;
  const t = s.run.terminal;
  if (
    t?.type !== 'RUN_FINISHED' ||
    record(t)?.['subagentRunId'] !== undefined ||
    t.threadId !== approval.threadId ||
    t.runId !== runId ||
    (t.outcome !== undefined && t.outcome.type !== 'success') ||
    (t.outcome?.type === 'success' && !!t.outcome.pendingToolCallIds?.length) ||
    !history(approval.transcript, rows)
  )
    return;
  const ownedCalls = submitCalls(approval.transcript),
    calls = submitCalls(rows),
    results = rows.filter(
      (m) => m.role === 'tool' && m.toolCallId === approval.toolCallId
    ),
    pending = ownedCalls.filter(
      (c) =>
        c.id !== approval.toolCallId &&
        !approval.transcript.some(
          (m) => m.role === 'tool' && m.toolCallId === c.id
        )
    );
  if (pending.length > 1) return;
  for (const call of pending) {
    const lookup = rows.filter(
      (m) => m.role === 'tool' && m.toolCallId === call.id
    );
    if (
      call.function.name !== 'check_availability' ||
      !lookupArgs(parse(call.function.arguments)) ||
      lookup.length !== 1 ||
      lookup[0].role !== 'tool' ||
      lookup[0].error ||
      !boundedText(lookup[0].content, 100000)
    )
      return;
  }
  const expected = approved
    ? `Meeting booked for ${approval.meeting.slot}: ${approval.meeting.topic}`
    : `The human declined. Meeting NOT booked: ${approval.meeting.topic}`;
  if (
    results.length !== 1 ||
    results[0].role !== 'tool' ||
    results[0].error ||
    typeof results[0].content !== 'string' ||
    parse(results[0].content) !== expected ||
    rows.some(
      (m) =>
        m.role === 'user' && !approval.transcript.some((p) => p.id === m.id)
    ) ||
    rows.some(
      (m) =>
        m.role === 'tool' &&
        m.toolCallId !== approval.toolCallId &&
        !approval.transcript.some((p) => p.id === m.id) &&
        !pending.some((c) => c.id === m.toolCallId)
    ) ||
    calls.some((c) => !ownedCalls.some((p) => p.id === c.id)) ||
    !valid()
  )
    return;
  return Object.freeze({ transcript: rows, result: expected });
}

import type { Session } from '@threadplane/ag-ui';
import {
  captureApproval,
  captureTurn,
  confirmResume,
  ownSnapshot,
  same,
  sameApproval,
  type MeetingApproval,
  type NativeSnapshot,
  type OwnedTurn,
} from './approval-policy';
import { projectSchedule, type ScheduleSnapshot } from './schedule-projection';
export interface StrandsSnapshot {
  readonly generation: number;
  readonly threadId: string | null;
  readonly busy: boolean;
  readonly canSend: boolean;
  readonly canRespond: boolean;
  readonly rows: NativeSnapshot['transcript'];
  readonly schedule: ScheduleSnapshot | undefined;
  readonly approval: MeetingApproval | undefined;
  readonly result: string | null;
  readonly status:
    | 'ready'
    | 'running'
    | 'pending'
    | 'approved'
    | 'declined'
    | 'unconfirmed'
    | 'cleanup-failed'
    | 'replacing'
    | 'disposed';
  readonly error: string | null;
}
type Methods = { [K in keyof Session]: Session[K] };
type Owner = {
  readonly candidate: Session;
  readonly threadId: string;
  readonly methods: Methods;
  readonly seenRuns: Set<string>;
  closed: boolean;
  release?: () => void;
  turn?: OwnedTurn;
  approval?: MeetingApproval;
  transcript: NativeSnapshot['transcript'];
  previous?: string;
  intent?: 'submit' | 'resume';
  resumeRunId?: string;
  approved?: boolean;
  unsafe: boolean;
};
/** Owns admission, observation and lifetime. Native Session alone executes the protocol. */
export function createStrandsApplication(options: {
  readonly sessionFactory: (threadId: string) => Session | Promise<Session>;
  readonly threadIdFactory?: () => string;
}) {
  const listeners = new Set<() => void>(),
    cleanups = new Set<Promise<void>>();
  let primary: Owner | undefined,
    operation: AbortController | undefined,
    disposed = false,
    cleanupFailed = false,
    revoking = false,
    disposal: Promise<void> | undefined;
  let snapshot: StrandsSnapshot = Object.freeze({
    generation: 0,
    threadId: null,
    busy: false,
    canSend: true,
    canRespond: false,
    rows: Object.freeze([]),
    schedule: undefined,
    approval: undefined,
    result: null,
    status: 'ready',
    error: null,
  });
  const cleanupFailure: Partial<StrandsSnapshot> = Object.freeze({
    canSend: false,
    canRespond: false,
    approval: undefined,
    result: null,
    status: 'cleanup-failed',
    error:
      'The conversation could not close safely. Reload the preview to continue.',
  });
  function failCleanup() {
    // Failure is permanent even if a later best-effort teardown succeeds.
    cleanupFailed = true;
    publish(cleanupFailure);
  }
  function publish(update: Partial<StrandsSnapshot>) {
    if (disposed) return;
    snapshot = Object.freeze({
      ...snapshot,
      ...update,
      ...(cleanupFailed ? cleanupFailure : {}),
    });
    for (const notify of [...listeners]) {
      try {
        notify();
      } catch {
        /* An observer cannot prevent revocation. */
      }
    }
  }
  function track(promise: Promise<unknown>) {
    const done = promise.then(
      () => undefined,
      () => undefined
    );
    cleanups.add(done);
    void done.then(() => cleanups.delete(done));
    return done;
  }
  async function drain() {
    while (cleanups.size) await Promise.all([...cleanups]);
  }
  function current(p: Owner) {
    return !disposed && !cleanupFailed && primary === p && !p.closed;
  }
  function cleanupCandidate(
    candidate: unknown,
    methods?: Partial<Methods>,
    release?: () => void
  ) {
    // Authority and the rendered controls have already been revoked by the caller.
    const done = track(
      Promise.resolve()
        .then(async () => {
          let dispose = methods?.dispose;
          try {
            dispose ??= (candidate as Session)?.dispose;
          } catch {
            failCleanup();
          }
          if (typeof dispose === 'function') {
            try {
              await dispose.call(candidate);
              return;
            } catch {
              failCleanup();
            }
          }
          let stop = methods?.stop;
          try {
            stop ??= (candidate as Session)?.stop;
          } catch {
            failCleanup();
          }
          if (typeof stop === 'function') {
            try {
              await stop.call(candidate);
            } catch {
              failCleanup();
            }
          } else failCleanup();
        })
        .catch(() => {
          // Retain unexpected cleanup rejection before the settlement-only barrier.
          failCleanup();
        })
    );
    try {
      release?.();
    } catch {
      failCleanup();
    }
    return done;
  }
  function close(p: Owner) {
    p.closed = true;
    const release = p.release;
    p.release = undefined;
    return cleanupCandidate(p.candidate, p.methods, release);
  }
  function fail(p?: Owner, bootstrap = false) {
    if (p && !current(p)) return;
    let prepared: (() => void) | undefined;
    if (p) {
      p.unsafe = true;
      p.approval = undefined;
      if (bootstrap) {
        primary = undefined;
        p.closed = true;
        // Observers may dispose after detachment but before release. Keep every
        // disposal behind preparation until candidate cleanup is registered.
        track(
          new Promise<void>((resolve) => {
            prepared = resolve;
          })
        );
      }
    }
    publish({
      canSend: false,
      canRespond: false,
      approval: undefined,
      result: null,
      status: 'unconfirmed',
      error:
        'The meeting outcome could not be confirmed. Start a new conversation.',
    });
    if (p && bootstrap) {
      try {
        void close(p);
      } finally {
        prepared?.();
      }
    }
  }
  function read(p: Owner, valid: () => boolean) {
    if (!valid()) return;
    const native = p.methods.getSnapshot.call(p.candidate);
    if (!valid()) return;
    return ownSnapshot(native, valid);
  }
  function capture(p: Owner, valid: () => boolean) {
    const native = read(p, valid);
    if (
      !native ||
      !valid() ||
      !Array.isArray(native.transcript) ||
      !Array.isArray(native.subagents)
    )
      return;
    if (native.status === 'error') p.unsafe = true;
    if (p.intent === 'submit' && !p.turn) {
      const turn = captureTurn(
        native,
        p.threadId,
        p.previous,
        p.transcript,
        valid
      );
      if (turn) {
        if (p.seenRuns.has(turn.runId)) p.unsafe = true;
        else {
          p.turn = turn;
          p.seenRuns.add(turn.runId);
        }
      }
    }
    if (
      p.intent === 'resume' &&
      !p.resumeRunId &&
      p.approval &&
      native.status === 'running' &&
      typeof native.run?.id === 'string' &&
      native.run.id !== p.approval.sourceRunId &&
      native.decision?.kind === 'native' &&
      native.decision.id === p.approval.pause &&
      native.decision.sourceRunId === p.approval.sourceRunId &&
      native.decision.attempt?.runId === native.run?.id
    ) {
      if (p.seenRuns.has(native.run.id)) p.unsafe = true;
      else {
        p.resumeRunId = native.run.id;
        p.seenRuns.add(native.run.id);
      }
    }
    const approval =
      p.intent === 'submit' && p.turn && !p.unsafe
        ? captureApproval(native, p.turn, valid)
        : undefined;
    const confirmed =
      p.intent === 'resume' &&
      p.approval &&
      p.resumeRunId &&
      typeof p.approved === 'boolean' &&
      !p.unsafe
        ? confirmResume(native, p.approval, p.resumeRunId, p.approved, valid)
        : undefined;
    return valid()
      ? {
          native,
          rows: Object.freeze(
            native.transcript.filter((m) => m.subagentRunId === undefined)
          ),
          schedule: projectSchedule(native.state),
          approval,
          confirmed,
        }
      : undefined;
  }
  function observe(p: Owner) {
    const valid = () => current(p) && !operation?.signal.aborted;
    try {
      const result = capture(p, valid);
      if (!valid()) return;
      if (!result) {
        fail(p);
        return;
      }
      if (
        snapshot.canRespond &&
        (!result.approval ||
          !p.approval ||
          !sameApproval(result.approval, p.approval))
      ) {
        fail(p);
        return;
      }
      publish({ rows: result.rows, schedule: result.schedule });
    } catch {
      if (valid()) fail(p);
    }
  }
  function claim(status: 'running' | 'replacing') {
    const controller = new AbortController();
    operation = controller;
    const valid = () =>
      !disposed &&
      !cleanupFailed &&
      operation === controller &&
      !controller.signal.aborted;
    publish({
      busy: true,
      canSend: false,
      canRespond: false,
      approval: undefined,
      result: null,
      status,
      error: null,
    });
    return { controller, valid };
  }
  function finish(controller: AbortController) {
    if (!disposed && operation === controller) {
      operation = undefined;
      publish({ busy: false });
    }
  }
  async function install(valid: () => boolean): Promise<Owner | undefined> {
    if (!valid()) return;
    const threadIdFactory =
      options.threadIdFactory ?? (() => crypto.randomUUID());
    if (!valid()) return;
    const threadId = threadIdFactory();
    if (!valid()) return;
    if (typeof threadId !== 'string' || !threadId || threadId.length > 500)
      throw TypeError('A thread identifier is required');
    const factory = options.sessionFactory;
    if (!valid()) return;
    // Track late bootstrap so New/dispose cannot finish ahead of candidate cleanup.
    let resolveCandidate!: (candidate: Session | Promise<Session>) => void,
      rejectCandidate!: (error: unknown) => void;
    const candidatePromise = new Promise<Session>((resolve, reject) => {
      resolveCandidate = resolve;
      rejectCandidate = reject;
    });
    track(
      candidatePromise.then((candidate) => {
        if (!valid()) return cleanupCandidate(candidate);
        return undefined;
      })
    );
    try {
      resolveCandidate(factory(threadId));
    } catch (error) {
      rejectCandidate(error);
    }
    const candidate = await candidatePromise;
    if (!valid()) return;
    const methods: Partial<Methods> = {};
    let release: (() => void) | undefined,
      p: Owner | undefined,
      cleanupAccessFailed = false;
    try {
      if (
        candidate === null ||
        (typeof candidate !== 'object' && typeof candidate !== 'function')
      )
        throw TypeError('A native Session is required');
      for (const name of [
        'getSnapshot',
        'subscribe',
        'submit',
        'resume',
        'stop',
        'dispose',
      ] as const) {
        let method: unknown;
        try {
          method = candidate[name];
        } catch (error) {
          cleanupAccessFailed = name === 'stop' || name === 'dispose';
          throw error;
        }
        if (!valid()) {
          void cleanupCandidate(candidate, methods);
          return;
        }
        if (typeof method !== 'function')
          throw TypeError('A complete native Session is required');
        Object.defineProperty(methods, name, {
          value: method,
          enumerable: true,
        });
      }
      p = {
        candidate,
        threadId,
        methods: methods as Methods,
        seenRuns: new Set(),
        closed: false,
        transcript: Object.freeze([]),
        unsafe: false,
      };
      const selected = p;
      const result = p.methods.subscribe.call(candidate, () => {
        if (primary === selected) observe(selected);
      });
      if (typeof result !== 'function')
        throw TypeError('A callable release is required');
      release = result;
      if (!valid()) {
        p.closed = true;
        void cleanupCandidate(candidate, methods, release);
        return;
      }
      // Only a complete callable candidate with its release in hand can become authoritative.
      p.release = release;
      primary = p;
      return p;
    } catch (error) {
      if (p) p.closed = true;
      void cleanupCandidate(candidate, methods, release);
      // Register owned cleanup before notifying reentrant observers. A later
      // successful disposal cannot erase an observed cleanup accessor failure.
      if (cleanupAccessFailed) failCleanup();
      throw error;
    }
  }
  async function submit(message: string, generation = snapshot.generation) {
    if (
      disposed ||
      cleanupFailed ||
      revoking ||
      snapshot.busy ||
      !snapshot.canSend ||
      generation !== snapshot.generation ||
      typeof message !== 'string' ||
      !message.trim() ||
      message.length > 16000
    )
      return;
    const { controller, valid } = claim('running');
    let p = primary;
    let bootstrapping = true;
    try {
      if (!valid()) return;
      await drain();
      if (!valid()) return;
      p ??= await install(valid);
      if (!p || !valid() || !current(p)) return;
      const owner = p,
        ownedValid = () => valid() && current(owner);
      publish({ threadId: p.threadId });
      if (!ownedValid()) return;
      const initial = read(p, ownedValid);
      if (!ownedValid()) return;
      if (
        !initial ||
        initial.status !== 'idle' ||
        initial.decision ||
        p.unsafe ||
        !same(
          initial.transcript.filter((m) => m.subagentRunId === undefined),
          p.transcript
        )
      ) {
        fail(p, true);
        return;
      }
      bootstrapping = false;
      p.previous = initial.run?.id;
      p.turn = undefined;
      p.intent = 'submit';
      p.approval = undefined;
      const pending = p.methods.submit.call(p.candidate, message, {
        signal: controller.signal,
      });
      void pending.catch(() => undefined);
      if (!ownedValid()) return;
      observe(p);
      const outcome = await pending;
      if (!ownedValid()) return;
      const result = capture(p, ownedValid);
      if (!ownedValid()) return;
      if (outcome !== 'paused' || !result?.approval || p.unsafe) {
        fail(p);
        return;
      }
      p.approval = result.approval;
      publish({
        rows: result.rows,
        schedule: result.schedule,
        approval: p.approval,
        canRespond: true,
        canSend: false,
        status: 'pending',
      });
    } catch {
      if (valid()) fail(p, bootstrapping);
    } finally {
      finish(controller);
    }
  }
  async function decide(
    approval: MeetingApproval,
    action: 'approve' | 'decline',
    generation = snapshot.generation
  ) {
    const p = primary;
    if (
      disposed ||
      cleanupFailed ||
      revoking ||
      snapshot.busy ||
      !snapshot.canRespond ||
      generation !== snapshot.generation ||
      !p ||
      p.closed ||
      p.unsafe ||
      p.approval !== approval ||
      snapshot.approval !== approval ||
      !p.turn ||
      (action !== 'approve' && action !== 'decline')
    )
      return;
    // Claim synchronously before getters, native execution or observer notification.
    const { controller, valid } = claim('running'),
      ownedValid = () => valid() && current(p);
    try {
      if (!ownedValid()) return;
      const native = read(p, ownedValid),
        fresh = native && captureApproval(native, p.turn, ownedValid);
      if (!ownedValid()) return;
      if (!fresh || !sameApproval(fresh, approval)) {
        fail(p);
        return;
      }
      p.intent = 'resume';
      p.resumeRunId = undefined;
      p.approved = action === 'approve';
      const pending = p.methods.resume.call(
        p.candidate,
        approval.pause,
        [
          {
            interruptId: approval.interruptId,
            status: 'resolved',
            payload: { approved: p.approved },
          },
        ],
        { signal: controller.signal }
      );
      void pending.catch(() => undefined);
      if (!ownedValid()) return;
      observe(p);
      const outcome = await pending;
      if (!ownedValid()) return;
      const result = capture(p, ownedValid);
      if (!ownedValid()) return;
      if (outcome !== 'success' || !result?.confirmed || p.unsafe) {
        fail(p);
        return;
      }
      p.transcript = result.confirmed.transcript;
      p.approval = undefined;
      publish({
        rows: result.rows,
        schedule: result.schedule,
        approval: undefined,
        canRespond: false,
        canSend: true,
        status: p.approved ? 'approved' : 'declined',
        result: result.confirmed.result,
        error: null,
      });
    } catch {
      if (ownedValid()) fail(p);
    } finally {
      finish(controller);
    }
  }
  async function revoke(replacing: boolean) {
    if (disposed || cleanupFailed || revoking) return;
    revoking = true;
    const previous = operation,
      p = primary;
    operation = undefined;
    primary = undefined;
    if (p) {
      p.closed = true;
      p.approval = undefined;
    }
    // A view notification can dispose while the old owner is already detached.
    // Keep that disposal behind preparation until the old cleanup is registered.
    let prepared!: () => void;
    track(
      new Promise<void>((resolve) => {
        prepared = resolve;
      })
    );
    // Clear controls and result before abort/release/cleanup can inspect or reenter.
    const { controller, valid } = claim(replacing ? 'replacing' : 'running');
    publish({
      generation: snapshot.generation + 1,
      threadId: replacing ? null : snapshot.threadId,
      rows: replacing ? Object.freeze([]) : snapshot.rows,
      schedule: replacing ? undefined : snapshot.schedule,
      approval: undefined,
      result: null,
      canRespond: false,
      canSend: false,
      status: replacing ? 'replacing' : 'unconfirmed',
      error: replacing
        ? null
        : 'The operation stopped. Start a new conversation.',
    });
    try {
      previous?.abort();
      if (p) void close(p);
    } finally {
      prepared();
    }
    try {
      await drain();
      if (valid() && replacing) publish({ canSend: true, status: 'ready' });
    } finally {
      revoking = false;
      finish(controller);
    }
  }
  function dispose(): Promise<void> {
    if (disposal) return disposal;
    let settled!: () => void;
    disposal = new Promise<void>((resolve) => {
      settled = resolve;
    });
    disposed = true;
    const previous = operation,
      p = primary;
    operation = undefined;
    primary = undefined;
    if (p) {
      p.closed = true;
      p.approval = undefined;
    }
    snapshot = Object.freeze({
      ...snapshot,
      generation: snapshot.generation + 1,
      busy: false,
      canSend: false,
      canRespond: false,
      approval: undefined,
      result: null,
      status: 'disposed',
    });
    listeners.clear();
    previous?.abort();
    if (p) void close(p);
    void drain().then(settled);
    return disposal;
  }
  return {
    getSnapshot: () => snapshot,
    subscribe(notify: () => void) {
      if (disposed) return () => undefined;
      listeners.add(notify);
      return () => {
        listeners.delete(notify);
      };
    },
    submit,
    decide,
    newConversation: () => revoke(true),
    stop: () => revoke(false),
    dispose,
  };
}