@rsconcept/rstool 0.10.3 → 1.0.1

package/src/models/tool-contract.ts

@@ -1,49 +1,88 @@
-import { type AnalysisResult, type AnalyzeExpressionInput } from './analysis';
-import {
-  type AddOrUpdateConstituentaInput,
-  type AddOrUpdateConstituentaResult
-} from './constituenta';
-import {
-  type DiagnosticRecord,
-  type ListDiagnosticsFilters
-} from './diagnostic';
 import {
-  type EvaluateConstituentaInput,
-  type EvaluateExpressionInput,
-  type EvaluationResult
-} from './evaluation';
-import {
-  type ClearConstituentaValuesInput,
-  type RecalculateModelResult,
-  type SessionModelState,
-  type SetConstituentaValueInput,
-  type SetConstituentaValuesInput
-} from './model-value';
-import {
-  type SessionHandle,
-  type SessionRevision,
-  type SessionState
-} from './session';
+  type ApplySchemaPatchInput,
+  type ApplySchemaPatchResult,
+  type SessionStateDetail,
+  type SessionStateResult
+} from './agent-workflow';
+import { type AnalysisResult, type AnalyzeExpressionInput } from './analysis';
+import { type DiagnosticRecord, type ListDiagnosticsFilters } from './diagnostic';
+import { type EvaluateInput, type EvaluationResult } from './evaluation';
+import { type ExportPortalInput, type ExportPortalResult, type ImportDataKind } from './import-export';
+import { type RecalculateModelResult, type SessionModelState, type SetModelValuesInput } from './model-value';
+import { type SessionHandle, type SessionRevision, type SessionState } from './session';
 
-export const CONTRACT_VERSION = '1.4.0';
+/** Agent-visible contract version; bump on breaking API changes. */
+export const CONTRACT_VERSION = '2.0.0';
 
+/** Options for constructing an {@link RSToolAgent}. */
+export interface RSToolAgentOptions {
+  /** When set, sessions are persisted to this directory and survive process restarts. */
+  persistenceDir?: string;
+}
+
+/**
+ * Public method surface of {@link RSToolAgent}.
+ *
+ * Each method accepts an optional `sessionId`; when omitted, the current session is used
+ * (or a new one is created where noted).
+ */
 export interface RSToolAgentContract {
+  /** Current contract version string (same as {@link CONTRACT_VERSION}). */
   readonly contractVersion: string;
+
+  /** Return the current session, or create one with optional `initial` metadata. */
+  ensureSession(initial?: Partial<SessionState>): SessionHandle;
+
+  /** Create a new session and make it current. */
   createSession(initial?: Partial<SessionState>): SessionHandle;
-  addOrUpdateConstituenta(sessionId: string, input: AddOrUpdateConstituentaInput): AddOrUpdateConstituentaResult;
-  analyzeExpression(sessionId: string, input: AnalyzeExpressionInput): AnalysisResult;
-  getFormState(sessionId: string): SessionState;
-  listDiagnostics(sessionId: string, filters?: ListDiagnosticsFilters): DiagnosticRecord[];
-  commitStep(sessionId: string, message?: string): SessionRevision;
-  exportSession(sessionId: string): string;
-  exportPortalSchema(sessionId: string): string;
-  exportPortalModel(sessionId: string): string;
-  importSession(payload: string): SessionHandle;
-  setConstituentaValue(sessionId: string, input: SetConstituentaValueInput): Promise<SessionModelState>;
-  setConstituentaValues(sessionId: string, input: SetConstituentaValuesInput): Promise<SessionModelState>;
-  clearConstituentaValues(sessionId: string, input: ClearConstituentaValuesInput): Promise<SessionModelState>;
-  getModelState(sessionId: string): SessionModelState;
-  evaluateExpression(sessionId: string, input: EvaluateExpressionInput): EvaluationResult;
-  evaluateConstituenta(sessionId: string, input: EvaluateConstituentaInput): EvaluationResult;
-  recalculateModel(sessionId: string): RecalculateModelResult;
+
+  /** Return the current session handle, or `null` when none is active. */
+  getCurrentSession(): SessionHandle | null;
+
+  /** Switch the active session; throws when `sessionId` is unknown. */
+  setCurrentSession(sessionId: string): SessionHandle;
+
+  /** Apply constituent patches to the schema (analyze, merge, optionally commit). */
+  applySchemaPatch(input: ApplySchemaPatchInput, sessionId?: string): ApplySchemaPatchResult;
+
+  /** Return session summary (default) or full cloned state when `detail` is `'full'`. */
+  getSessionState(detail?: SessionStateDetail, sessionId?: string): SessionStateResult;
+
+  /** List diagnostics for the session, optionally filtered by constituent. */
+  listDiagnostics(filters?: ListDiagnosticsFilters, sessionId?: string): DiagnosticRecord[];
+
+  /** Parse and type-check an RSLang expression against the current schema context. */
+  analyzeExpression(input: AnalyzeExpressionInput, sessionId?: string): AnalysisResult;
+
+  /** Record a revision checkpoint with an optional message. */
+  commitStep(message?: string, sessionId?: string): SessionRevision;
+
+  /** Export the session as a JSON string (state + diagnostics). */
+  exportSession(sessionId?: string): string;
+
+  /** Export schema or model payload in Portal JSON format. */
+  exportPortal(input: ExportPortalInput, sessionId?: string): ExportPortalResult;
+
+  /**
+   * Import a session export or Portal JSON payload and make the new session current.
+   *
+   * When `kind` is `'auto'`, the payload shape is detected automatically.
+   */
+  importData(payload: string | object, kind?: ImportDataKind): SessionHandle;
+
+  /** Set or clear model values for constituents; returns the updated model state. */
+  setModelValues(input: SetModelValuesInput, sessionId?: string): Promise<SessionModelState>;
+
+  /** Return a deep clone of the session model state. */
+  getModelState(sessionId?: string): SessionModelState;
+
+  /**
+   * Evaluate a stored constituent or a scratch expression.
+   *
+   * Provide `constituentId`, or both `expression` and `cstType`.
+   */
+  evaluate(input: EvaluateInput, sessionId?: string): EvaluationResult;
+
+  /** Recompute derived model values for all constituents. */
+  recalculateModel(sessionId?: string): RecalculateModelResult;
 }

