feat(ql3): expose fenced copilot diagnosis API

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

@@ -117,7 +117,7 @@ async function projectedFile(root, name, bytes) {
   await chmod(join(root, name), 0o440);
 }
 
-test('Copilot composition is explicit, shares the Prompt gateway and exposes no route', async () => {
+test('Copilot composition is explicit, shares the Prompt gateway and injects one route capability', async () => {
   const secretRoot = await mkdtemp(join(tmpdir(), 'ql3-cluster-ai-secret-'));
   const configRoot = await mkdtemp(join(tmpdir(), 'ql3-copilot-config-'));
   const invocationRoot = await mkdtemp(join(tmpdir(), 'ql3-copilot-invocation-'));
@@ -229,7 +229,7 @@ test('Copilot composition is explicit, shares the Prompt gateway and exposes no
     assert.equal(created.gateway, gateway);
     assert.equal(created.successfulCompletion, registeredSink);
     assert.equal(created.artifactStore, artifactStore);
-    assert.equal('copilot' in controlOptions, false);
+    assert.equal(controlOptions.copilotFailureDiagnosis.capability, copilot);
     assert.equal(await application.stop(), 'stopped');
   } finally {
     config.fill(0); invocation.fill(0); result.fill(0); output.fill(0);

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

@@ -0,0 +1,269 @@
+const assert = require('node:assert/strict');
+const { test } = require('node:test');
+const {
+  CLUSTER_COPILOT_FAILURE_DIAGNOSIS_REQUEST_SCHEMA,
+  CLUSTER_COPILOT_FAILURE_DIAGNOSIS_RESPONSE_SCHEMA,
+  CLUSTER_CONTROL_COPILOT_FAILURE_DIAGNOSIS_ROUTE,
+  createClusterControlCopilotFailureDiagnosisRoute,
+} = require('@qinglong/cluster-control/copilot-routes');
+
+function authorized(body, overrides = {}) {
+  return {
+    request: {
+      requestId: 'diagnosis-request-1',
+      method: 'POST',
+      path: '/api/v3/projects/project-1/runs/source-run-1/copilot/failure-diagnoses',
+      query: {},
+      headers: {},
+      signal: new AbortController().signal,
+      body,
+    },
+    principal: {
+      subject: { type: 'api_app', id: 'app-1' },
+      authenticationId: 'credential-1',
+      authenticatedAtMs: 1,
+      expiresAtMs: 10_000,
+      assurance: 'service',
+    },
+    operationId: 'copilot.failure_diagnosis.execute',
+    permission: 'model.invoke',
+    projectId: 'project-1',
+    policyFence: { projectVersion: 3, bindingVersion: 7 },
+    ...overrides,
+  };
+}
+
+function body(overrides = {}) {
+  return {
+    schema: CLUSTER_COPILOT_FAILURE_DIAGNOSIS_REQUEST_SCHEMA,
+    traceId: 'trace-1',
+    ...overrides,
+  };
+}
+
+function succeeded(admissionStatus = 'created') {
+  return {
+    admissionStatus,
+    admission: {
+      requestId: 'diagnosis-request-1',
+      runId: 'diagnosis-run-1',
+      sourceRunId: 'source-run-1',
+    },
+    tool: { outcome: 'succeeded', output: { private: 'must not cross' } },
+    model: {
+      outcome: 'succeeded',
+      output: {
+        artifactId: 'cdo:artifact-1',
+        artifactDigest: 'a'.repeat(64),
+        provider: 'private-provider',
+      },
+      plaintext: 'private diagnosis',
+    },
+    terminalization: null,
+    terminalizationRequired: false,
+  };
+}
+
+test('defines one exact model.invoke route and binds HTTP request identity', async () => {
+  let command;
+  const route = createClusterControlCopilotFailureDiagnosisRoute({
+    async execute(value) {
+      command = value;
+      return succeeded();
+    },
+  });
+  const request = authorized(body());
+  const result = await route.handle(request, {
+    projectId: 'project-1',
+    runId: 'source-run-1',
+  });
+
+  assert.deepEqual(CLUSTER_CONTROL_COPILOT_FAILURE_DIAGNOSIS_ROUTE, {
+    method: 'POST',
+    path: '/api/v3/projects/{projectId}/runs/{runId}/copilot/failure-diagnoses',
+    operationId: 'copilot.failure_diagnosis.execute',
+    permission: 'model.invoke',
+    projectParameter: 'projectId',
+  });
+  assert.deepEqual(command, {
+    requestId: 'diagnosis-request-1',
+    traceId: 'trace-1',
+    projectId: 'project-1',
+    sourceRunId: 'source-run-1',
+    principal: request.principal,
+  });
+  assert.equal('policyFence' in command, false);
+  assert.equal('model' in command, false);
+  assert.equal('attemptId' in command, false);
+  assert.equal(result.statusCode, 201);
+  assert.deepEqual(result.body, {
+    schema: CLUSTER_COPILOT_FAILURE_DIAGNOSIS_RESPONSE_SCHEMA,
+    requestId: 'diagnosis-request-1',
+    status: 'created',
+    replayed: false,
+    sourceRunId: 'source-run-1',
+    diagnosisRunId: 'diagnosis-run-1',
+    outcome: 'succeeded',
+    stage: 'model',
+    reason: null,
+    outputArtifact: {
+      artifactId: 'cdo:artifact-1',
+      artifactDigest: 'a'.repeat(64),
+    },
+  });
+  assert.equal(JSON.stringify(result).includes('private'), false);
+});
+
+test('returns a content-free existing receipt for exact replay', async () => {
+  const route = createClusterControlCopilotFailureDiagnosisRoute({
+    async execute() {
+      return succeeded('existing');
+    },
+  });
+  const result = await route.handle(authorized(body()), {
+    projectId: 'project-1',
+    runId: 'source-run-1',
+  });
+  assert.equal(result.statusCode, 200);
+  assert.equal(result.body.status, 'existing');
+  assert.equal(result.body.replayed, true);
+});
+
+test('projects pre-Model terminalization without Tool or log content', async () => {
+  const route = createClusterControlCopilotFailureDiagnosisRoute({
+    async execute() {
+      return {
+        admissionStatus: 'created',
+        admission: {
+          requestId: 'diagnosis-request-1',
+          runId: 'diagnosis-run-1',
+          sourceRunId: 'source-run-1',
+        },
+        tool: { outcome: 'failed', privateLog: 'must not cross' },
+        model: null,
+        terminalization: {
+          stage: 'log',
+          reason: 'log_retired',
+          outcome: 'failed',
+          privateEvidence: 'must not cross',
+        },
+        terminalizationRequired: false,
+      };
+    },
+  });
+  const result = await route.handle(authorized(body()), {
+    projectId: 'project-1',
+    runId: 'source-run-1',
+  });
+  assert.equal(result.statusCode, 201);
+  assert.equal(result.body.stage, 'log');
+  assert.equal(result.body.reason, 'log_retired');
+  assert.equal(result.body.outcome, 'failed');
+  assert.equal(result.body.outputArtifact, null);
+  assert.equal(JSON.stringify(result).includes('private'), false);
+});
+
+test('rejects non-exact bodies before invoking the capability', async () => {
+  let calls = 0;
+  const route = createClusterControlCopilotFailureDiagnosisRoute({
+    async execute() {
+      calls += 1;
+      return succeeded();
+    },
+  });
+  for (const invalid of [
+    null,
+    {},
+    body({ requestId: 'body-request-must-not-exist' }),
+    body({ provider: 'caller-selected' }),
+    body({ traceId: '' }),
+    Object.assign(Object.create(null), body()),
+  ]) {
+    const result = await route.handle(authorized(invalid), {
+      projectId: 'project-1',
+      runId: 'source-run-1',
+    });
+    assert.equal(result.statusCode, 400);
+    assert.deepEqual(result.body, {
+      code: 'invalid_copilot_failure_diagnosis_request',
+    });
+  }
+  assert.equal(calls, 0);
+});
+
+test('fails closed on capability responses that do not bind the durable identity', async () => {
+  for (const mutation of [
+    (value) => ({
+      ...value,
+      admission: { ...value.admission, requestId: 'other' },
+    }),
+    (value) => ({
+      ...value,
+      admission: { ...value.admission, sourceRunId: 'other' },
+    }),
+    (value) => ({ ...value, terminalizationRequired: true }),
+    (value) => ({ ...value, model: null }),
+    (value) => ({ ...value, model: { ...value.model, output: null } }),
+  ]) {
+    const route = createClusterControlCopilotFailureDiagnosisRoute({
+      async execute() {
+        return mutation(succeeded());
+      },
+    });
+    const result = await route.handle(authorized(body()), {
+      projectId: 'project-1',
+      runId: 'source-run-1',
+    });
+    assert.deepEqual(result, {
+      statusCode: 503,
+      body: { code: 'copilot_failure_diagnosis_unavailable' },
+    });
+  }
+});
+
+test('maps internal failures to stable low-sensitive transport codes', async () => {
+  for (const [internal, statusCode, external] of [
+    [
+      'COPILOT_FAILURE_DIAGNOSIS_APPLICATION_CONFLICT',
+      409,
+      'copilot_failure_diagnosis_conflict',
+    ],
+    [
+      'TRUSTED_TOOL_EXECUTION_POLICY_DENIED',
+      403,
+      'copilot_failure_diagnosis_forbidden',
+    ],
+    [
+      'COPILOT_FAILURE_DIAGNOSIS_APPLICATION_BUSY',
+      429,
+      'copilot_failure_diagnosis_capacity_exceeded',
+    ],
+    [
+      'COPILOT_MODEL_EGRESS_DENIED',
+      422,
+      'copilot_failure_diagnosis_policy_rejected',
+    ],
+    [
+      'MODEL_INVOCATION_DEADLINE_EXCEEDED',
+      504,
+      'copilot_failure_diagnosis_deadline_exceeded',
+    ],
+    ['MODEL_INVOCATION_ABORTED', 408, 'copilot_failure_diagnosis_aborted'],
+    ['PRIVATE_STORAGE_FAILURE', 503, 'copilot_failure_diagnosis_unavailable'],
+  ]) {
+    const route = createClusterControlCopilotFailureDiagnosisRoute({
+      async execute() {
+        throw Object.assign(new Error('private internal detail'), {
+          code: internal,
+        });
+      },
+    });
+    const result = await route.handle(authorized(body()), {
+      projectId: 'project-1',
+      runId: 'source-run-1',
+    });
+    assert.equal(result.statusCode, statusCode, internal);
+    assert.deepEqual(result.body, { code: external });
+    assert.equal(JSON.stringify(result).includes('private'), false);
+  }
+});

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

@@ -729,6 +729,7 @@ test('optionally exposes Prompt execution behind shared admission and policy', a
     'prompt.execution.read',
     'prompt.execution.output.read',
     'prompt.output.read',
+    'copilot.failure_diagnosis.execute',
   ]);
   const response = await invoke(
     stack,
@@ -756,6 +757,134 @@ test('optionally exposes Prompt execution behind shared admission and policy', a
   assert.equal(events.includes('audit:prompt.execute:allowed'), true);
 });
 
+test('optionally exposes Copilot diagnosis behind shared authentication, Policy and audit', async () => {
+  const { events, input } = fixture();
+  let command;
+  const capability = {
+    async execute(value) {
+      command = value;
+      events.push(`diagnose:${value.sourceRunId}`);
+      return {
+        admissionStatus: 'created',
+        admission: {
+          requestId: value.requestId,
+          runId: 'diagnosis-run-1',
+          sourceRunId: value.sourceRunId,
+        },
+        tool: { outcome: 'succeeded' },
+        model: {
+          outcome: 'succeeded',
+          output: {
+            artifactId: 'cdo:artifact-1',
+            artifactDigest: 'a'.repeat(64),
+          },
+        },
+        terminalization: null,
+        terminalizationRequired: false,
+      };
+    },
+  };
+  const stack = createProductionClusterControlApplicationStack(input, {
+    copilotFailureDiagnosis: { capability },
+  });
+  const result = await invoke(
+    stack,
+    metadata(
+      '/api/v3/projects/project-1/runs/run-1/copilot/failure-diagnoses',
+      'POST',
+      {
+        schema: 'qinglong/cluster-copilot-failure-diagnosis-request@v1',
+        traceId: 'trace-production-1',
+      },
+    ),
+  );
+
+  assert.equal(result.statusCode, 201);
+  assert.equal(command.requestId, 'request-production-1');
+  assert.equal(command.projectId, 'project-1');
+  assert.equal(command.sourceRunId, 'run-1');
+  assert.equal(command.principal.subject.id, 'app-production');
+  assert.equal('policyFence' in command, false);
+  assert.deepEqual(events.slice(-4), [
+    'authenticate',
+    'authorize',
+    'audit:copilot.failure_diagnosis.execute:allowed',
+    'diagnose:run-1',
+  ]);
+});
+
+test('keeps the Copilot route absent by default and never invokes it after Policy denial', async () => {
+  const defaultFixture = fixture();
+  const defaultStack = createProductionClusterControlApplicationStack(
+    defaultFixture.input,
+  );
+  const request = metadata(
+    '/api/v3/projects/project-1/runs/run-1/copilot/failure-diagnoses',
+    'POST',
+    {
+      schema: 'qinglong/cluster-copilot-failure-diagnosis-request@v1',
+      traceId: 'trace-production-1',
+    },
+  );
+  await assert.rejects(
+    defaultStack.admission.prepare(request),
+    (error) => error?.statusCode === 404 && error?.code === 'route_not_found',
+  );
+
+  let calls = 0;
+  const deniedFixture = fixture({
+    policies: {
+      async resolve() {
+        deniedFixture.events.push('authorize');
+        return {
+          project: {
+            id: 'project-1',
+            name: 'Denied Project',
+            slug: 'denied-project',
+            status: 'active',
+            version: 3,
+            createdAtMs: 1,
+            updatedAtMs: 2,
+          },
+          binding: {
+            projectId: 'project-1',
+            subject: { type: 'api_app', id: 'app-production' },
+            state: 'active',
+            role: 'viewer',
+            version: 7,
+            mutationId: 'binding-denied-1',
+            changedBy: { type: 'system', id: 'bootstrap' },
+            createdAtMs: 1,
+          },
+        };
+      },
+    },
+  });
+  const deniedStack = createProductionClusterControlApplicationStack(
+    deniedFixture.input,
+    {
+      copilotFailureDiagnosis: {
+        capability: {
+          async execute() {
+            calls += 1;
+          },
+        },
+      },
+    },
+  );
+  await assert.rejects(
+    deniedStack.admission.prepare(request),
+    (error) => error?.statusCode === 403 && error?.code === 'forbidden',
+  );
+  assert.equal(calls, 0);
+  assert.equal(
+    deniedFixture.events.includes(
+      'audit:copilot.failure_diagnosis.execute:denied',
+    ),
+    true,
+  );
+});
+
 test('optionally exposes the redacted Prompt catalog behind shared admission and policy', async () => {
   const { events, input } = fixture();
   const stack = createProductionClusterControlApplicationStack(input, {