feat(ql3): add fenced copilot diagnosis cancellation

packages/ql3-cluster-control/test/aiProductionApplication.test.cjs

@@ -169,9 +169,11 @@ test('Copilot composition is explicit, shares the Prompt gateway and injects one
   const artifactStore = { put() {}, inspect() {}, readLogRange() {} };
   const copilot = Object.freeze({ execute() {} });
   const copilotRead = Object.freeze({ inspect() {}, readOutput() {} });
+  const copilotCancellation = Object.freeze({ cancel() {} });
   let registeredSink;
   let created;
   let createdRead;
+  let createdCancellation;
   let controlOptions;
   try {
     await Promise.all([
@@ -233,6 +235,10 @@ test('Copilot composition is explicit, shares the Prompt gateway and injects one
         createdRead = options;
         return copilotRead;
       },
+      createCopilotCancellation(options) {
+        createdCancellation = options;
+        return copilotCancellation;
+      },
       async startControl(options) {
         controlOptions = options;
         return {
@@ -257,11 +263,16 @@ test('Copilot composition is explicit, shares the Prompt gateway and injects one
     assert.equal(created.artifactStore, artifactStore);
     assert.equal(createdRead.pool, fakePool);
     assert.equal(typeof createdRead.prepared.outputKeys.resolve, 'function');
+    assert.equal(createdCancellation.pool, fakePool);
     assert.equal(controlOptions.copilotFailureDiagnosis.capability, copilot);
     assert.equal(
       controlOptions.copilotFailureDiagnosis.readCapability,
       copilotRead,
     );
+    assert.equal(
+      controlOptions.copilotFailureDiagnosis.cancellationCapability,
+      copilotCancellation,
+    );
     assert.equal(await application.stop(), 'stopped');
   } finally {
     config.fill(0);

packages/ql3-cluster-control/test/copilotFailureDiagnosisCancellationRoute.test.cjs

@@ -0,0 +1,232 @@
+const assert = require('node:assert/strict');
+const { test } = require('node:test');
+
+const {
+  CopilotFailureDiagnosisCancellationNotFoundError,
+} = require('@qinglong/ai/failure-diagnosis-cancellation');
+const {
+  CLUSTER_RUN_CANCELLATION_SCHEMA,
+  ClusterRunCancellationFenceRejectedError,
+} = require('@qinglong/runtime-core/cluster-run-cancellation');
+const {
+  CLUSTER_COPILOT_FAILURE_DIAGNOSIS_CANCELLATION_RESPONSE_SCHEMA,
+  CLUSTER_CONTROL_COPILOT_FAILURE_DIAGNOSIS_CANCELLATION_ROUTE,
+  createClusterControlCopilotFailureDiagnosisCancellationRoute,
+} = require('@qinglong/cluster-control/copilot-cancellation-route');
+
+function authorized(body, overrides = {}) {
+  return {
+    request: {
+      requestId: 'transport-request-1',
+      method: 'POST',
+      path: '/api/v3/projects/project-1/runs/source-run-1/copilot/failure-diagnoses/diagnosis-request-1/cancellation',
+      query: {},
+      headers: {},
+      signal: new AbortController().signal,
+      body,
+    },
+    principal: {
+      subject: { type: 'user', id: 'owner-1' },
+      authenticationId: 'credential-1',
+      authenticatedAtMs: 1,
+      expiresAtMs: 10_000,
+      assurance: 'multi_factor',
+    },
+    operationId: 'copilot.failure_diagnosis.cancel',
+    permission: 'run.stop',
+    projectId: 'project-1',
+    policyFence: { projectVersion: 3, bindingVersion: 7 },
+    ...overrides,
+  };
+}
+
+const parameters = {
+  projectId: 'project-1',
+  runId: 'source-run-1',
+  requestId: 'diagnosis-request-1',
+};
+
+function body(overrides = {}) {
+  return {
+    schema: CLUSTER_RUN_CANCELLATION_SCHEMA,
+    mutationId: '11111111-1111-4111-8111-111111111111',
+    ...overrides,
+  };
+}
+
+function result(overrides = {}) {
+  return {
+    schema: 'qinglong/copilot-failure-diagnosis-cancellation-result@v1',
+    status: 'accepted',
+    convergence: 'terminal',
+    projectId: 'project-1',
+    sourceRunId: 'source-run-1',
+    requestId: 'diagnosis-request-1',
+    diagnosisRunId: 'diagnosis-run-1',
+    runStatus: 'cancelled',
+    outcome: 'cancelled',
+    runVersion: 7,
+    eventSequence: 7,
+    cancelRequestedAtMs: 500,
+    cancelReason: 'user',
+    ...overrides,
+  };
+}
+
+test('defines an exact run.stop route and passes only fenced target facts', async () => {
+  let command;
+  const request = authorized(body());
+  const route = createClusterControlCopilotFailureDiagnosisCancellationRoute(
+    {
+      async cancel(value) {
+        command = value;
+        return result();
+      },
+    },
+    () => '22222222-2222-4222-8222-222222222222',
+  );
+  const response = await route.handle(request, parameters);
+  assert.deepEqual(
+    CLUSTER_CONTROL_COPILOT_FAILURE_DIAGNOSIS_CANCELLATION_ROUTE,
+    {
+      method: 'POST',
+      path: '/api/v3/projects/{projectId}/runs/{runId}/copilot/failure-diagnoses/{requestId}/cancellation',
+      operationId: 'copilot.failure_diagnosis.cancel',
+      permission: 'run.stop',
+      projectParameter: 'projectId',
+    },
+  );
+  assert.deepEqual(command, {
+    projectId: 'project-1',
+    sourceRunId: 'source-run-1',
+    requestId: 'diagnosis-request-1',
+    mutationId: '11111111-1111-4111-8111-111111111111',
+    eventId: '22222222-2222-4222-8222-222222222222',
+    subject: request.principal.subject,
+    policyFence: request.policyFence,
+  });
+  assert.deepEqual(response, {
+    statusCode: 202,
+    body: {
+      schema: CLUSTER_COPILOT_FAILURE_DIAGNOSIS_CANCELLATION_RESPONSE_SCHEMA,
+      status: 'accepted',
+      convergence: 'terminal',
+      projectId: 'project-1',
+      sourceRunId: 'source-run-1',
+      requestId: 'diagnosis-request-1',
+      diagnosisRunId: 'diagnosis-run-1',
+      runStatus: 'cancelled',
+      outcome: 'cancelled',
+      runVersion: 7,
+      eventSequence: 7,
+      cancelRequestedAtMs: 500,
+      cancelReason: 'user',
+    },
+  });
+});
+
+test('projects an in-flight durable intent without claiming Provider abort', async () => {
+  const route = createClusterControlCopilotFailureDiagnosisCancellationRoute(
+    {
+      async cancel() {
+        return result({
+          status: 'already_requested',
+          convergence: 'model_in_flight',
+          runStatus: 'running',
+          outcome: null,
+          runVersion: 6,
+          eventSequence: 6,
+        });
+      },
+    },
+    () => '22222222-2222-4222-8222-222222222222',
+  );
+  const response = await route.handle(authorized(body()), parameters);
+  assert.equal(response.statusCode, 200);
+  assert.equal(response.body.convergence, 'model_in_flight');
+  assert.equal(response.body.runStatus, 'running');
+  assert.equal(response.body.outcome, null);
+  assert.equal('providerAborted' in response.body, false);
+});
+
+test('rejects non-exact bodies before invoking the capability', async () => {
+  let calls = 0;
+  const route = createClusterControlCopilotFailureDiagnosisCancellationRoute(
+    {
+      async cancel() {
+        calls += 1;
+        return result();
+      },
+    },
+    () => '22222222-2222-4222-8222-222222222222',
+  );
+  for (const value of [
+    null,
+    {},
+    body({ runId: 'caller-selected' }),
+    body({ reason: 'timeout' }),
+    body({ mutationId: '' }),
+  ]) {
+    const response = await route.handle(authorized(value), parameters);
+    assert.equal(response.statusCode, 400);
+  }
+  assert.equal(calls, 0);
+});
+
+test('fails closed on widened or identity-drifted capability results', async () => {
+  for (const value of [
+    result({ sourceRunId: 'other' }),
+    result({ privateProvider: 'must-not-cross' }),
+    result({ runVersion: 8 }),
+    result({ convergence: 'model_in_flight' }),
+  ]) {
+    const route = createClusterControlCopilotFailureDiagnosisCancellationRoute(
+      {
+        async cancel() {
+          return value;
+        },
+      },
+      () => '22222222-2222-4222-8222-222222222222',
+    );
+    const response = await route.handle(authorized(body()), parameters);
+    assert.deepEqual(response, {
+      statusCode: 503,
+      body: {
+        code: 'copilot_failure_diagnosis_cancellation_unavailable',
+      },
+    });
+  }
+});
+
+test('maps hidden targets, Policy races and storage failures to stable codes', async () => {
+  for (const [error, statusCode, code] of [
+    [
+      new CopilotFailureDiagnosisCancellationNotFoundError(),
+      404,
+      'copilot_failure_diagnosis_not_found',
+    ],
+    [
+      new ClusterRunCancellationFenceRejectedError('authorization_changed'),
+      409,
+      'copilot_failure_diagnosis_cancellation_fence_rejected',
+    ],
+    [
+      new Error('private storage detail'),
+      503,
+      'copilot_failure_diagnosis_cancellation_unavailable',
+    ],
+  ]) {
+    const route = createClusterControlCopilotFailureDiagnosisCancellationRoute(
+      {
+        async cancel() {
+          throw error;
+        },
+      },
+      () => '22222222-2222-4222-8222-222222222222',
+    );
+    const response = await route.handle(authorized(body()), parameters);
+    assert.equal(response.statusCode, statusCode);
+    assert.equal(response.body.code, code);
+    assert.equal(JSON.stringify(response).includes('private'), false);
+  }
+});

packages/ql3-cluster-control/test/productionApplication.test.cjs

@@ -732,6 +732,7 @@ test('optionally exposes Prompt execution behind shared admission and policy', a
     'copilot.failure_diagnosis.execute',
     'copilot.failure_diagnosis.read',
     'copilot.failure_diagnosis.output.read',
+    'copilot.failure_diagnosis.cancel',
   ]);
   const response = await invoke(
     stack,
@@ -762,6 +763,7 @@ test('optionally exposes Prompt execution behind shared admission and policy', a
 test('optionally exposes Copilot diagnosis behind shared authentication, Policy and audit', async () => {
   const { events, input } = fixture();
   let command;
+  let cancellationCommand;
   const capability = {
     async execute(value) {
       command = value;
@@ -803,11 +805,30 @@ test('optionally exposes Copilot diagnosis behind shared authentication, Policy
         requestId: value.requestId,
       };
     },
+    async cancel(value) {
+      cancellationCommand = value;
+      return {
+        schema: 'qinglong/copilot-failure-diagnosis-cancellation-result@v1',
+        status: 'accepted',
+        convergence: 'terminal',
+        projectId: value.projectId,
+        sourceRunId: value.sourceRunId,
+        requestId: value.requestId,
+        diagnosisRunId: 'diagnosis-run-1',
+        runStatus: 'cancelled',
+        outcome: 'cancelled',
+        runVersion: 7,
+        eventSequence: 7,
+        cancelRequestedAtMs: 2_000,
+        cancelReason: 'user',
+      };
+    },
   };
   const stack = createProductionClusterControlApplicationStack(input, {
     copilotFailureDiagnosis: {
       capability,
       readCapability: capability,
+      cancellationCapability: capability,
     },
   });
   const result = await invoke(
@@ -849,6 +870,25 @@ test('optionally exposes Copilot diagnosis behind shared authentication, Policy
   );
   assert.equal(inspection.statusCode, 404);
   assert.equal(output.statusCode, 404);
+  const cancellation = await invoke(
+    stack,
+    metadata(
+      '/api/v3/projects/project-1/runs/run-1/copilot/failure-diagnoses/diagnosis-request-1/cancellation',
+      'POST',
+      {
+        schema: 'qinglong/run-cancellation@v1',
+        mutationId: '00000000-0000-4000-8000-000000000099',
+      },
+    ),
+  );
+  assert.equal(cancellation.statusCode, 202);
+  assert.equal(cancellationCommand.projectId, 'project-1');
+  assert.equal(cancellationCommand.sourceRunId, 'run-1');
+  assert.equal(cancellationCommand.requestId, 'diagnosis-request-1');
+  assert.deepEqual(cancellationCommand.policyFence, {
+    projectVersion: 3,
+    bindingVersion: 7,
+  });
   assert.equal(
     events.includes('audit:copilot.failure_diagnosis.read:allowed'),
     true,
@@ -857,6 +897,10 @@ test('optionally exposes Copilot diagnosis behind shared authentication, Policy
     events.includes('audit:copilot.failure_diagnosis.output.read:allowed'),
     true,
   );
+  assert.equal(
+    events.includes('audit:copilot.failure_diagnosis.cancel:allowed'),
+    true,
+  );
 });
 
 test('keeps the Copilot route absent by default and never invokes it after Policy denial', async () => {
@@ -879,6 +923,7 @@ test('keeps the Copilot route absent by default and never invokes it after Polic
   for (const path of [
     '/api/v3/projects/project-1/runs/run-1/copilot/failure-diagnoses/diagnosis-request-1',
     '/api/v3/projects/project-1/runs/run-1/copilot/failure-diagnoses/diagnosis-request-1/output',
+    '/api/v3/projects/project-1/runs/run-1/copilot/failure-diagnoses/diagnosis-request-1/cancellation',
   ]) {
     await assert.rejects(
       defaultStack.admission.prepare(metadata(path)),