Merge pull request #21 from vitry/fix/rescue-empty-session-create

fix: accept bounded empty create snapshots

Author: vitry

marketplace/plugins/zcode/scripts/lib/zcode-client.mjs

@@ -5,7 +5,7 @@ import { readdir, realpath } from 'node:fs/promises';
 import { PluginError } from './errors.mjs';
 import { isBoundedPublicIdentifier, isSafeIdentifier } from './identifier.mjs';
 import { closeProtocolUntil, connectZCodeBroker, MAX_DRAIN_TIMEOUT_MS, spawnZCodeProtocol } from './zcode-protocol.mjs';
-import { validSessionInfo, validSetupAuthProbeSnapshot, validSnapshot as snapshotValid } from './zcode-schema.mjs';
+import { validCreateSnapshot, validSessionInfo, validSetupAuthProbeSnapshot, validSnapshot as snapshotValid } from './zcode-schema.mjs';
 import { brokerEndpointFor, brokerIdentityNameForWireOptions, ensureZCodeBroker, inspectBrokerIdentity, MAX_BROKER_IDLE_TIMEOUT_MS, MIN_BROKER_IDLE_TIMEOUT_MS, prioritizeBrokerOwnership } from '../zcode-broker.mjs';
 import { resolveWorkspaceStorage } from './workspace.mjs';
 
