wip: first run of implementation

tests/engine/agentic/capabilities/registry.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest';
+import { CapabilityRegistryService } from '../../../../src/main/agentic/capabilities/registry';
+
+describe('CapabilityRegistryService', () => {
+  it('returns per-surface capability differences', () => {
+    const registry = new CapabilityRegistryService();
+
+    const tabCapabilities = registry.getSnapshot({ surface: 'tab' });
+    const sidebarCapabilities = registry.getSnapshot({ surface: 'sidebar' });
+
+    expect(tabCapabilities.widgets).toContain('tabs');
+    expect(sidebarCapabilities.widgets).toContain('tabs');
+    expect(tabCapabilities.actions).toContain('toggleSidebar');
+    expect(sidebarCapabilities.actions).toContain('toggleAssistantSidebar');
+    expect(tabCapabilities.actions).not.toContain('toggleAssistantSidebar');
+  });
+
+  it('omits disabled capabilities from active lists', () => {
+    const registry = new CapabilityRegistryService({
+      disabledActions: ['openSettings'],
+      disabledWidgets: ['chart'],
+      disabledTools: ['view_image'],
+    });
+
+    const snapshot = registry.getSnapshot({ surface: 'tab' });
+
+    expect(snapshot.actions).not.toContain('openSettings');
+    expect(snapshot.widgets).not.toContain('chart');
+    expect(snapshot.tools).not.toContain('view_image');
+    expect(snapshot.disabled).toEqual(expect.arrayContaining(['action:openSettings', 'widget:chart', 'tool:view_image']));
+  });
+});

tests/engine/agentic/observability/protocolTelemetry.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'vitest';
+import { ProtocolTelemetryService } from '../../../../src/main/agentic/observability/protocolTelemetry';
+
+describe('ProtocolTelemetryService', () => {
+  it('tracks parse validity, repairs, fallback, and blocked actions', () => {
+    const telemetry = new ProtocolTelemetryService();
+
+    telemetry.recordTurn({
+      validEnvelope: true,
+      repairAttempted: false,
+      fallbackUsed: false,
+      blockedActions: 0,
+    });
+
+    telemetry.recordTurn({
+      validEnvelope: true,
+      repairAttempted: true,
+      fallbackUsed: false,
+      blockedActions: 1,
+    });
+
+    telemetry.recordTurn({
+      validEnvelope: false,
+      repairAttempted: true,
+      fallbackUsed: true,
+      blockedActions: 2,
+    });
+
+    const snapshot = telemetry.getSnapshot();
+
+    expect(snapshot.totalTurns).toBe(3);
+    expect(snapshot.validEnvelopeTurns).toBe(2);
+    expect(snapshot.repairAttempts).toBe(2);
+    expect(snapshot.fallbackTurns).toBe(1);
+    expect(snapshot.blockedActionCount).toBe(3);
+    expect(snapshot.parseValidityRate).toBeCloseTo(2 / 3, 5);
+  });
+});

tests/engine/agentic/policy/actionPolicy.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+import { resolveActionPolicy } from '../../../../src/main/agentic/policy/actionPolicy';
+
+describe('action policy', () => {
+  it('marks dangerous actions as requiring explicit confirmation', () => {
+    const policy = resolveActionPolicy('deletePost');
+    expect(policy.level).toBe('danger');
+    expect(policy.requiresConfirmation).toBe(true);
+  });
+
+  it('marks configurable but safe navigation actions as confirm', () => {
+    const policy = resolveActionPolicy('openSettings');
+    expect(policy.level).toBe('confirm');
+    expect(policy.requiresConfirmation).toBe(true);
+  });
+
+  it('defaults unknown actions to danger', () => {
+    const policy = resolveActionPolicy('unknownAction');
+    expect(policy.level).toBe('danger');
+  });
+});

