React Deep Agents Skills 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 { useCallback, useEffect, useState } from 'react';
import { useAgent } from '@threadplane/react';
import {
  ChatInput,
  MessageList,
  ToolObservation,
  Reasoning,
  Citations,
} from '@threadplane/react/chat';
import { Markdown } from '@threadplane/react/markdown';
import type { MessageRow } from '@threadplane/content/messages';
import type { SkillIndex } from './index-projection';
import type { ReadProjection, SkillRead } from './read-projection';
import { copyData, LIMITS, type Authority } from './authority';
import {
  createConnectedApplication,
  type skillsConnection,
} from './connection';
 
function literal(value: unknown): string {
  try {
    const copied = copyData(value);
    const text =
      typeof copied === 'string'
        ? copied
        : JSON.stringify(copied, null, 2) ?? '';
    return text.length <= LIMITS.fieldText
      ? text
      : 'Observation text unavailable: display limit exceeded.';
  } catch {
    return 'Observation text unavailable.';
  }
}
 
/** Application owns row Markdown snapshots and tool/result association. */
export function renderMessage(
  row: MessageRow,
  authority: Authority = { kind: 'unconfirmed' }
) {
  if (row.role === 'tool') return null;
  const label =
    row.role === 'user'
      ? 'You'
      : row.role === 'assistant'
      ? 'Assistant'
      : 'System';
  return (
    <article
      aria-label={label}
      className={`tp-chat-message tp-chat-message--${row.role}`}
    >
      <p className="tp-chat-message__role">{label}</p>
      {row.role === 'assistant' && row.reasoning && (
        <Reasoning snapshot={row.reasoning} />
      )}
      <Markdown snapshot={row.markdown} />
      {row.toolCalls.map((call) => {
        const error =
          call.status === 'error' ||
          (authority.kind === 'terminal' &&
            authority.rawToolStatuses[call.id] === 'error');
        return (
          <div
            key={call.id}
            className="tool-observation"
            data-call-id={call.id}
          >
            <p>
              {error
                ? 'Tool result: error'
                : `Observed delivery: ${call.status}`}
            </p>
            <ToolObservation
              name={call.name}
              argumentsText={literal(call.args)}
              resultText={
                call.status === 'complete'
                  ? literal(call.result)
                  : call.status === 'error'
                  ? literal(call.error)
                  : undefined
              }
              label={error ? 'Observed tool error' : 'Observed tool delivery'}
            />
          </div>
        );
      })}
      {row.role === 'assistant' && row.message.citations && (
        <Citations citations={row.message.citations} />
      )}
    </article>
  );
}
 
const readLabels: Record<SkillRead['kind'], string> = {
  pending: 'Read pending',
  unknown: 'Read status unknown',
  error: 'Read failed',
  unavailable: 'Read evidence unavailable',
  partial: 'Partially inspected',
  inspected: 'Inspected',
};
const hasReads = (value: ReadProjection): value is readonly SkillRead[] =>
  Array.isArray(value);
export function SkillPanels({
  index,
  reads,
}: {
  index: SkillIndex;
  reads: ReadProjection;
}) {
  return (
    <div className="skill-panels">
      <section aria-label="Skills index">
        <h2>Skills index</h2>
        <p>
          The index shows names, descriptions, virtual instruction paths, and
          optional support annotations. Metadata does not establish that
          instructions were read.
        </p>
        {index.kind === 'ready' ? (
          <>
            <p data-testid="skills-source" data-source={index.source}>
              {index.source === 'checkpoint'
                ? 'Confirmed checkpoint'
                : 'Observed root values'}
            </p>
            {!index.skills.length && <p>The skills index is empty.</p>}
            {index.skills.map((skill) => (
              <article key={skill.path}>
                <h3>{skill.name}</h3>
                <p>{skill.description}</p>
                <code>{skill.path}</code>
                {(skill.license !== undefined ||
                  skill.compatibility !== undefined ||
                  skill.allowed_tools !== undefined ||
                  skill.metadata !== undefined) && (
                  <details>
                    <summary>Skill metadata</summary>
                    {skill.license !== undefined && (
                      <p>License: {skill.license ?? 'unspecified'}</p>
                    )}
                    {skill.compatibility !== undefined && (
                      <p>
                        Compatibility: {skill.compatibility ?? 'unspecified'}
                      </p>
                    )}
                    {skill.allowed_tools !== undefined && (
                      <p>
                        Allowed tools:{' '}
                        {skill.allowed_tools.join(', ') || 'none listed'}
                      </p>
                    )}
                    {skill.metadata && <pre>{literal(skill.metadata)}</pre>}
                  </details>
                )}
              </article>
            ))}
          </>
        ) : (
          <p>
            {index.kind === 'absent'
              ? 'No skills index observed.'
              : index.kind === 'stale'
              ? 'Skills index belongs to an earlier conversation.'
              : 'Skills index unavailable.'}
          </p>
        )}
      </section>
      <section aria-label="Skill read observations">
        <h2>Skill read observations</h2>
        <p>
          Instruction bodies and references are read on demand during a
          response. Inspected describes observed read evidence; it does not
          imply the whole file was read.
        </p>
        {hasReads(reads) ? (
          !reads.length ? (
            <p>No associated skill reads observed.</p>
          ) : (
            reads.map((read) => (
              <article key={read.id} data-read-kind={read.kind}>
                <h3>{read.skillName}</h3>
                <p>
                  Read call: <code>{read.id}</code>
                </p>
                <p>
                  {read.category === 'instruction'
                    ? 'Skill instruction'
                    : 'Skill reference'}
                </p>
                <code>{read.path}</code>
                <p>{readLabels[read.kind]}</p>
                {read.empty && <p>An empty-file reminder was observed.</p>}
                {read.result !== undefined && (
                  <details>
                    <summary>Literal read result</summary>
                    <pre>{read.result}</pre>
                  </details>
                )}
              </article>
            ))
          )
        ) : (
          <p>Read observations unavailable.</p>
        )}
      </section>
    </div>
  );
}
 