@@ -22,7 +22,7 @@ export class ZCodeClient {
 
   /** @param {{workspace:string,sessionId?:string,model?:{providerId:string,modelId:string,variant?:string},importedHistory?:{title?:string,createdAt?:number,updatedAt?:number,messages:Array<{role:'user'|'assistant',content:string,timestamp?:number}>}}} input */
   async createSession(input) {
-    return this.createSessionValidated(input, snapshotValid);
+    return this.createSessionValidated(input, validCreateSnapshot);
   }
 
   /** @param {{workspace:string,sessionId?:string,model?:{providerId:string,modelId:string,variant?:string},importedHistory?:{title?:string,createdAt?:number,updatedAt?:number,messages:Array<{role:'user'|'assistant',content:string,timestamp?:number}>}}} input Setup-only compatibility probe; formal runtime callers must use createSession(). */

marketplace/plugins/zcode/scripts/lib/zcode-schema.mjs

@@ -162,18 +162,36 @@ export function validSnapshot(/** @type {any} */ value, /** @type {string} */ se
 }
 
 /**
- * Setup-only compatibility validation for ZCode 0.16.1's empty projection.
- * The normal validSnapshot relation remains strict for all runtime paths.
+ * Compatibility validation for ZCode 0.16.1's initial empty projection.
+ * The normal validSnapshot relation remains strict for reads and updates.
  * @param {any} value @param {string} sessionId @param {string} workspacePath
  */
-export function validSetupAuthProbeSnapshot(value, sessionId, workspacePath) {
+function validEmptyCreateSnapshot(value, sessionId, workspacePath) {
   return validSnapshotEnvelope(value)
     && text(sessionId) && value.session.sessionId === sessionId
     && value.session.workspace.workspacePath === workspacePath && value.session.workspace.workspaceKey === workspacePath
     && value.session.status === 'idle'
     && value.projection.sessionId === 'unknown' && value.projection.status === 'idle'
     && (value.session.target === undefined || value.session.target === null)
     && (value.projection.target === undefined || value.projection.target === null)
+    && value.projection.currentTurnId === undefined
+    && value.projection.turnCount === 0 && value.projection.totalTokenCount === 0 && value.projection.contextUsed === 0
     && value.projection.pendingPermissions.length === 0 && value.projection.activeToolCalls.length === 0 && value.projection.backgroundJobs.length === 0
-    && value.runtime.eventSeq === 0 && value.runtime.pendingRequestIds.length === 0 && value.messages.length === 0;
+    && value.projection.lastError === undefined
+    && value.runtime.eventSeq === 0 && value.runtime.stateRevision === 0
+    && value.runtime.activeTurnId === undefined && value.runtime.activeTurnKind === undefined
+    && value.runtime.pendingRequestIds.length === 0
+    && (value.runtime.apiRetry === undefined || value.runtime.apiRetry === null)
+    && value.runtime.contextUsage === undefined
+    && (value.runtime.goalVerifications === undefined || value.runtime.goalVerifications.length === 0)
+    && (value.runtime.goalVerificationTimeline === undefined || value.runtime.goalVerificationTimeline.length === 0)
+    && value.messages.length === 0;
+}
+
+export function validCreateSnapshot(/** @type {any} */ value, /** @type {string} */ sessionId, /** @type {string} */ workspacePath) {
+  return validSnapshot(value, sessionId, workspacePath) || validEmptyCreateSnapshot(value, sessionId, workspacePath);
+}
+
+export function validSetupAuthProbeSnapshot(/** @type {any} */ value, /** @type {string} */ sessionId, /** @type {string} */ workspacePath) {
+  return validEmptyCreateSnapshot(value, sessionId, workspacePath);
 }

scripts/lib/zcode-client.mjs

@@ -5,7 +5,7 @@ import { readdir, realpath } from 'node:fs/promises';
 import { PluginError } from './errors.mjs';
 import { isBoundedPublicIdentifier, isSafeIdentifier } from './identifier.mjs';
 import { closeProtocolUntil, connectZCodeBroker, MAX_DRAIN_TIMEOUT_MS, spawnZCodeProtocol } from './zcode-protocol.mjs';
-import { validSessionInfo, validSetupAuthProbeSnapshot, validSnapshot as snapshotValid } from './zcode-schema.mjs';
+import { validCreateSnapshot, validSessionInfo, validSetupAuthProbeSnapshot, validSnapshot as snapshotValid } from './zcode-schema.mjs';
 import { brokerEndpointFor, brokerIdentityNameForWireOptions, ensureZCodeBroker, inspectBrokerIdentity, MAX_BROKER_IDLE_TIMEOUT_MS, MIN_BROKER_IDLE_TIMEOUT_MS, prioritizeBrokerOwnership } from '../zcode-broker.mjs';
 import { resolveWorkspaceStorage } from './workspace.mjs';
 
@@ -22,7 +22,7 @@ export class ZCodeClient {
 
   /** @param {{workspace:string,sessionId?:string,model?:{providerId:string,modelId:string,variant?:string},importedHistory?:{title?:string,createdAt?:number,updatedAt?:number,messages:Array<{role:'user'|'assistant',content:string,timestamp?:number}>}}} input */
   async createSession(input) {
-    return this.createSessionValidated(input, snapshotValid);
+    return this.createSessionValidated(input, validCreateSnapshot);
   }
 
   /** @param {{workspace:string,sessionId?:string,model?:{providerId:string,modelId:string,variant?:string},importedHistory?:{title?:string,createdAt?:number,updatedAt?:number,messages:Array<{role:'user'|'assistant',content:string,timestamp?:number}>}}} input Setup-only compatibility probe; formal runtime callers must use createSession(). */

scripts/lib/zcode-schema.mjs

@@ -162,18 +162,36 @@ export function validSnapshot(/** @type {any} */ value, /** @type {string} */ se
 }
 
 /**
- * Setup-only compatibility validation for ZCode 0.16.1's empty projection.
- * The normal validSnapshot relation remains strict for all runtime paths.
+ * Compatibility validation for ZCode 0.16.1's initial empty projection.
+ * The normal validSnapshot relation remains strict for reads and updates.
  * @param {any} value @param {string} sessionId @param {string} workspacePath
  */
-export function validSetupAuthProbeSnapshot(value, sessionId, workspacePath) {
+function validEmptyCreateSnapshot(value, sessionId, workspacePath) {
   return validSnapshotEnvelope(value)
     && text(sessionId) && value.session.sessionId === sessionId
     && value.session.workspace.workspacePath === workspacePath && value.session.workspace.workspaceKey === workspacePath
     && value.session.status === 'idle'
     && value.projection.sessionId === 'unknown' && value.projection.status === 'idle'
     && (value.session.target === undefined || value.session.target === null)
     && (value.projection.target === undefined || value.projection.target === null)
+    && value.projection.currentTurnId === undefined
+    && value.projection.turnCount === 0 && value.projection.totalTokenCount === 0 && value.projection.contextUsed === 0
     && value.projection.pendingPermissions.length === 0 && value.projection.activeToolCalls.length === 0 && value.projection.backgroundJobs.length === 0
-    && value.runtime.eventSeq === 0 && value.runtime.pendingRequestIds.length === 0 && value.messages.length === 0;
+    && value.projection.lastError === undefined
+    && value.runtime.eventSeq === 0 && value.runtime.stateRevision === 0
+    && value.runtime.activeTurnId === undefined && value.runtime.activeTurnKind === undefined
+    && value.runtime.pendingRequestIds.length === 0
+    && (value.runtime.apiRetry === undefined || value.runtime.apiRetry === null)
+    && value.runtime.contextUsage === undefined
+    && (value.runtime.goalVerifications === undefined || value.runtime.goalVerifications.length === 0)
+    && (value.runtime.goalVerificationTimeline === undefined || value.runtime.goalVerificationTimeline.length === 0)
+    && value.messages.length === 0;
+}
+
+export function validCreateSnapshot(/** @type {any} */ value, /** @type {string} */ sessionId, /** @type {string} */ workspacePath) {
+  return validSnapshot(value, sessionId, workspacePath) || validEmptyCreateSnapshot(value, sessionId, workspacePath);
+}
+
+export function validSetupAuthProbeSnapshot(/** @type {any} */ value, /** @type {string} */ sessionId, /** @type {string} */ workspacePath) {
+  return validEmptyCreateSnapshot(value, sessionId, workspacePath);
 }

tests/zcode-client.test.mjs

@@ -14,6 +14,7 @@ import { brokerEndpointFor, brokerIdentityNameForWireOptions, ensureZCodeBroker,
 import { atomicWriteJson, withFileLock } from '../scripts/lib/fs.mjs';
 import { PluginError } from '../scripts/lib/errors.mjs';
 import { resolveWorkspaceStorage } from '../scripts/lib/workspace.mjs';
+import { validCreateSnapshot, validSetupAuthProbeSnapshot, validSnapshot } from '../scripts/lib/zcode-schema.mjs';
 
 const fixture = fileURLToPath(new URL('./fixtures/fake-zcode-cli.mjs', import.meta.url));
 const brokerStartupFault = fileURLToPath(new URL('./fixtures/broker-startup-fault.cjs', import.meta.url));
@@ -236,6 +237,86 @@ test('typed operations use real 0.16.1 method and parameter shapes', async () =>
   });
 });
 
+test('ordinary session/create accepts the bounded 0.16.1 initial empty-session snapshot', async () => {
+  await withClient(async (client) => {
+    const created = await client.createSession({ workspace: '/repo' });
+    assert.equal(created.session.sessionId, 'session-1');
+    assert.equal(created.projection.sessionId, 'unknown');
+    assert.deepEqual(created.messages, []);
+  }, { FAKE_ZCODE_EMPTY_SESSION: '1' });
+});
+
+test('ordinary session/create rejects conflicting or non-empty unknown-projection snapshots', async (t) => {
+  for (const variant of ['conflict', 'non-idle', 'event-seq', 'messages', 'target']) await t.test(variant, () => withClient(async (client) => {
+    await assert.rejects(client.createSession({ workspace: '/repo' }), { code: 'ZCODE_OUTPUT_INVALID' });
+  }, { FAKE_ZCODE_EMPTY_SESSION: '1', FAKE_ZCODE_EMPTY_SESSION_VARIANT: variant }));
+});
+
+test('ordinary empty session/create retains explicit session ID binding', async () => {
+  await withClient(async (client) => {
+    await assert.rejects(client.createSession({ workspace: '/repo', sessionId: 'requested-session' }), { code: 'ZCODE_OUTPUT_INVALID' });
+  }, { FAKE_ZCODE_EMPTY_SESSION: '1', FAKE_ZCODE_SESSION_ID: 'different-session' });
+});
+
+test('the unknown-projection exception remains confined to session/create', async (t) => {
+  for (const method of ['session/read', 'session/resume', 'session/setModel', 'session/setThoughtLevel']) await t.test(method, () => withClient(async (client) => {
+    const sessionId = (await client.createSession({ workspace: '/repo' })).session.sessionId;
+    const operation = method === 'session/read' ? () => client.readSession(sessionId)
+      : method === 'session/resume' ? () => client.resumeSession(sessionId)
+        : method === 'session/setModel' ? () => client.setModel(sessionId, { providerId: 'fake2', modelId: 'other' })
+          : () => client.setThoughtLevel(sessionId, 'high');
+    await assert.rejects(operation(), { code: 'ZCODE_OUTPUT_INVALID' });
+  }, { FAKE_ZCODE_EMPTY_SESSION: '1' }));
+});
+
+test('the empty-create validator rejects every remaining non-empty or conflicting relation', async () => {
+  await withClient(async (client) => {
+    const empty = await client.createSession({ workspace: '/repo' });
+    const sessionId = empty.session.sessionId; const workspace = resolve('/repo');
+    assert.equal(validSnapshot(empty, sessionId, workspace), false, 'fixture must enter the empty-create branch');
+    const target = { sessionId, targetId: 'target-1', objective: 'not empty', summaryTitle: null, status: 'active', tokenBudget: null, tokensUsed: 0, timeUsedSeconds: 0, createdAt: 1, updatedAt: 1 };
+    const permission = { requestId: 'request-1', toolCallId: 'tool-1', toolName: 'write', reason: 'not empty', riskLevel: 'low', options: [{ optionId: 'allow', kind: 'allow', name: 'Allow', response: { decision: 'allow' } }], requestedAt: 1 };
+    const verification = { passed: false, reason: 'not empty' };
+    const cases = [
+      ['non-idle session status', (value) => { value.session.status = 'running'; }, true],
+      ['non-null session target', (value) => { value.session.target = target; }, true],
+      ['current projection turn', (value) => { value.projection.currentTurnId = 'turn-1'; }, true],
+      ['nonzero projection turn count', (value) => { value.projection.turnCount = 1; }, true],
+      ['nonzero projection token count', (value) => { value.projection.totalTokenCount = 1; }, true],
+      ['nonzero projection context use', (value) => { value.projection.contextUsed = 1; }, true],
+      ['pending projection permission', (value) => { value.projection.pendingPermissions = [permission]; }, true],
+      ['active projection tool call', (value) => { value.projection.activeToolCalls = [{ toolCallId: 'tool-1', toolName: 'write', status: 'pending' }]; }, true],
+      ['background projection job', (value) => { value.projection.backgroundJobs = [{}]; }, true],
+      ['projection error', (value) => { value.projection.lastError = { type: 'runtime', message: 'not empty' }; }, true],
+      ['nonzero runtime revision', (value) => { value.runtime.stateRevision = 1; }, true],
+      ['active runtime turn ID', (value) => { value.runtime.activeTurnId = 'turn-1'; }, true],
+      ['active runtime turn kind', (value) => { value.runtime.activeTurnKind = 'regular'; }, true],
+      ['pending runtime request', (value) => { value.runtime.pendingRequestIds = ['request-1']; }, true],
+      ['runtime API retry', (value) => { value.runtime.apiRetry = { kind: 'api_retry', attempt: 1, maxRetries: 2, retryDelayMs: 100, errorStatus: null, error: 'retrying' }; }, true],
+      ['runtime context usage', (value) => { value.runtime.contextUsage = { used: 1, size: 128000 }; }, true],
+      ['runtime goal verification', (value) => { value.runtime.goalVerifications = [verification]; }, true],
+      ['runtime goal verification timeline', (value) => { value.runtime.goalVerificationTimeline = [{ version: 1, kind: 'synthetic', type: 'goal_verification', display: 'separator', targetId: 'target-1', verificationId: 'verification-1', status: 'started' }]; }, true],
+      ['wrong workspace path', (value) => { value.session.workspace.workspacePath = '/wrong-workspace'; }, false],
+      ['wrong workspace key', (value) => { value.session.workspace.workspaceKey = '/wrong-workspace'; }, false],
+    ];
+    for (const [name, mutate, strictCompatible] of cases) {
+      const candidate = structuredClone(empty); mutate(candidate);
+      assert.equal(validSnapshot(candidate, sessionId, workspace), false, `${name}: strict branch must remain unavailable`);
+      assert.equal(validCreateSnapshot(candidate, sessionId, workspace), false, `${name}: empty-create branch must reject the mutation`);
+      assert.equal(validSetupAuthProbeSnapshot(candidate, sessionId, workspace), false, `${name}: setup probe must reject the mutation`);
+      if (strictCompatible) {
+        candidate.projection.sessionId = sessionId;
+        assert.equal(validSnapshot(candidate, sessionId, workspace), true, `${name}: mutation must otherwise retain a valid snapshot envelope`);
+      }
+    }
+    const explicitEmpty = structuredClone(empty);
+    explicitEmpty.session.target = null; explicitEmpty.projection.target = null; explicitEmpty.runtime.apiRetry = null;
+    explicitEmpty.runtime.goalVerifications = []; explicitEmpty.runtime.goalVerificationTimeline = [];
+    assert.equal(validCreateSnapshot(explicitEmpty, sessionId, workspace), true, 'explicit null and empty activity state must remain fresh');
+    assert.equal(validSetupAuthProbeSnapshot(explicitEmpty, sessionId, workspace), true, 'setup probe must accept explicit null and empty activity state');
+  }, { FAKE_ZCODE_EMPTY_SESSION: '1' });
+});
+
 test('session/create answers runtime preference requests with the exact string ID', async () => {
   await withClient(async (client, record) => {
     const created = await client.createSession({ workspace: '/repo' });