package/src/session/batch-apply.test.ts

@@ -0,0 +1,123 @@
+import { describe, expect, it } from 'vitest';
+
+import { CstType } from '../models';
+import { orderDrafts, reorderSessionItemsByDrafts } from './batch-apply';
+
+const baseItem = {
+  id: 1,
+  alias: 'X1',
+  cstType: CstType.BASE,
+  definitionFormal: '',
+  term: '',
+  definitionText: '',
+  convention: '',
+  analysis: { success: true, type: null, valueClass: 'value' as const, diagnostics: [] }
+};
+
+describe('orderDrafts', () => {
+  it('orders dependents after suppliers', () => {
+    const ordered = orderDrafts(
+      [baseItem],
+      [
+        { id: 3, alias: 'D1', cstType: CstType.TERM, definitionFormal: 'Pr1(S1)' },
+        { id: 2, alias: 'S1', cstType: CstType.STRUCTURED, definitionFormal: 'ℬ(X1×X1)' }
+      ]
+    );
+    expect(ordered.map(draft => draft.alias)).toEqual(['S1', 'D1']);
+  });
+
+  it('orders multi-hop chains X1 → S1 → D1', () => {
+    const ordered = orderDrafts(
+      [baseItem],
+      [
+        { id: 4, alias: 'D1', cstType: CstType.TERM, definitionFormal: 'Pr1(S1)' },
+        { id: 3, alias: 'S1', cstType: CstType.STRUCTURED, definitionFormal: 'ℬ(X1×X1)' },
+        { id: 2, alias: 'C1', cstType: CstType.CONSTANT, definitionFormal: '' }
+      ]
+    );
+    expect(ordered.map(draft => draft.alias)).toEqual(['C1', 'S1', 'D1']);
+  });
+
+  it('orders draft that only references existing session items', () => {
+    const ordered = orderDrafts(
+      [
+        baseItem,
+        {
+          id: 2,
+          alias: 'S1',
+          cstType: CstType.STRUCTURED,
+          definitionFormal: 'ℬ(X1×X1)',
+          term: '',
+          definitionText: '',
+          convention: '',
+          analysis: { success: true, type: null, valueClass: 'value', diagnostics: [] }
+        }
+      ],
+      [{ id: 3, alias: 'D1', cstType: CstType.TERM, definitionFormal: 'Pr1(S1)' }]
+    );
+    expect(ordered.map(draft => draft.alias)).toEqual(['D1']);
+  });
+
+  it('appends cyclic drafts after topological ids', () => {
+    const ordered = orderDrafts(
+      [],
+      [
+        { id: 1, alias: 'D1', cstType: CstType.TERM, definitionFormal: 'D2' },
+        { id: 2, alias: 'D2', cstType: CstType.TERM, definitionFormal: 'D1' }
+      ]
+    );
+    expect(ordered.map(draft => draft.alias).sort()).toEqual(['D1', 'D2']);
+    expect(ordered).toHaveLength(2);
+  });
+
+  it('returns all independent drafts', () => {
+    const ordered = orderDrafts(
+      [],
+      [
+        { id: 1, alias: 'C1', cstType: CstType.CONSTANT, definitionFormal: '' },
+        { id: 2, alias: 'C2', cstType: CstType.CONSTANT, definitionFormal: '' }
+      ]
+    );
+    expect(ordered.map(draft => draft.alias).sort()).toEqual(['C1', 'C2']);
+    expect(ordered).toHaveLength(2);
+  });
+});
+
+describe('reorderSessionItemsByDrafts', () => {
+  const mk = (id: number, alias: string) => ({
+    id,
+    alias,
+    cstType: CstType.BASE,
+    definitionFormal: '',
+    term: '',
+    definitionText: '',
+    convention: '',
+    analysis: { success: true, type: null, valueClass: 'value' as const, diagnostics: [] }
+  });
+
+  it('restores full-batch declaration order', () => {
+    const items = [mk(4, 'X1'), mk(3, 'C1'), mk(2, 'S1'), mk(1, 'D1')];
+    reorderSessionItemsByDrafts(items, [
+      { id: 1, alias: 'D1', cstType: CstType.TERM, definitionFormal: 'Pr1(S1)' },
+      { id: 2, alias: 'S1', cstType: CstType.STRUCTURED, definitionFormal: 'ℬ(X1×X1)' },
+      { id: 3, alias: 'C1', cstType: CstType.CONSTANT, definitionFormal: '' },
+      { id: 4, alias: 'X1', cstType: CstType.BASE, definitionFormal: '' }
+    ]);
+    expect(items.map(item => item.alias)).toEqual(['D1', 'S1', 'C1', 'X1']);
+  });
+
+  it('appends only new items in draft order', () => {
+    const items = [mk(1, 'X1'), mk(3, 'S1'), mk(2, 'C1')];
+    reorderSessionItemsByDrafts(items, [
+      { id: 2, alias: 'C1', cstType: CstType.CONSTANT, definitionFormal: '' },
+      { id: 3, alias: 'S1', cstType: CstType.STRUCTURED, definitionFormal: 'ℬ(X1×X1)' }
+    ]);
+    expect(items.map(item => item.alias)).toEqual(['X1', 'C1', 'S1']);
+  });
+
+  it('does not move existing items on update-only patch', () => {
+    const items = [mk(1, 'X1'), mk(2, 'D1')];
+    reorderSessionItemsByDrafts(items, [{ id: 2, alias: 'D1', cstType: CstType.TERM, definitionFormal: '1+2' }]);
+    expect(items.map(item => item.alias)).toEqual(['X1', 'D1']);
+  });
+});