tests/engine/agentic/protocol/responseBuilder.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, it } from 'vitest';
+import { ProtocolResponseBuilder } from '../../../../src/main/agentic/protocol/responseBuilder';
+
+describe('ProtocolResponseBuilder', () => {
+  it('builds canonical envelope from mixed text + AGUI payload', () => {
+    const builder = new ProtocolResponseBuilder();
+
+    const raw = [
+      'I found weak months.',
+      '```json',
+      '{"specVersion":"1","elements":[{"type":"chart","chartType":"bar","series":[{"label":"Jan","value":10}]}]}',
+      '```',
+    ].join('\n');
+
+    const result = builder.build({
+      rawAssistantOutput: raw,
+      surface: 'tab',
+      capabilities: {
+        widgets: ['chart'],
+        actions: ['openPost'],
+        tools: ['search_posts'],
+      },
+    });
+
+    expect(result.envelope.ui?.elements).toHaveLength(1);
+    expect(result.envelope.assistantText).toContain('I found weak months');
+    expect(result.envelope.protocolVersion).toBe('2.0');
+    expect(result.repairAttempted).toBe(false);
+  });
+
+  it('repairs non-canonical envelope keys and validates output', () => {
+    const builder = new ProtocolResponseBuilder();
+
+    const raw = JSON.stringify({
+      protocol_version: '2.0',
+      assistant_text: 'Need more details',
+      intent: 'ask_input',
+      needs_input: {
+        required: true,
+        fields: [{ key: 'date', label: 'Date', inputType: 'date' }],
+      },
+      actions: [],
+      confidence: 0.8,
+      trace_id: 'trace-manual',
+    });
+
+    const result = builder.build({
+      rawAssistantOutput: raw,
+      surface: 'sidebar',
+      capabilities: {
+        widgets: ['form'],
+        actions: ['openPost'],
+        tools: ['search_posts'],
+      },
+    });
+
+    expect(result.repairAttempted).toBe(true);
+    expect(result.envelope.assistantText).toBe('Need more details');
+    expect(result.envelope.needsInput.required).toBe(true);
+    expect(result.envelope.needsInput.fields).toHaveLength(1);
+    expect(result.validationError).toBeUndefined();
+  });
+
+  it('falls back to safe summarize envelope when payload is invalid', () => {
+    const builder = new ProtocolResponseBuilder();
+
+    const raw = '{"specVersion":"9","elements":[]}';
+
+    const result = builder.build({
+      rawAssistantOutput: raw,
+      surface: 'tab',
+      capabilities: {
+        widgets: ['chart'],
+        actions: ['openPost'],
+        tools: ['search_posts'],
+      },
+    });
+
+    expect(result.envelope.intent).toBe('summarize');
+    expect(result.envelope.ui).toBeUndefined();
+    expect(result.envelope.assistantText).toContain('specVersion');
+    expect(result.traceId.length).toBeGreaterThan(0);
+  });
+
+  it('blocks actions that are unavailable for the active surface capabilities', () => {
+    const builder = new ProtocolResponseBuilder();
+
+    const raw = JSON.stringify({
+      protocolVersion: '2.0',
+      assistantText: 'Open settings?',
+      intent: 'propose_action',
+      needsInput: { required: false, fields: [] },
+      actions: [{
+        id: 'a1',
+        action: 'openSettings',
+        label: 'Open Settings',
+        policy: 'confirm',
+        requiresConfirmation: true,
+      }],
+      confidence: 0.7,
+      traceId: 'trace-abc',
+    });
+
+    const result = builder.build({
+      rawAssistantOutput: raw,
+      surface: 'tab',
+      capabilities: {
+        widgets: ['chart'],
+        actions: ['openPost'],
+        tools: ['search_posts'],
+      },
+    });
+
+    expect(result.envelope.actions).toHaveLength(0);
+    expect(result.warnings.some((warning) => warning.includes('openSettings'))).toBe(true);
+  });
+});

