@dotdrelle/wiki-manager 0.11.10 → 0.12.1

package/src/contracts/schemas.js

@@ -3,6 +3,7 @@ const STATUS_VALUES = [
   'queued',
   'running',
   'waiting',
+  'waiting_approval',
   'pending_approval',
   'done',
   'failed',
@@ -18,6 +19,7 @@ const STATUS_VALUES = [
 
 const nullableString = { type: ['string', 'null'] };
 const nullableObject = { type: ['object', 'null'], additionalProperties: true };
+const stringArraySchema = { type: 'array', items: { type: 'string' } };
 const outputReferenceSchema = {
   $id: 'https://dotdrelle.dev/wiki-manager/contracts/output-reference/v1',
   title: 'OutputReference',
@@ -38,6 +40,241 @@ const outputReferenceSchema = {
   ],
 };
 
+const retryPolicySchema = {
+  $id: 'https://dotdrelle.dev/wiki-manager/contracts/retry-policy/v1',
+  title: 'RetryPolicy',
+  schemaVersion: '1',
+  type: 'object',
+  required: ['maxAttempts', 'retryableErrors', 'allowAgentFallback'],
+  additionalProperties: false,
+  properties: {
+    maxAttempts: { type: 'integer', minimum: 1 },
+    retryableErrors: stringArraySchema,
+    allowAgentFallback: { type: 'boolean' },
+  },
+};
+
+const jsonSchemaSchema = { type: 'object', additionalProperties: true };
+const capabilityDescriptionSchema = {
+  $id: 'https://dotdrelle.dev/wiki-manager/contracts/capability-description/v1',
+  title: 'CapabilityDescription',
+  schemaVersion: '1',
+  type: 'object',
+  required: ['id', 'version', 'description', 'inputSchema', 'outputSchema', 'supportedOperations'],
+  additionalProperties: true,
+  properties: {
+    id: { type: 'string', minLength: 1 },
+    version: { type: 'string', minLength: 1 },
+    description: { type: 'string' },
+    inputSchema: jsonSchemaSchema,
+    outputSchema: jsonSchemaSchema,
+    supportedOperations: stringArraySchema,
+    mutationClass: { type: 'string' },
+    defaultRequiresApproval: { type: 'boolean' },
+    estimatedCost: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        llmCalls: { type: 'number', minimum: 0 },
+        tokenRange: { type: 'array', items: { type: 'number' } },
+      },
+    },
+  },
+};
+
+const agentDescriptionSchema = {
+  $id: 'https://dotdrelle.dev/wiki-manager/contracts/agent-description/v1',
+  title: 'AgentDescription',
+  schemaVersion: '1',
+  type: 'object',
+  required: ['contractVersion', 'agentType', 'agentInstanceId', 'displayName', 'capabilities', 'orchestration', 'limits', 'health'],
+  additionalProperties: true,
+  properties: {
+    contractVersion: { type: 'string', minLength: 1 },
+    agentType: { type: 'string', minLength: 1 },
+    agentInstanceId: { type: 'string', minLength: 1 },
+    displayName: { type: 'string', minLength: 1 },
+    capabilities: { type: 'array', items: capabilityDescriptionSchema },
+    orchestration: {
+      type: 'object',
+      required: ['canPlan', 'canExpandPlan', 'canExecute', 'canCancel', 'canResume', 'supportsIdempotency', 'supportsParallelWorkers'],
+      additionalProperties: true,
+      properties: {
+        canPlan: { type: 'boolean' },
+        canExpandPlan: { type: 'boolean' },
+        canExecute: { type: 'boolean' },
+        canCancel: { type: 'boolean' },
+        canResume: { type: 'boolean' },
+        supportsIdempotency: { type: 'boolean' },
+        supportsParallelWorkers: { type: 'boolean' },
+      },
+    },
+    limits: {
+      type: 'object',
+      required: ['recommendedConcurrency', 'maxConcurrency'],
+      additionalProperties: true,
+      properties: {
+        recommendedConcurrency: { type: 'number', minimum: 0 },
+        maxConcurrency: { type: 'number', minimum: 0 },
+        maxTasksPerPlan: { type: 'number', minimum: 0 },
+        maxTaskDurationMs: { type: 'number', minimum: 0 },
+      },
+    },
+    health: {
+      type: 'object',
+      required: ['status'],
+      additionalProperties: false,
+      properties: {
+        status: { type: 'string', enum: ['available', 'degraded', 'unavailable'] },
+      },
+    },
+  },
+};
+
+const taskGroupSchema = {
+  $id: 'https://dotdrelle.dev/wiki-manager/contracts/task-group/v1',
+  title: 'TaskGroup',
+  schemaVersion: '1',
+  type: 'object',
+  required: ['id', 'label'],
+  additionalProperties: false,
+  properties: {
+    id: { type: 'string', minLength: 1 },
+    label: { type: 'string', minLength: 1 },
+    recommendedConcurrency: { type: 'integer', minimum: 1 },
+    progressWeight: { type: 'number', minimum: 0 },
+  },
+};
+
+const plannedTaskSchema = {
+  $id: 'https://dotdrelle.dev/wiki-manager/contracts/planned-task/v1',
+  title: 'PlannedTask',
+  schemaVersion: '1',
+  type: 'object',
+  required: [
+    'id',
+    'label',
+    'requiredCapability',
+    'operation',
+    'dependsOn',
+    'parallelizable',
+    'inputRefs',
+    'locks',
+    'requiresApproval',
+    'idempotencyKey',
+    'progressWeight',
+  ],
+  additionalProperties: false,
+  properties: {
+    id: { type: 'string', minLength: 1 },
+    label: { type: 'string', minLength: 1 },
+    requiredCapability: { type: 'string', minLength: 1 },
+    operation: { type: 'string', minLength: 1 },
+    arguments: { type: 'object', additionalProperties: true },
+    groupId: { type: 'string' },
+    dependsOn: stringArraySchema,
+    dependsOnGroup: { type: 'string' },
+    barrier: { type: 'boolean' },
+    parallelizable: { type: 'boolean' },
+    recommendedConcurrency: { type: 'integer', minimum: 1 },
+    inputRefs: { type: 'array', items: outputReferenceSchema },
+    expectedOutputRefs: { type: 'array', items: outputReferenceSchema },
+    locks: stringArraySchema,
+    requiresApproval: { type: 'boolean' },
+    approvalClass: { type: 'string' },
+    approvalSummary: { type: 'string' },
+    idempotencyKey: { type: ['string', 'null'] },
+    progressWeight: { type: 'number', minimum: 0 },
+    priority: { type: 'number' },
+    retryPolicy: retryPolicySchema,
+  },
+};
+
+const taskGraphFragmentSchema = {
+  $id: 'https://dotdrelle.dev/wiki-manager/contracts/task-graph-fragment/v1',
+  title: 'TaskGraphFragment',
+  schemaVersion: '1',
+  type: 'object',
+  required: ['contractVersion', 'agentInstanceId', 'capability', 'summary', 'groups', 'tasks'],
+  additionalProperties: false,
+  properties: {
+    contractVersion: { type: 'string', minLength: 1 },
+    agentInstanceId: { type: 'string', minLength: 1 },
+    capability: { type: 'string', minLength: 1 },
+    summary: {
+      type: 'object',
+      required: ['label', 'initialSynthesis', 'estimatedTasks'],
+      additionalProperties: false,
+      properties: {
+        label: { type: 'string', minLength: 1 },
+        initialSynthesis: stringArraySchema,
+        estimatedTasks: { type: 'integer', minimum: 0 },
+      },
+    },
+    groups: { type: 'array', items: taskGroupSchema },
+    tasks: { type: 'array', items: plannedTaskSchema },
+    expectedOutputs: { type: 'array', items: outputReferenceSchema },
+  },
+};
+
+const planExpansionRequestSchema = {
+  $id: 'https://dotdrelle.dev/wiki-manager/contracts/plan-expansion-request/v1',
+  title: 'PlanExpansionRequest',
+  schemaVersion: '1',
+  type: 'object',
+  required: ['capability'],
+  additionalProperties: true,
+  properties: {
+    capability: { type: 'string', minLength: 1 },
+    operation: nullableString,
+    objective: nullableString,
+    reason: nullableString,
+    arguments: { type: 'object', additionalProperties: true },
+    workspace: { type: 'object', additionalProperties: true },
+    constraints: {
+      type: 'object',
+      additionalProperties: true,
+      properties: {
+        maxTasks: { type: 'integer', minimum: 1 },
+        maxConcurrency: { type: 'integer', minimum: 1 },
+        maxDepth: { type: 'integer', minimum: 1 },
+        requireApprovalForMutations: { type: 'boolean' },
+      },
+    },
+    insertBeforeTasks: stringArraySchema,
+    insertAfterTasks: stringArraySchema,
+  },
+};
+
+// Shared by planStepSchema and patchTaskSchema, which differ only in their
+// `id`/`description` requiredness — every other field is identical.
+const taskFieldsSchema = {
+  label: { type: 'string' },
+  requiredCapability: { type: ['string', 'null'] },
+  operation: { type: ['string', 'null'] },
+  arguments: { type: 'object', additionalProperties: true },
+  groupId: nullableString,
+  status: { type: 'string' },
+  dependsOn: { type: 'array', items: { type: 'string' } },
+  dependsOnGroup: nullableString,
+  barrier: { type: 'boolean' },
+  parallelizable: { type: 'boolean' },
+  recommendedConcurrency: { type: 'integer', minimum: 1 },
+  executor: nullableString,
+  executorQuery: nullableObject,
+  inputRefs: { type: 'array', items: outputReferenceSchema },
+  expectedOutputRefs: { type: 'array', items: outputReferenceSchema },
+  locks: stringArraySchema,
+  requiresApproval: { type: 'boolean' },
+  approvalClass: nullableString,
+  approvalSummary: nullableString,
+  idempotencyKey: { type: ['string', 'null'] },
+  progressWeight: { type: 'number', minimum: 0 },
+  priority: { type: 'number' },
+  retryPolicy: retryPolicySchema,
+  outputRefs: { type: 'array', items: outputReferenceSchema },
+};
+
 const planStepSchema = {
   type: 'object',
   required: ['description', 'status', 'dependsOn', 'outputRefs'],
@@ -46,11 +283,7 @@ const planStepSchema = {
     step: { type: 'number' },
     id: nullableString,
     description: { type: 'string' },
-    status: { type: 'string' },
-    dependsOn: { type: 'array', items: { type: 'string' } },
-    executor: nullableString,
-    executorQuery: nullableObject,
-    outputRefs: { type: 'array', items: outputReferenceSchema },
+    ...taskFieldsSchema,
   },
 };
 