export function SkillsDemo({
  connection,
  onReady,
}: {
  connection: ReturnType<typeof skillsConnection>;
  onReady: () => void;
}) {
  const [application] = useState(() => createConnectedApplication(connection));
  const [draft, setDraft] = useState('');
  const snapshot = useAgent(application);
  const renderRow = useCallback(
    (row: MessageRow) => renderMessage(row, snapshot.authority),
    [snapshot.authority]
  );
  useEffect(() => {
    onReady();
  }, [onReady]);
  useEffect(
    () => () => {
      void application.dispose();
    },
    [application]
  );
  useEffect(() => {
    setDraft('');
  }, [snapshot.viewGeneration]);
  const status = snapshot.busy
    ? snapshot.activity === 'confirming'
      ? 'Confirming saved conversation…'
      : snapshot.activity === 'restoring'
      ? 'Restoring conversation…'
      : snapshot.activity === 'creating'
      ? 'Creating conversation…'
      : 'Receiving response…'
    : !snapshot.canSubmit
    ? 'Start a new conversation to continue.'
    : snapshot.outcome === 'success'
    ? 'Response saved.'
    : 'Ready.';
  return (
    <ExampleLayout className="skills-demo">
      <header>
        <div>
          <h1>Deep Agents skills</h1>
        </div>
        <button
          type="button"
          onClick={() => {
            setDraft('');
            void application.newConversation();
          }}
        >
          New conversation
        </button>
      </header>
      <p>
        Inspect progressive disclosure of skill metadata, instructions, and
        reference files. Aviation examples use fixed sample data. Stop cancels
        local delivery; backend work may continue.
      </p>
      <div className="seed-prompts" aria-label="Example prompts">
        <button
          type="button"
          disabled={snapshot.busy || !snapshot.canSubmit}
          onClick={() => {
            const current = application.getSnapshot();
            if (current.canSubmit && !current.busy)
              setDraft('Can a mid-size jet operate out of KASE?');
          }}
        >
          Mid-size jet at KASE
        </button>
      </div>
      <label>
        Saved conversations{' '}
        <select
          aria-label="Saved conversations"
          value={snapshot.threadId ?? ''}
          disabled={snapshot.busy}
          onChange={(event) => {
            if (!event.target.value) return;
            setDraft('');
            void application.selectConversation(event.target.value);
          }}
        >
          <option value="">Choose a saved conversation</option>
          {snapshot.history.map((entry) => (
            <option key={entry.id} value={entry.id}>
              {entry.label}
            </option>
          ))}
        </select>
      </label>
      <div className="skills-workspace">
        <div className="skills-chat">
          <MessageList
            rows={snapshot.rows}
            renderMessage={renderRow}
            label="Conversation"
          />
          <ExampleFooter>
            {snapshot.error && <p role="alert">{snapshot.error}</p>}
            <ChatInput
              key={snapshot.viewGeneration}
              label="Message"
              value={draft}
              onValueChange={setDraft}
              placeholder="Ask about aircraft and runway requirements…"
              hint="Enter to send. Shift+Enter adds a new line."
              busy={snapshot.busy}
              disabled={!snapshot.canSubmit && !snapshot.busy}
              onStop={snapshot.busy ? () => void application.stop() : undefined}
              onSubmit={(text) => {
                const current = application.getSnapshot();
                if (!current.canSubmit || current.busy || !text.trim())
                  return false;
                void application.submit(text);
                return true;
              }}
            />
            <p role="status">{status}</p>
          </ExampleFooter>
        </div>
        <aside className="skills-sidebar" aria-label="Skills sidebar">
          <SkillPanels index={snapshot.index} reads={snapshot.reads} />
        </aside>
      </div>
    </ExampleLayout>
  );
}