package/src/session/batch-apply.ts

@@ -0,0 +1,82 @@
+import { Graph } from '@rsconcept/domain/graph/graph';
+import { extractGlobals } from '@rsconcept/domain/rslang/api';
+
+import { type ConstituentaDraft, type ConstituentaState } from '../models';
+
+/** Order drafts so suppliers are applied before dependents. */
+export function orderDrafts(sessionItems: ConstituentaState[], drafts: ConstituentaDraft[]): ConstituentaDraft[] {
+  const merged = new Map<number, ConstituentaDraft>();
+  for (const item of sessionItems) {
+    merged.set(item.id, {
+      id: item.id,
+      alias: item.alias,
+      cstType: item.cstType,
+      definitionFormal: item.definitionFormal
+    });
+  }
+  for (const draft of drafts) {
+    merged.set(draft.id, draft);
+  }
+
+  const graph = new Graph<number>();
+  const aliasToId = new Map<string, number>();
+  for (const [id, draft] of merged) {
+    graph.addNode(id);
+    aliasToId.set(draft.alias, id);
+  }
+
+  for (const [id, draft] of merged) {
+    if (!draft.definitionFormal) {
+      continue;
+    }
+    for (const alias of extractGlobals(draft.definitionFormal)) {
+      const depId = aliasToId.get(alias);
+      if (depId !== undefined && depId !== id) {
+        graph.addEdge(depId, id);
+      }
+    }
+  }
+
+  const draftIds = new Set(drafts.map(draft => draft.id));
+  const topoIds = graph.topologicalOrder().filter(id => draftIds.has(id));
+  const seen = new Set(topoIds);
+  const missing = drafts.filter(draft => !seen.has(draft.id)).map(draft => draft.id);
+
+  const orderedIds = [...topoIds, ...missing];
+  return orderedIds.map(id => drafts.find(draft => draft.id === id)!).filter(Boolean);
+}
+
+/**
+ * Restore declaration order in session items after a batch apply.
+ * Topological apply order is only needed for analysis; Portal JSON uses array order.
+ */
+export function reorderSessionItemsByDrafts(items: ConstituentaState[], drafts: ConstituentaDraft[]): void {
+  if (drafts.length === 0 || items.length === 0) {
+    return;
+  }
+
+  const draftIds = drafts.map(draft => draft.id);
+  const draftIdSet = new Set(draftIds);
+  const mentioned = items.filter(item => draftIdSet.has(item.id));
+  if (mentioned.length === 0) {
+    return;
+  }
+
+  const unmentioned = items.filter(item => !draftIdSet.has(item.id));
+  if (unmentioned.length === 0) {
+    const byId = new Map(items.map(item => [item.id, item]));
+    items.splice(0, items.length, ...draftIds.map(id => byId.get(id)!));
+    return;
+  }
+
+  const existingIds = new Set(unmentioned.map(item => item.id));
+  const newDrafts = drafts.filter(draft => !existingIds.has(draft.id));
+  if (newDrafts.length === 0) {
+    return;
+  }
+
+  const newIds = new Set(newDrafts.map(draft => draft.id));
+  const kept = items.filter(item => !newIds.has(item.id));
+  const byId = new Map(items.map(item => [item.id, item]));
+  items.splice(0, items.length, ...kept, ...newDrafts.map(draft => byId.get(draft.id)!));
+}