@@ -61,11 +294,7 @@ const patchTaskSchema = {
   properties: {
     id: { type: 'string' },
     description: { type: 'string' },
-    status: { type: 'string' },
-    dependsOn: { type: 'array', items: { type: 'string' } },
-    executor: nullableString,
-    executorQuery: nullableObject,
-    outputRefs: { type: 'array', items: outputReferenceSchema },
+    ...taskFieldsSchema,
   },
 };
 
@@ -145,7 +374,7 @@ export const contractSchemas = {
       message: { type: 'string' },
       prompt: { type: 'string' },
       request: { type: 'string' },
-      intent: { type: 'string', enum: ['observe', 'converse', 'mutate', 'enqueue'] },
+      intent: { type: 'string', enum: ['observe', 'converse', 'mutate', 'enqueue', 'approve', 'modify_run', 'enqueue_run', 'cancel', 'ambiguous'] },
       workspace: nullableString,
       patchId: { type: 'string' },
       id: { type: 'string' },
@@ -157,7 +386,7 @@ export const contractSchemas = {
     title: 'StructuredPlan',
     schemaVersion: '1',
     type: 'array',
-    items: planStepSchema,
+    items: { anyOf: [planStepSchema, plannedTaskSchema] },
   },
   planPatch: {
     $id: 'https://dotdrelle.dev/wiki-manager/contracts/plan-patch/v1',
@@ -179,7 +408,7 @@ export const contractSchemas = {
           additionalProperties: true,
           properties: {
             op: { type: 'string', enum: ['add_task', 'add_dependency', 'remove_dependency', 'cancel_task', 'replace_executor', 'request_approval'] },
-            task: patchTaskSchema,
+            task: { anyOf: [patchTaskSchema, plannedTaskSchema] },
             taskId: { type: 'string' },
             targetTaskId: { type: 'string' },
             dependencyId: { type: 'string' },
@@ -193,6 +422,13 @@ export const contractSchemas = {
     },
   },
   outputReference: outputReferenceSchema,
+  capabilityDescription: capabilityDescriptionSchema,
+  agentDescription: agentDescriptionSchema,
+  retryPolicy: retryPolicySchema,
+  taskGroup: taskGroupSchema,
+  plannedTask: plannedTaskSchema,
+  taskGraphFragment: taskGraphFragmentSchema,
+  planExpansionRequest: planExpansionRequestSchema,
 };
 
 export function validateContract(name, value) {

package/src/contracts/schemas.test.js

@@ -50,7 +50,7 @@ test('agent event contract carries the unified audit identity fields', () => {
     runId: 'run-1',
     turnId: 'turn-1',
     taskId: 'task-1',
-    workspace: 'juno',
+    workspace: 'acme',
     payload: { toolCallId: 'call-1', ok: true },
   };
 
@@ -58,7 +58,7 @@ test('agent event contract carries the unified audit identity fields', () => {
 });
 
 test('run and control request contracts reject empty run input but accept explicit controls', () => {
-  assert.equal(validateContract('runRequest', { input: 'Build docs', workspace: 'juno' }).ok, true);
+  assert.equal(validateContract('runRequest', { input: 'Build docs', workspace: 'acme' }).ok, true);
   assert.equal(validateContract('runRequest', { input: '' }).ok, false);
   assert.equal(validateContract('controlMessage', { action: 'message', input: 'Ou en est le build ?', intent: 'observe' }).ok, true);
 });
@@ -91,3 +91,148 @@ test('plan and patch contracts cover structured dependencies and output refs', (
   assert.equal(validateContract('plan', plan).ok, true);
   assert.equal(validateContract('planPatch', patch).ok, true);
 });
+
+test('task graph fragment contract carries planned tasks and groups round-trip', () => {
+  const fragment = {
+    contractVersion: '1',
+    agentInstanceId: 'production-main',
+    capability: 'knowledge.update',
+    summary: {
+      label: 'Update knowledge',
+      initialSynthesis: ['Two files will be ingested.'],
+      estimatedTasks: 1,
+    },
+    groups: [{
+      id: 'ingest',
+      label: 'Ingest sources',
+      recommendedConcurrency: 2,
+      progressWeight: 2,
+    }],
+    tasks: [{
+      id: 'ingest-a',
+      label: 'Ingest source A',
+      requiredCapability: 'knowledge.update',
+      operation: 'ingest',
+      arguments: { files: ['raw/untracked/a.md'] },
+      groupId: 'ingest',
+      dependsOn: [],
+      parallelizable: true,
+      recommendedConcurrency: 2,
+      inputRefs: [{ type: 'file', ref: 'raw/untracked/a.md', label: 'A' }],
+      expectedOutputRefs: ['wiki/a.md'],
+      locks: ['workspace:wiki'],
+      requiresApproval: false,
+      idempotencyKey: null,
+      progressWeight: 1,
+      priority: 10,
+      retryPolicy: {
+        maxAttempts: 2,
+        retryableErrors: ['timeout'],
+        allowAgentFallback: false,
+      },
+    }],
+    expectedOutputs: ['wiki/a.md'],
+  };
+
+  const roundTrip = JSON.parse(JSON.stringify(fragment));
+  assert.deepEqual(roundTrip, fragment);
+  assert.equal(validateContract('taskGraphFragment', roundTrip).ok, true);
+  assert.equal(validateContract('plannedTask', roundTrip.tasks[0]).ok, true);
+  assert.equal(validateContract('taskGroup', roundTrip.groups[0]).ok, true);
+  assert.equal(validateContract('retryPolicy', roundTrip.tasks[0].retryPolicy).ok, true);
+});
+
+test('strict planned task contract rejects invalid fields and types', () => {
+  const invalid = {
+    id: 'bad',
+    label: 'Bad task',
+    requiredCapability: 'knowledge.update',
+    operation: 'ingest',
+    dependsOn: [],
+    parallelizable: false,
+    inputRefs: [],
+    locks: [],
+    requiresApproval: false,
+    idempotencyKey: null,
+    progressWeight: 1,
+    executor: 'legacy-tool',
+  };
+
+  const result = validateContract('plannedTask', invalid);
+  assert.equal(result.ok, false);
+  assert.ok(result.errors.some((error) => error.includes('executor is not allowed')));
+  assert.throws(() => assertContract('plannedTask', invalid), /executor is not allowed/);
+});
+
+test('plan and plan patch contracts accept new planned task fields without rejecting legacy tasks', () => {
+  const plannedTask = {
+    id: 'publish',
+    label: 'Publish deliverable',
+    requiredCapability: 'document.publish',
+    operation: 'publish',
+    arguments: { target: 'deliverables/report.md' },
+    dependsOn: ['build'],
+    parallelizable: false,
+    inputRefs: ['deliverables/report.md'],
+    locks: ['deliverable:report.md'],
+    requiresApproval: true,
+    approvalClass: 'mutation',
+    approvalSummary: 'Publish report',
+    idempotencyKey: 'idem-1',
+    progressWeight: 1,
+  };
+  const legacyTask = {
+    step: 1,
+    id: 'build',
+    description: 'Build report',
+    status: 'done',
+    dependsOn: [],
+    outputRefs: ['deliverables/report.md'],
+  };
+
+  assert.equal(validateContract('plan', [legacyTask, plannedTask]).ok, true);
+  assert.equal(validateContract('planPatch', {
+    basePlanRevision: 1,
+    operations: [{ op: 'add_task', task: plannedTask }],
+  }).ok, true);
+});
+
+test('agent description contract validates orchestrable agent capabilities', () => {
+  const description = {
+    contractVersion: '1',
+    agentType: 'production',
+    agentInstanceId: 'production-main',
+    displayName: 'Production',
+    capabilities: [{
+      id: 'knowledge.update',
+      version: '1',
+      description: 'Update wiki knowledge',
+      inputSchema: { type: 'object' },
+      outputSchema: { type: 'object' },
+      supportedOperations: ['ingest', 'pipeline'],
+      mutationClass: 'workspace',
+      defaultRequiresApproval: true,
+      estimatedCost: { llmCalls: 2, tokenRange: [1000, 3000] },
+    }],
+    orchestration: {
+      canPlan: true,
+      canExpandPlan: false,
+      canExecute: true,
+      canCancel: true,
+      canResume: false,
+      supportsIdempotency: false,
+      supportsParallelWorkers: true,
+    },
+    limits: {
+      recommendedConcurrency: 2,
+      maxConcurrency: 4,
+      maxTasksPerPlan: 50,
+      maxTaskDurationMs: 600000,
+    },
+    health: { status: 'available' },
+  };
+
+  assert.equal(validateContract('agentDescription', description).ok, true);
+  assert.equal(validateContract('capabilityDescription', description.capabilities[0]).ok, true);
+  assert.equal(validateContract('agentDescription', { ...description, health: { status: 'offline' } }).ok, false);
+});

package/src/core/activity.js

@@ -100,11 +100,12 @@ export function normalizeActivity(activity, fallback = {}) {
   return normalized;
 }
 
-function productionActivityFromPayload(payload) {
+function productionActivityFromPayload(payload, context = {}) {
   const progress = payload?.progress;
   const job = payload?.job;
   const jobId = payload?.jobId ?? job?.jobId;
   if (!progress && !job && !jobId) return null;
+  const result = payload?.result && typeof payload.result === 'object' ? payload.result : null;
   const status = job?.status ?? payload?.status ?? progress?.status ?? 'running';
   const percent = Number.isFinite(Number(progress?.percent)) ? Number(progress.percent) : null;
   const sourceCount = Number(progress?.sourceCount);
@@ -139,21 +140,23 @@ function productionActivityFromPayload(payload) {
   return normalizeActivity({
     id: jobId,
     source: 'production',
-    kind: job?.type ?? payload?.type ?? progress?.phase ?? progress?.currentStep ?? 'job',
+    kind: job?.type ?? payload?.operation ?? payload?.type ?? progress?.phase ?? progress?.currentStep ?? 'job',
     label: detail ? `Production: ${detail}` : `Production: ${status}`,
     status,
     progress: {
       ...(progress ?? {}),
       ...(percent !== null ? { percent } : {}),
       step,
+      ...(payload?.taskId ? { stepId: String(payload.taskId) } : {}),
     },
     poll: jobId ? {
       server: 'production',
-      tool: 'production_job_status',
+      tool: context.tool === 'agent_status' ? 'agent_status' : 'production_job_status',
       args: { jobId },
       intervalMs: 2500,
     } : null,
-    error: job?.error ?? payload?.error ?? null,
+    outputRefs: Array.isArray(result?.outputRefs) ? result.outputRefs : [],
+    error: job?.error ?? result?.error?.message ?? payload?.error ?? null,
   });
 }
 
@@ -163,7 +166,7 @@ export function extractActivity(payload, context = {}) {
     return normalizeActivity(payload._activity, { source: context.server });
   }
   if (context.server === 'production') {
-    return productionActivityFromPayload(payload);
+    return productionActivityFromPayload(payload, context);
   }
   return null;
 }