import { Client } from '@langchain/langgraph-sdk';
import { createSession } from '@threadplane/langgraph';
// eslint-disable-next-line @nx/enforce-module-boundaries -- Internal bridge is copied by the isolated build.
import type { RuntimeBridgeConfiguration } from '../../../../../libs/cockpit-runtime-bridge/src/index';
import {
  createSkillsApplication,
  type SkillsClient,
  type SkillsSession,
} from './application';
import { copyData, record, text, LIMITS, type Checkpoint } from './authority';
export interface SkillsConnection {
  readonly apiUrl: string;
  readonly headers: Record<string, string>;
}
export function skillsConnection(
  configuration: RuntimeBridgeConfiguration
): SkillsConnection {
  if (
    configuration.status === 'error' ||
    (configuration.status === 'configured' &&
      configuration.target.kind === 'ag-ui')
  )
    throw Error('Runtime configuration failed.');
  const target =
    configuration.status === 'configured' &&
    configuration.target.kind === 'langsmith'
      ? configuration.target
      : null;
  return {
    apiUrl: target?.apiUrl ?? new URL('/api', window.location.origin).href,
    headers: target ? { 'x-api-key': target.apiKey } : {},
  };
}
export function createSkillsClient(input: SkillsConnection): SkillsClient {
  const connection = Object.freeze({
      apiUrl: input.apiUrl,
      headers: Object.freeze({ ...input.headers }),
    }),
    known = new Set<string>();
  const client = new Client({
    apiUrl: connection.apiUrl,
    apiKey: null,
    defaultHeaders: connection.headers,
    callerOptions: { maxRetries: 0 },
  });
  function owned(id: string, signal: AbortSignal) {
    if (!known.has(id) || signal.aborted)
      throw Error('Conversation unavailable.');
  }
  return {
    async createThread(signal) {
      if (signal.aborted) throw Error('Aborted');
      const id = crypto.randomUUID(),
        created = await client.threads.create({
          threadId: id,
          ifExists: 'raise',
          signal,
        });
      if (signal.aborted || created.thread_id !== id)
        throw Error('Conversation creation was not confirmed.');
      known.add(id);
      return id;
    },
    sessionFactory(id) {
      if (!known.has(id)) throw Error('Unknown conversation.');
      const session = createSession({
        assistantId: 'da-skills',
        threadId: id,
        apiUrl: connection.apiUrl,
        clientOptions: { maxRetries: 0, defaultHeaders: connection.headers },
      });
      try {
        const state = session.getSnapshot();
        if (
          ![
            'getSnapshot',
            'subscribe',
            'submit',
            'load',
            'stop',
            'dispose',
          ].every(
            (k) => typeof session[k as keyof typeof session] === 'function'
          ) ||
          ![
            state.messages,
            state.toolCalls,
            state.interrupts,
            state.subgraphs,
          ].every((x) => Array.isArray(x) && x.length === 0)
        )
          throw Error('Rejected session');
        return session as SkillsSession;
      } catch {
        void Promise.resolve(session.dispose()).catch(() => undefined);
        throw Error('Runtime session is unavailable.');
      }
    },
    async readCurrent(id, signal) {
      owned(id, signal);
      const value = await client.threads.getState(id, undefined, { signal });
      owned(id, signal);
      return value;
    },
    async readHistory(id, signal) {
      owned(id, signal);
      const value = await client.threads.getHistory(id, { limit: 1, signal });
      owned(id, signal);
      return value;
    },
    async readCheckpoint(requested, signal) {
      const v = copyData(requested, false);
      if (
        !record(v) ||
        !text(v.thread_id) ||
        v.checkpoint_ns !== '' ||
        !text(v.checkpoint_id) ||
        v.checkpoint_id.length > LIMITS.fieldText ||
        Object.keys(v).some(
          (k) =>
            ![
              'thread_id',
              'checkpoint_ns',
              'checkpoint_id',
              'checkpoint_map',
            ].includes(k)
        ) ||
        (v.checkpoint_map !== undefined &&
          (!record(v.checkpoint_map) ||
            Object.keys(v.checkpoint_map).length !== 1 ||
            v.checkpoint_map[''] !== v.checkpoint_id))
      )
        throw Error('Checkpoint unavailable.');
      const c = v as unknown as Checkpoint;
      owned(c.thread_id, signal);
      const value = await client.threads.getState(
        c.thread_id,
        c as Parameters<typeof client.threads.getState>[1],
        { signal }
      );
      owned(c.thread_id, signal);
      return value;
    },
  };
}
export function createConnectedApplication(connection: SkillsConnection) {
  return createSkillsApplication(createSkillsClient(connection));
}

import { copyData, displayUnits, LIMITS, record, text } from './authority';
 
export interface Skill {
  readonly name: string;
  readonly description: string;
  readonly path: string;
  readonly metadata?: Readonly<Record<string, string>>;
  readonly license?: string | null;
  readonly compatibility?: string | null;
  readonly allowed_tools?: readonly string[];
}
export interface IndexInput {
  readonly owner: string;
  readonly generation: string;
  readonly currentOwner: string;
  readonly currentGeneration: string;
  readonly source: 'observed-root' | 'checkpoint';
  readonly values: unknown;
}
export type SkillIndex =
  | {
      readonly kind: 'ready';
      readonly source: IndexInput['source'];
      readonly owner: string;
      readonly generation: string;
      readonly skills: readonly Skill[];
    }
  | { readonly kind: 'absent' | 'unavailable' | 'stale' };
 