package/src/session/persistence.test.ts

@@ -0,0 +1,63 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { SessionPersistence, type PersistedSessionEnvelope } from './persistence';
+
+const envelope: PersistedSessionEnvelope = {
+  state: {
+    sessionId: 'safe-id',
+    alias: '',
+    title: '',
+    comment: '',
+    createdAt: '2026-01-01T00:00:00.000Z',
+    updatedAt: '2026-01-01T00:00:00.000Z',
+    revisions: [],
+    items: [],
+    model: { items: [] }
+  },
+  diagnostics: []
+};
+
+describe('SessionPersistence', () => {
+  const dirs: string[] = [];
+
+  afterEach(() => {
+    for (const dir of dirs.splice(0)) {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  function createPersistence(): SessionPersistence {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'rstool-session-'));
+    dirs.push(dir);
+    return new SessionPersistence(dir);
+  }
+
+  it('persists a safe session id under the configured directory', () => {
+    const persistence = createPersistence();
+    const sessionId = 'a03eec4c-6519-4088-9d8c-0a9c11611583';
+
+    persistence.save(sessionId, envelope);
+
+    expect(persistence.load(sessionId)).toEqual(envelope);
+    persistence.delete(sessionId);
+    expect(persistence.load(sessionId)).toBeNull();
+  });
+
+  it.each(['../escape', 'foo/bar', 'foo\\bar', '..', 'safe/../escape'])(
+    'rejects unsafe session id %j on save',
+    unsafeId => {
+      const persistence = createPersistence();
+      expect(() => persistence.save(unsafeId, envelope)).toThrow(/Invalid session ID/);
+    }
+  );
+
+  it.each(['../escape', 'foo/bar', 'foo\\bar', '..'])('rejects unsafe session id %j on load and delete', unsafeId => {
+    const persistence = createPersistence();
+    expect(() => persistence.load(unsafeId)).toThrow(/Invalid session ID/);
+    expect(() => persistence.delete(unsafeId)).toThrow(/Invalid session ID/);
+  });
+});

package/src/session/persistence.ts

@@ -0,0 +1,69 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { type DiagnosticRecord, type SessionState } from '../models';
+
+export interface PersistedSessionEnvelope {
+  state: SessionState;
+  diagnostics: DiagnosticRecord[];
+}
+
+const CURRENT_SESSION_FILE = '_current.json';
+const UNSAFE_SESSION_ID = /[/\\]|\.\./;
+
+function assertSafeSessionId(sessionId: string): void {
+  if (!sessionId || UNSAFE_SESSION_ID.test(sessionId)) {
+    throw new Error(`Invalid session ID: ${sessionId}`);
+  }
+}
+
+export class SessionPersistence {
+  private readonly dir: string;
+
+  public constructor(dir: string) {
+    this.dir = dir;
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  public save(sessionId: string, envelope: PersistedSessionEnvelope): void {
+    fs.writeFileSync(this.filePath(sessionId), JSON.stringify(envelope, null, 2), 'utf-8');
+  }
+
+  public load(sessionId: string): PersistedSessionEnvelope | null {
+    const file = this.filePath(sessionId);
+    if (!fs.existsSync(file)) {
+      return null;
+    }
+    return JSON.parse(fs.readFileSync(file, 'utf-8')) as PersistedSessionEnvelope;
+  }
+
+  public delete(sessionId: string): void {
+    const file = this.filePath(sessionId);
+    if (fs.existsSync(file)) {
+      fs.unlinkSync(file);
+    }
+  }
+
+  public saveCurrentSessionId(sessionId: string | null): void {
+    fs.writeFileSync(path.join(this.dir, CURRENT_SESSION_FILE), JSON.stringify({ sessionId }, null, 2), 'utf-8');
+  }
+
+  public loadCurrentSessionId(): string | null {
+    const file = path.join(this.dir, CURRENT_SESSION_FILE);
+    if (!fs.existsSync(file)) {
+      return null;
+    }
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf-8')) as { sessionId?: string | null };
+    return parsed.sessionId ?? null;
+  }
+
+  private filePath(sessionId: string): string {
+    assertSafeSessionId(sessionId);
+    const file = path.resolve(this.dir, `${sessionId}.json`);
+    const relative = path.relative(path.resolve(this.dir), file);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) {
+      throw new Error(`Invalid session ID: ${sessionId}`);
+    }
+    return file;
+  }
+}

package/src/session/session-store.ts

@@ -1,12 +1,18 @@
 import { randomUUID } from 'node:crypto';
 
 import {
+  CONTRACT_VERSION,
   type DiagnosticRecord,
   type ListDiagnosticsFilters,
   type SessionHandle,
   type SessionRevision,
   type SessionState
 } from '../models';
+import { SessionPersistence, type PersistedSessionEnvelope } from './persistence';
+
+export interface SessionStoreOptions {
+  persistenceDir?: string;
+}
 
 interface SessionEnvelope {
   state: SessionState;
@@ -15,6 +21,11 @@ interface SessionEnvelope {
 
 export class SessionStore {
   private sessions = new Map<string, SessionEnvelope>();
+  private readonly persistence: SessionPersistence | null;
+
+  public constructor(options: SessionStoreOptions = {}) {
+    this.persistence = options.persistenceDir ? new SessionPersistence(options.persistenceDir) : null;
+  }
 
   public create(initial?: Partial<SessionState>, contractVersion?: string): SessionHandle {
     const now = new Date().toISOString();
@@ -30,30 +41,43 @@ export class SessionStore {
       items: initial?.items ?? [],
       model: initial?.model ?? { items: [] }
     };
-    this.sessions.set(sessionId, {
+    const envelope: SessionEnvelope = {
       state,
       diagnostics: []
-    });
+    };
+    this.sessions.set(sessionId, envelope);
+    this.persist(sessionId, envelope);
     return {
       sessionId,
-      contractVersion: contractVersion ?? '1.0.0'
+      contractVersion: contractVersion ?? CONTRACT_VERSION
     };
   }
 
   public get(sessionId: string): SessionEnvelope {
-    const found = this.sessions.get(sessionId);
+    const found = this.sessions.get(sessionId) ?? this.loadFromDisk(sessionId);
     if (!found) {
       throw new Error(`Unknown session: ${sessionId}`);
     }
     return found;
   }
 
+  public has(sessionId: string): boolean {
+    if (this.sessions.has(sessionId)) {
+      return true;
+    }
+    if (!this.persistence) {
+      return false;
+    }
+    return this.persistence.load(sessionId) !== null;
+  }
+
   public replaceState(sessionId: string, nextState: SessionState): void {
     const found = this.get(sessionId);
     found.state = {
       ...nextState,
       updatedAt: new Date().toISOString()
     };
+    this.persist(sessionId, found);
   }
 
   public addRevision(sessionId: string, message?: string): SessionRevision {
@@ -65,20 +89,66 @@ export class SessionStore {
     };
     found.state.revisions.push(revision);
     found.state.updatedAt = revision.at;
+    this.persist(sessionId, found);
     return revision;
   }
 
-  public appendDiagnostics(sessionId: string, records: DiagnosticRecord[]): void {
+  /** Replace active diagnostics for one constituent (or scratch when constituentId is undefined). */
+  public replaceDiagnosticsForConstituent(
+    sessionId: string,
+    constituentId: number | undefined,
+    records: DiagnosticRecord[]
+  ): void {
     const found = this.get(sessionId);
+    found.diagnostics = found.diagnostics.filter(record => record.constituentId !== constituentId);
     found.diagnostics.push(...records);
     found.state.updatedAt = new Date().toISOString();
+    this.persist(sessionId, found);
+  }
+
+  public setDiagnostics(sessionId: string, records: DiagnosticRecord[]): void {
+    const found = this.get(sessionId);
+    found.diagnostics = [...records];
+    found.state.updatedAt = new Date().toISOString();
+    this.persist(sessionId, found);
   }
 
   public listDiagnostics(sessionId: string, filters?: ListDiagnosticsFilters): DiagnosticRecord[] {
     const found = this.get(sessionId);
-    if (!filters?.constituentId) {
+    if (filters?.constituentId === undefined) {
       return [...found.diagnostics];
     }
     return found.diagnostics.filter(record => record.constituentId === filters.constituentId);
   }
+
+  public snapshot(sessionId: string): SessionEnvelope {
+    const found = this.get(sessionId);
+    return structuredClone(found);
+  }
+
+  public restore(sessionId: string, snapshot: SessionEnvelope): void {
+    this.sessions.set(sessionId, structuredClone(snapshot));
+    this.persist(sessionId, this.sessions.get(sessionId)!);
+  }
+
+  public saveCurrentSessionId(sessionId: string | null): void {
+    this.persistence?.saveCurrentSessionId(sessionId);
+  }
+
+  public loadCurrentSessionId(): string | null {
+    return this.persistence?.loadCurrentSessionId() ?? null;
+  }
+
+  private loadFromDisk(sessionId: string): SessionEnvelope | null {
+    const loaded = this.persistence?.load(sessionId);
+    if (!loaded) {
+      return null;
+    }
+    this.sessions.set(sessionId, loaded);
+    return loaded;
+  }
+
+  private persist(sessionId: string, envelope: SessionEnvelope): void {
+    this.persistence?.save(sessionId, envelope as PersistedSessionEnvelope);
+  }
 }

package/src/wrapper/client.test.ts

@@ -0,0 +1,58 @@
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+import { CstType, EvalStatus, RSToolWrapperClient } from '../index';
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '../..');
+
+describe('RSToolWrapperClient integration', () => {
+  it('runs createSession, patch, model, and evaluate over stdio', async () => {
+    const client = new RSToolWrapperClient({
+      command: 'npx',
+      args: ['tsx', resolve(packageRoot, 'src/wrapper/stdio-wrapper.ts')],
+      cwd: packageRoot,
+      shell: true
+    });
+
+    try {
+      await client.waitUntilReady();
+
+      const methods = await client.call<string[]>('methods');
+      expect(methods).toContain('applySchemaPatch');
+
+      const session = await client.call<{ sessionId: string; contractVersion: string }>('createSession', {
+        initial: { title: 'Wrapper test' }
+      });
+      expect(session.sessionId).toBeTruthy();
+
+      await client.call('applySchemaPatch', {
+        sessionId: session.sessionId,
+        items: [{ alias: 'X1' }, { alias: 'D1', definitionFormal: '1+2' }]
+      });
+
+      await client.call('setModelValues', {
+        sessionId: session.sessionId,
+        set: [{ target: 1, value: { 0: 'zero' } }]
+      });
+
+      const evalResult = await client.call<{ success: boolean; value: number; status: number }>('evaluate', {
+        sessionId: session.sessionId,
+        constituentId: 2
+      });
+      expect(evalResult.success).toBe(true);
+      expect(evalResult.value).toBe(3);
+      expect(evalResult.status).toBe(EvalStatus.HAS_DATA);
+
+      const analysis = await client.call<{ success: boolean; diagnostics: unknown[] }>('analyzeExpression', {
+        sessionId: session.sessionId,
+        expression: '(',
+        cstType: CstType.TERM
+      });
+      expect(analysis.success).toBe(false);
+      expect(analysis.diagnostics.length).toBeGreaterThan(0);
+    } finally {
+      await client.close();
+    }
+  }, 30_000);
+});