tests/engine/agentic/protocol/validator.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it } from 'vitest';
+import {
+  validateProtocolRequestEnvelope,
+  validateProtocolResponseEnvelope,
+  type ProtocolResponseEnvelope,
+} from '../../../../src/main/agentic/protocol/validator';
+
+describe('agentic protocol validator', () => {
+  it('validates canonical response envelope', () => {
+    const envelope: ProtocolResponseEnvelope = {
+      protocolVersion: '2.0',
+      assistantText: 'Done',
+      intent: 'summarize',
+      needsInput: {
+        required: false,
+        fields: [],
+      },
+      actions: [],
+      confidence: 0.82,
+      traceId: 'trace-abc',
+    };
+
+    const result = validateProtocolResponseEnvelope(envelope);
+    expect(result.ok).toBe(true);
+    expect(result.error).toBeUndefined();
+  });
+
+  it('rejects response envelope with unknown properties in strict mode', () => {
+    const result = validateProtocolResponseEnvelope({
+      protocolVersion: '2.0',
+      assistantText: 'Done',
+      intent: 'summarize',
+      needsInput: { required: false, fields: [] },
+      actions: [],
+      confidence: 0.8,
+      traceId: 'trace-abc',
+      extra: 'nope',
+    });
+
+    expect(result.ok).toBe(false);
+    expect(result.error?.code).toBe('AGUI_PROTOCOL_VALIDATION_ERROR');
+  });
+
+  it('rejects needsInput.required=true without fields', () => {
+    const result = validateProtocolResponseEnvelope({
+      protocolVersion: '2.0',
+      assistantText: 'Need details',
+      intent: 'ask_input',
+      needsInput: { required: true, fields: [] },
+      actions: [],
+      confidence: 0.9,
+      traceId: 'trace-xyz',
+    });
+
+    expect(result.ok).toBe(false);
+    expect(result.error?.message).toContain('needsInput.fields');
+  });
+
+  it('validates canonical request envelope with capabilities', () => {
+    const result = validateProtocolRequestEnvelope({
+      protocolVersion: '2.0',
+      surface: 'tab',
+      messages: [{ role: 'user', content: 'Create a chart' }],
+      context: { projectId: 'project-1' },
+      capabilities: {
+        widgets: ['chart', 'form'],
+        actions: ['openPost'],
+        tools: ['search_posts'],
+      },
+    });
+
+    expect(result.ok).toBe(true);
+  });
+});

tests/engine/agentic/workflow/checkpointStore.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from 'vitest';
+import {
+  WorkflowCheckpointStore,
+  type WorkflowCheckpointSettingsAdapter,
+} from '../../../../src/main/agentic/workflow/checkpointStore';
+
+class InMemorySettingsAdapter implements WorkflowCheckpointSettingsAdapter {
+  private readonly store = new Map<string, string>();
+
+  async getSetting(key: string): Promise<string | null> {
+    return this.store.get(key) ?? null;
+  }
+
+  async setSetting(key: string, value: string): Promise<void> {
+    this.store.set(key, value);
+  }
+}
+
+describe('WorkflowCheckpointStore', () => {
+  it('persists and reloads workflow checkpoints by conversation id', async () => {
+    const adapter = new InMemorySettingsAdapter();
+    const store = new WorkflowCheckpointStore(adapter);
+
+    await store.save({
+      conversationId: 'conversation-1',
+      state: 'awaiting_input',
+      pendingFields: ['date'],
+      lastTraceId: 'trace-1',
+      updatedAt: new Date('2026-02-25T10:00:00.000Z').toISOString(),
+    });
+
+    const loaded = await store.load('conversation-1');
+
+    expect(loaded).not.toBeNull();
+    expect(loaded?.state).toBe('awaiting_input');
+    expect(loaded?.pendingFields).toEqual(['date']);
+    expect(loaded?.lastTraceId).toBe('trace-1');
+  });
+});

tests/engine/agentic/workflow/stateMachine.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'vitest';
+import { AgentTurnStateMachine } from '../../../../src/main/agentic/workflow/turnStateMachine';
+
+describe('AgentTurnStateMachine', () => {
+  it('transitions to awaiting_input when envelope requests required input', () => {
+    const stateMachine = new AgentTurnStateMachine();
+
+    const next = stateMachine.transition({
+      previousState: 'planning',
+      envelope: {
+        intent: 'ask_input',
+        needsInput: {
+          required: true,
+          fields: [{ key: 'date', label: 'Date', inputType: 'date' }],
+        },
+      },
+    });
+
+    expect(next).toBe('awaiting_input');
+  });
+
+  it('transitions to completed when summarize intent has no required input', () => {
+    const stateMachine = new AgentTurnStateMachine();
+
+    const next = stateMachine.transition({
+      previousState: 'observing',
+      envelope: {
+        intent: 'summarize',
+        needsInput: {
+          required: false,
+          fields: [],
+        },
+      },
+    });
+
+    expect(next).toBe('completed');
+  });
+});