/** Literal canonical virtual paths only; never decode or normalize a model path. */
export function skillPath(value: unknown): value is string {
  return (
    text(value) &&
    value.length <= LIMITS.fieldText &&
    value.startsWith('/skills/') &&
    !/[\\\\%?#\u0000-\u0020\u007f]/.test(value) &&
    value
      .slice(1)
      .split('/')
      .every((part) => part.length > 0 && part !== '.' && part !== '..')
  );
}
 
/** Every call replaces the projection. Empty, absent and malformed values cannot
 * revive a previously observed index. Custom event metadata is never a source. */
export function projectIndex(input: IndexInput): SkillIndex {
  try {
    const owned = copyData(input) as IndexInput;
    if (
      !['owner', 'generation', 'currentOwner', 'currentGeneration'].every(
        (k) => {
          const v = owned[k as keyof IndexInput];
          return text(v) && v.length <= LIMITS.fieldText;
        }
      )
    )
      return { kind: 'unavailable' };
    if (
      owned.owner !== owned.currentOwner ||
      owned.generation !== owned.currentGeneration
    )
      return { kind: 'stale' };
    if (
      !['observed-root', 'checkpoint'].includes(owned.source) ||
      !record(owned.values)
    )
      return { kind: 'unavailable' };
    if (!Object.hasOwn(owned.values, 'skills_metadata'))
      return { kind: 'absent' };
    const entries = owned.values.skills_metadata;
    if (!Array.isArray(entries) || entries.length > LIMITS.entries)
      return { kind: 'unavailable' };
    const names = new Set<string>(),
      paths = new Set<string>(),
      strings: string[] = [],
      skills: Skill[] = [];
    for (const v of entries) {
      if (
        !record(v) ||
        !text(v.name) ||
        v.name.length > 64 ||
        !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(v.name) ||
        !text(v.description) ||
        !skillPath(v.path) ||
        v.path !== '/skills/' + v.name + '/SKILL.md' ||
        names.has(v.name) ||
        paths.has(v.path)
      )
        return { kind: 'unavailable' };
      names.add(v.name);
      paths.add(v.path);
      const skill: Record<string, unknown> = {
        name: v.name,
        description: v.description,
        path: v.path,
      };
      strings.push(v.name, v.description, v.path);
      for (const key of ['license', 'compatibility']) {
        const value = v[key];
        if (value !== undefined) {
          if (value !== null && typeof value !== 'string')
            return { kind: 'unavailable' };
          skill[key] = value;
          if (typeof value === 'string') strings.push(value);
        }
      }
      if (v.metadata !== undefined) {
        if (
          !record(v.metadata) ||
          Object.keys(v.metadata).length > LIMITS.entries
        )
          return { kind: 'unavailable' };
        for (const [key, value] of Object.entries(v.metadata)) {
          if (!text(key) || typeof value !== 'string')
            return { kind: 'unavailable' };
          strings.push(key, value);
        }
        skill.metadata = v.metadata;
      }
      if (v.allowed_tools !== undefined) {
        if (
          !Array.isArray(v.allowed_tools) ||
          v.allowed_tools.length > LIMITS.entries ||
          v.allowed_tools.some((v) => !text(v)) ||
          new Set(v.allowed_tools).size !== v.allowed_tools.length
        )
          return { kind: 'unavailable' };
        strings.push(...v.allowed_tools);
        skill.allowed_tools = v.allowed_tools;
      }
      skills.push(Object.freeze(skill) as unknown as Skill);
    }
    displayUnits(strings);
    return Object.freeze({
      kind: 'ready',
      source: owned.source,
      owner: owned.owner,
      generation: owned.generation,
      skills: Object.freeze(skills),
    });
  } catch {
    return { kind: 'unavailable' };
  }
}

import type { Message, ToolCall } from '@threadplane/core';
 
/** All limits count UTF16 code units, including property keys. */
export const LIMITS = Object.freeze({
  depth: 32,
  nodes: 10000,
  copyText: 4 * 1024 * 1024,
  displayText: 1024 * 1024,
  fieldText: 65536,
  entries: 100,
});
export const record = (v: unknown): v is Record<string, unknown> =>
  !!v && typeof v === 'object' && !Array.isArray(v);
export const text = (v: unknown): v is string =>
  typeof v === 'string' && v.length > 0;
 
/** Bounded capture before recursion or serialization. Never evaluates an accessor.
 * Enumerable keys are counted before the reflective own-key scan; descriptors
 * are inspected individually rather than allocating an unbounded descriptor map. */
export function copyData(value: unknown, allowUndefined = true): unknown {
  let nodes = 0,
    units = 0;
  const parents = new Set<object>();
  const charge = (s: string) => {
    units += s.length;
    if (units > LIMITS.copyText) throw new Error('Data text limit');
  };
  function visit(v: unknown, depth: number): unknown {
    if (++nodes > LIMITS.nodes || depth > LIMITS.depth)
      throw new Error('Data structure limit');
    if (v === null || typeof v === 'boolean') return v;
    if (typeof v === 'string') {
      charge(v);
      return v;
    }
    if (v === undefined && allowUndefined) return undefined;
    if (typeof v === 'number' && Number.isFinite(v)) return v;
    if (typeof v !== 'object' || v === null || parents.has(v))
      throw new Error('Nonplain data');
    const array = Array.isArray(v),
      proto = Object.getPrototypeOf(v);
    if (
      array
        ? proto !== Array.prototype
        : proto !== Object.prototype && proto !== null
    )
      throw new Error('Nonplain prototype');
    const length = array
      ? Object.getOwnPropertyDescriptor(v, 'length')?.value
      : undefined;
    if (
      array &&
      (!Number.isInteger(length) || length > LIMITS.nodes - nodes || length < 0)
    )
      throw new Error('Array limit');
    let enumerable = 0;
    for (const k in v)
      if (Object.hasOwn(v, k) && ++enumerable > LIMITS.nodes - nodes)
        throw new Error('Key limit');
    const keys = Reflect.ownKeys(v);
    if (keys.length > LIMITS.nodes - nodes + (array ? 1 : 0))
      throw new Error('Key limit');
    if (array && keys.length !== length + 1)
      throw new Error('Sparse or decorated array');
    const out: Record<string, unknown> | unknown[] = array
      ? []
      : Object.create(null);
    parents.add(v);
    for (const k of keys) {
      if (typeof k !== 'string') throw new Error('Symbol data');
      if (array && k === 'length') continue;
      if (array && (!/^(0|[1-9][0-9]*)$/.test(k) || Number(k) >= length))
        throw new Error('Decorated array');
      charge(k);
      const d = Object.getOwnPropertyDescriptor(v, k);
      if (!d || !('value' in d) || !d.enumerable)
        throw new Error('Accessor or hidden data');
      Object.defineProperty(out, k, {
        value: visit(d.value, depth + 1),
        enumerable: true,
      });
    }
    parents.delete(v);
    return Object.freeze(out);
  }
  return visit(value, 0);
}
 
/** Stable semantic equality for already-owned bounded plain data. */
export function sameData(a: unknown, b: unknown): boolean {
  if (a === b) return true;
  if (Array.isArray(a) && Array.isArray(b))
    return a.length === b.length && a.every((v, i) => sameData(v, b[i]));
  if (!record(a) || !record(b)) return false;
  const ak = Object.keys(a),
    bk = Object.keys(b);
  return (
    ak.length === bk.length &&
    ak.every((k) => Object.hasOwn(b, k) && sameData(a[k], b[k]))
  );
}
 
export function displayUnits(strings: readonly string[]): number {
  let total = 0;
  for (const s of strings) {
    if (typeof s !== 'string') throw new Error('Unavailable display text');
    if (s.length > LIMITS.fieldText) throw new Error('Display field limit');
    total += s.length;
    if (total > LIMITS.displayText) throw new Error('Display aggregate limit');
  }
  return total;
}
/** Already-owned optional native metadata stays literal and contract-shaped. */
export function validMessageMetadata(m: Record<string, unknown>): boolean {
  if (
    ['name', 'reasoning', 'toolCallId'].some(
      (k) => m[k] !== undefined && typeof m[k] !== 'string'
    )
  )
    return false;
  if (
    m.toolCallIds !== undefined &&
    (!Array.isArray(m.toolCallIds) ||
      m.toolCallIds.some((v) => !text(v)) ||
      new Set(m.toolCallIds).size !== m.toolCallIds.length)
  )
    return false;
  if (
    m.citations !== undefined &&
    (!Array.isArray(m.citations) ||
      m.citations.some(
        (c) =>
          !record(c) ||
          !text(c.id) ||
          typeof c.index !== 'number' ||
          !Number.isFinite(c.index) ||
          ['title', 'url', 'snippet', 'sourceType', 'iconUrl'].some(
            (k) => c[k] !== undefined && typeof c[k] !== 'string'
          ) ||
          (c.publishedAt !== undefined &&
            typeof c.publishedAt !== 'string' &&
            typeof c.publishedAt !== 'number')
      ))
  )
    return false;
  return true;
}
export interface Baseline {
  readonly messages: readonly unknown[];
}
export interface TurnIdentity {
  readonly owner: string;
  readonly generation: string;
  readonly threadId: string;
  readonly humanId: string;
  readonly humanContent: string;
}
export interface Turn extends TurnIdentity {
  readonly baseline: Baseline;
}
export interface Checkpoint {
  readonly thread_id: string;
  readonly checkpoint_ns: '';
  readonly checkpoint_id: string;
  readonly checkpoint_map?: Readonly<Record<string, string>>;
}
export interface NativeSnapshot {
  readonly status: string;
  readonly messages: readonly Message[];
  readonly toolCalls: readonly ToolCall[];
  readonly values?: unknown;
  readonly interrupts: readonly unknown[];
  readonly subgraphs: readonly unknown[];
  readonly error?: unknown;
}
export interface AuthorityInput {
  readonly turn: Turn | undefined;
  readonly owner: string;
  readonly generation: string;
  readonly threadId: string;
  readonly outcome: string;
  /** Current root from the owned raw client, never child values or native synthesis. */
  readonly observedState: unknown;
  /** Fresh raw history from that same client and thread, newest first. */
  readonly history: readonly unknown[];
  /** Exact getState(thread, history[0].checkpoint), not a second current lookup. */
  readonly loadedCheckpoint: unknown;
  readonly snapshot: NativeSnapshot;
  readonly loadedSnapshot: NativeSnapshot;
}
export type Authority =
  | { readonly kind: 'unconfirmed' }
  | {
      readonly kind: 'terminal';
      readonly checkpoint: Checkpoint;
      readonly messages: readonly unknown[];
      readonly values: Readonly<Record<string, unknown>>;
      readonly rawToolStatuses: Readonly<Record<string, 'success' | 'error'>>;
      readonly turn: Turn;
    };
export function captureBaseline(
  input: unknown = { messages: [] }
): Baseline | undefined {
  try {
    const v = copyData(input, false);
    if (!record(v) || !Array.isArray(v.messages)) return undefined;
    return Object.freeze({ messages: v.messages });
  } catch {
    return undefined;
  }
}
export function captureTurn(
  baseline: Baseline | undefined,
  input: TurnIdentity
): Turn | undefined {
  try {
    const b = copyData(baseline, false),
      identity = copyData(input, false);
    if (
      !record(b) ||
      !Array.isArray(b.messages) ||
      !record(identity) ||
      ['owner', 'generation', 'threadId', 'humanId'].some(
        (k) =>
          !text(identity[k]) ||
          (identity[k] as string).length > LIMITS.fieldText
      ) ||
      typeof identity.humanContent !== 'string' ||
      identity.humanContent.length > LIMITS.fieldText ||
      b.messages.some((m) => record(m) && m.id === identity.humanId)
    )
      return undefined;
    return Object.freeze({ ...identity, baseline: b }) as unknown as Turn;
  } catch {
    return undefined;
  }
}
function checkpointSource(
  value: unknown,
  threadId: string
): Checkpoint | undefined {
  if (
    !record(value) ||
    value.thread_id !== threadId ||
    value.checkpoint_ns !== '' ||
    !text(value.checkpoint_id) ||
    value.checkpoint_id.length > LIMITS.fieldText ||
    Object.keys(value).some(
      (k) =>
        ![
          'thread_id',
          'checkpoint_ns',
          'checkpoint_id',
          'checkpoint_map',
        ].includes(k)
    )
  )
    return undefined;
  if (
    value.checkpoint_map !== undefined &&
    (!record(value.checkpoint_map) ||
      Object.keys(value.checkpoint_map).length !== 1 ||
      value.checkpoint_map[''] !== value.checkpoint_id)
  )
    return undefined;
  return value as unknown as Checkpoint;
}
const empty = (v: unknown) =>
  v === undefined || (Array.isArray(v) && v.length === 0);
const clean = (v: Record<string, unknown>) =>
  (v.error === undefined || v.error === null) &&
  empty(v.interrupts) &&
  empty(v.subgraphs) &&
  empty(v.__interrupt__);
 
/** Canonical root semantics independent of native delivery bookkeeping. */
function normalizedRaw(raw: readonly unknown[]):
  | {
      messages: Record<string, unknown>[];
      tools: Record<string, unknown>[];
      statuses: Record<string, 'success' | 'error'>;
    }
  | undefined {
  const messages: Record<string, unknown>[] = [],
    tools = new Map<string, Record<string, unknown>>(),
    ids = new Set<string>(),
    pending = new Set<string>(),
    statuses: Record<string, 'success' | 'error'> = Object.create(null);
  for (const w of raw) {
    if (
      !record(w) ||
      !text(w.id) ||
      ids.has(w.id) ||
      typeof w.content !== 'string' ||
      !clean(w) ||
      !empty(w.invalid_tool_calls) ||
      !['human', 'ai', 'tool'].includes(w.type as string)
    )
      return undefined;
    ids.add(w.id);
    const extra = w.additional_kwargs ?? {};
    if (
      !record(extra) ||
      !empty(extra.tool_calls) ||
      extra.function_call !== undefined
    )
      return undefined;
    const reasoning =
      typeof w.reasoning === 'string'
        ? w.reasoning
        : typeof extra.reasoning_content === 'string'
        ? extra.reasoning_content
        : undefined;
    // Supported citation shape is normalized explicitly; no private runtime imports.
    const source = extra.citations ?? extra.sources;
    let citations: unknown;
    if (Array.isArray(source))
      citations = source.map((s, i) => {
        if (typeof s === 'string')
          return { id: `c${i + 1}`, index: i + 1, url: s };
        const r = record(s) ? s : {},
          out: Record<string, unknown> = {
            id:
              [r.id, r.refId].find((x) => typeof x === 'string') ?? `c${i + 1}`,
            index:
              typeof r.index === 'number' && Number.isFinite(r.index)
                ? r.index
                : i + 1,
          };
        for (const [k, aliases] of Object.entries({
          title: ['title', 'name'],
          url: ['url', 'href', 'source'],
          snippet: ['snippet', 'content', 'excerpt'],
          sourceType: ['sourceType'],
          iconUrl: ['iconUrl'],
        })) {
          const v = aliases.map((a) => r[a]).find((x) => typeof x === 'string');
          if (v !== undefined) out[k] = v;
        }
        if (
          typeof r.publishedAt === 'string' ||
          typeof r.publishedAt === 'number'
        )
          out.publishedAt = r.publishedAt;
        if (record(r.extra)) out.extra = r.extra;
        return out;
      });
    const m: Record<string, unknown> = {
      id: w.id,
      role:
        w.type === 'human' ? 'user' : w.type === 'ai' ? 'assistant' : 'tool',
      content: w.content,
      ...(typeof w.name === 'string' ? { name: w.name } : {}),
    };
    if (reasoning !== undefined) m.reasoning = reasoning;
    if (citations !== undefined) m.citations = citations;
    if (w.type === 'ai') {
      if (pending.size || w.tool_call_id !== undefined) return undefined;
      const calls = w.tool_calls ?? [];
      if (!Array.isArray(calls)) return undefined;
      m.toolCallIds = [];
      for (const c of calls) {
        if (
          !record(c) ||
          !text(c.id) ||
          !text(c.name) ||
          tools.has(c.id) ||
          !Object.hasOwn(c, 'args') ||
          (c.type !== undefined && c.type !== 'tool_call') ||
          Object.keys(c).some(
            (k) => !['id', 'name', 'args', 'type'].includes(k)
          )
        )
          return undefined;
        (m.toolCallIds as string[]).push(c.id);
        tools.set(c.id, {
          id: c.id,
          name: c.name,
          args: c.args,
          status: 'pending',
        });
        pending.add(c.id);
      }
    } else if (w.type === 'tool') {
      const t =
        typeof w.tool_call_id === 'string'
          ? tools.get(w.tool_call_id)
          : undefined;
      if (
        !t ||
        !pending.delete(w.tool_call_id as string) ||
        !['success', 'error'].includes(w.status as string) ||
        (w.name !== t.name &&
          !(
            w.status === 'error' &&
            (w.name === null || w.name === undefined)
          )) ||
        !empty(w.tool_calls)
      )
        return undefined;
      m.toolCallId = w.tool_call_id;
      t.status = 'complete';
      t.result = w.content;
      statuses[w.tool_call_id as string] = w.status as 'success' | 'error';
    } else if (
      pending.size ||
      !empty(w.tool_calls) ||
      w.tool_call_id !== undefined
    )
      return undefined;
    messages.push(m);
  }
  if (
    pending.size ||
    messages[0]?.role !== 'user' ||
    messages.at(-1)?.role !== 'assistant' ||
    !text(messages.at(-1)?.content) ||
    (messages.at(-1)?.toolCallIds as unknown[])?.length
  )
    return undefined;
  return { messages, tools: [...tools.values()], statuses };
}
function nativeSemantic(
  input: NativeSnapshot
):
  | { messages: Record<string, unknown>[]; tools: readonly ToolCall[] }
  | undefined {
  if (
    input.status !== 'idle' ||
    (input.error !== undefined && input.error !== null) ||
    !Array.isArray(input.interrupts) ||
    input.interrupts.length ||
    !Array.isArray(input.subgraphs) ||
    !Array.isArray(input.messages) ||
    !Array.isArray(input.toolCalls)
  )
    return undefined;
  const messages: Record<string, unknown>[] = [],
    ids = new Set<string>();
  for (const m of input.messages) {
    if (
      !record(m) ||
      !text(m.id) ||
      ids.has(m.id) ||
      typeof m.content !== 'string' ||
      !validMessageMetadata(m) ||
      !record(m.delivery) ||
      !text(m.delivery.generation) ||
      m.delivery.phase !== 'complete' ||
      m.delivery.outcome !== 'success' ||
      Object.keys(m).some(
        (k) =>
          ![
            'id',
            'role',
            'content',
            'delivery',
            'reasoning',
            'citations',
            'name',
            'toolCallId',
            'toolCallIds',
          ].includes(k)
      )
    )
      return undefined;
    ids.add(m.id);
    const out: Record<string, unknown> = {
      id: m.id,
      role: m.role,
      content: m.content,
    };
    for (const k of ['name', 'reasoning', 'citations', 'toolCallId'])
      if (m[k as keyof Message] !== undefined) out[k] = m[k as keyof Message];
    if (m.role === 'assistant') {
      if (m.toolCallIds !== undefined && !Array.isArray(m.toolCallIds))
        return undefined;
      out.toolCallIds = m.toolCallIds ?? [];
    } else if (!empty(m.toolCallIds)) return undefined;
    messages.push(out);
  }
  return { messages, tools: input.toolCalls };
}
/** Only contiguous, complete result batches declared by a current assistant may
 * permute. Prior canonical history and all human/assistant boundaries stay strict. */
function matchesRoot(
  raw: ReturnType<typeof normalizedRaw>,
  native: ReturnType<typeof nativeSemantic>,
  prefix: number
): boolean {
  if (
    !raw ||
    !native ||
    raw.messages.length !== native.messages.length ||
    raw.tools.length !== native.tools.length
  )
    return false;
  const catalog = new Map<string, ToolCall>();
  for (const t of native.tools) {
    if (
      !record(t) ||
      !text(t.id) ||
      catalog.has(t.id) ||
      t.status !== 'complete'
    )
      return false;
    catalog.set(t.id, t);
  }
  for (const t of raw.tools)
    if (!sameData(t, catalog.get(t.id as string))) return false;
  for (let i = 0; i < raw.messages.length; i++) {
    const r = raw.messages[i],
      n = native.messages[i];
    if (!sameData(r, n)) return false;
    const callIds = r.role === 'assistant' ? (r.toolCallIds as string[]) : [];
    if (i >= prefix && callIds.length) {
      const batch = raw.messages.slice(i + 1, i + 1 + callIds.length),
        observed = native.messages.slice(i + 1, i + 1 + callIds.length);
      if (
        batch.length !== callIds.length ||
        observed.length !== callIds.length ||
        batch.some((m) => m.role !== 'tool') ||
        observed.some((m) => m.role !== 'tool')
      )
        return false;
      const byId = new Map(observed.map((m) => [m.toolCallId, m]));
      if (
        byId.size !== callIds.length ||
        batch.some(
          (m) =>
            !callIds.includes(m.toolCallId as string) ||
            !sameData(m, byId.get(m.toolCallId))
        )
      )
        return false;
      i += callIds.length;
    }
  }
  return true;
}
 
/** Compare already-owned live values with the exact checkpoint projection.
 * Deployed streams can omit the two private Skills keys. Every observed key
 * still agrees exactly; every ordinary checkpoint key must be observed. */
function matchesLiveValues(
  live: unknown,
  checkpoint: Record<string, unknown>
): boolean {
  if (!record(live)) return false;
  return (
    Object.keys(live).every(
      (key) =>
        Object.hasOwn(checkpoint, key) && sameData(live[key], checkpoint[key])
    ) &&
    Object.keys(checkpoint).every(
      (key) =>
        Object.hasOwn(live, key) ||
        key === 'skills_metadata' ||
        key === 'skills_load_errors'
    )
  );
}
 
/** A failure yields no replacement: callers retain previously confirmed authority.
 * The caller captures its owned client and turn once before asynchronous reads. */
export function captureAuthority(input: unknown): Authority {
  const unavailable: Authority = Object.freeze({ kind: 'unconfirmed' });
  try {
    const captured = copyData(input) as AuthorityInput;
    const turn = captured.turn;
    if (
      !turn ||
      ['owner', 'generation', 'threadId', 'humanId'].some(
        (k) =>
          !text((turn as unknown as Record<string, unknown>)[k]) ||
          ((turn as unknown as Record<string, unknown>)[k] as string).length >
            LIMITS.fieldText
      ) ||
      typeof turn.humanContent !== 'string' ||
      turn.humanContent.length > LIMITS.fieldText ||
      captured.outcome !== 'success' ||
      turn.owner !== captured.owner ||
      turn.generation !== captured.generation ||
      turn.threadId !== captured.threadId ||
      !Array.isArray(turn.baseline?.messages)
    )
      return unavailable;
    const observed = copyData(captured.observedState, false),
      loaded = copyData(captured.loadedCheckpoint, false),
      history = copyData(captured.history, false);
    if (
      !record(observed) ||
      !record(loaded) ||
      !Array.isArray(history) ||
      !history.length ||
      !sameData(observed, loaded) ||
      !sameData(history[0], loaded) ||
      !clean(loaded) ||
      !Array.isArray(loaded.next) ||
      loaded.next.length ||
      !Array.isArray(loaded.tasks) ||
      loaded.tasks.length ||
      !record(loaded.values) ||
      !clean(loaded.values) ||
      !Array.isArray(loaded.values.messages)
    )
      return unavailable;
    const cp = checkpointSource(loaded.checkpoint, captured.threadId);
    if (!cp) return unavailable;
    const checkpointIds = new Set<string>();
    for (const h of history) {
      if (!record(h)) return unavailable;
      const c = checkpointSource(h.checkpoint, captured.threadId);
      if (!c || checkpointIds.has(c.checkpoint_id)) return unavailable;
      checkpointIds.add(c.checkpoint_id);
    }
    const messages = loaded.values.messages,
      prefix = turn.baseline.messages;
    if (!sameData(prefix, messages.slice(0, prefix.length))) return unavailable;
    const human = messages[prefix.length];
    if (
      !record(human) ||
      human.type !== 'human' ||
      human.id !== turn.humanId ||
      human.content !== turn.humanContent ||
      messages.filter((m) => record(m) && m.id === turn.humanId).length !== 1 ||
      messages
        .slice(prefix.length + 1)
        .some((m) => record(m) && m.type === 'human')
    )
      return unavailable;
    const raw = normalizedRaw(messages),
      before = nativeSemantic(captured.snapshot),
      after = nativeSemantic(captured.loadedSnapshot);
    const otherValues: Record<string, unknown> = {};
    for (const k of Object.keys(loaded.values))
      if (k !== 'messages' && k !== '__interrupt__')
        otherValues[k] = loaded.values[k];
    if (
      !raw ||
      !matchesRoot(raw, before, prefix.length) ||
      !matchesRoot(raw, after, prefix.length) ||
      !matchesLiveValues(captured.snapshot.values, otherValues) ||
      !sameData(captured.loadedSnapshot.values, otherValues)
    )
      return unavailable;
    return Object.freeze({
      kind: 'terminal',
      checkpoint: cp,
      messages,
      values: loaded.values,
      rawToolStatuses: Object.freeze(raw.statuses),
      turn,
    });
  } catch {
    return unavailable;
  }
}