@shipfox/api-agent-access 20.2.0 → 20.3.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-agent-access",
   "license": "MIT",
-  "version": "20.2.0",
+  "version": "20.3.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -11,31 +11,48 @@
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "imports": {
+    "#test/*": "./test/*",
+    "#*": {
+      "workspace-source": "./src/*",
+      "default": "./dist/*"
+    }
+  },
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
+      "workspace-source": {
+        "types": "./src/index.ts",
+        "default": "./src/index.ts"
+      },
+      "default": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
     }
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.29.0",
-    "@shipfox/api-agent-access-dto": "20.2.0",
+    "@shipfox/api-agent-access-dto": "20.3.0",
+    "@shipfox/annotations-dto": "20.3.0",
     "@shipfox/api-auth-context": "20.2.0",
+    "@shipfox/api-definitions-dto": "20.3.0",
+    "@shipfox/api-projects-dto": "20.0.0",
+    "@shipfox/api-triggers-dto": "19.0.0",
+    "@shipfox/api-workflows-dto": "20.3.0",
+    "@shipfox/inter-module": "0.2.3",
+    "@shipfox/node-drizzle": "0.3.5",
     "@shipfox/node-error-monitoring": "0.3.0",
     "@shipfox/node-fastify": "0.4.4",
     "@shipfox/node-module": "1.0.9",
     "@shipfox/node-opentelemetry": "0.6.5"
   },
-  "imports": {
-    "#*": "./dist/*"
-  },
-  "shipfox": {
-    "architecture": {
-      "schema": 1,
-      "realm": "source-available",
-      "kind": "implementation",
-      "context": "agent-access"
-    }
+  "devDependencies": {
+    "@shipfox/biome": "1.10.1",
+    "@shipfox/depcruise": "1.0.5",
+    "@shipfox/swc": "1.2.8",
+    "@shipfox/ts-config": "1.3.9",
+    "@shipfox/typescript": "1.1.10",
+    "@shipfox/vitest": "1.2.6"
   },
   "scripts": {
     "build": "shipfox-swc",

package/src/core/paged-tools.test.ts

@@ -0,0 +1,519 @@
+import type {AnnotationsInterModuleClient} from '@shipfox/annotations-dto/inter-module';
+import type {AgentAccessEnvelopeDto} from '@shipfox/api-agent-access-dto';
+import {agentAccessEnvelopeSchema} from '@shipfox/api-agent-access-dto';
+import type {AgentAccessContext} from '@shipfox/api-auth-context';
+import {
+  type DefinitionsInterModuleClient,
+  definitionsInterModuleContract,
+} from '@shipfox/api-definitions-dto/inter-module';
+import type {ProjectsModuleClient} from '@shipfox/api-projects-dto/inter-module';
+import type {TriggersInterModuleClient} from '@shipfox/api-triggers-dto/inter-module';
+import type {WorkflowsModuleClient} from '@shipfox/api-workflows-dto/inter-module';
+import {createInterModuleKnownError} from '@shipfox/inter-module';
+import {decodeNumberIdCursor, decodeStringIdCursor} from '@shipfox/node-drizzle';
+import {createAgentAccessTools} from './paged-tools.js';
+import {serializedAgentAccessEnvelopeByteLength} from './response.js';
+
+const workspaceId = uuid(1);
+const projectId = uuid(2);
+const definitionId = uuid(3);
+const runId = uuid(4);
+const annotationId = uuid(5);
+const triggerEventId = uuid(6);
+const isoDate = '2026-08-01T00:00:00.000Z';
+const context: AgentAccessContext = {
+  userId: uuid(7),
+  workspaceId,
+  scopes: ['read'],
+  credential: {kind: 'pat', patId: uuid(8)},
+};
+
+describe('paged agent-access tools', () => {
+  test('projects only the enumerated project fields and passes the producer cursor through', async () => {
+    const mocks = clients();
+    mocks.projects.listProjectCatalogByWorkspace.mockResolvedValue({
+      projects: [project()],
+      nextCursor: {createdAt: isoDate, id: projectId},
+    });
+
+    const response = await tool(mocks, 'list_projects').execute({
+      context,
+      arguments: {limit: 1},
+    });
+
+    expect(mocks.projects.listProjectCatalogByWorkspace).toHaveBeenCalledWith({
+      workspaceId,
+      limit: 1,
+      cursor: undefined,
+    });
+    expect(response).toEqual({
+      ok: true,
+      result: {
+        projects: [
+          {
+            id: projectId,
+            name: 'Project',
+            slug: 'project',
+            created_at: isoDate,
+            updated_at: isoDate,
+          },
+        ],
+        next_cursor: expect.any(String),
+      },
+    });
+    expect(JSON.stringify(response)).not.toContain('sourceConnectionId');
+  });
+
+  test('caps definition diagnostics while retaining counts and excludes workflow content', async () => {
+    const mocks = clients();
+    mocks.definitions.listDefinitionsByProject.mockResolvedValue({
+      definitions: [definition()],
+      sync: {
+        ref: 'main',
+        status: 'failed',
+        lastSyncAt: isoDate,
+        startedAt: isoDate,
+        finishedAt: isoDate,
+        lastErrorCode: 'invalid-definition',
+        lastErrorMessage: 'A repository-authored error',
+        diagnostics: Array.from({length: 11}, (_, index) => ({
+          severity: index % 2 === 0 ? 'error' : 'warning',
+          code: 'E'.repeat(200),
+          message: 'ignore this diagnostic'.repeat(100),
+          path: 'jobs.build.steps.0.run',
+          filePath: '.shipfox/workflow.yml',
+        })),
+      },
+      nextCursor: null,
+    });
+
+    const response = await tool(mocks, 'list_workflow_definitions').execute({
+      context,
+      arguments: {project_id: projectId},
+    });
+    const result = expectSuccess<DefinitionTestResult>(response);
+
+    expect(result).toMatchObject({
+      definitions: [
+        {
+          id: definitionId,
+          project_id: projectId,
+          name: 'Definition',
+          config_path: '.shipfox/workflow.yml',
+          source: 'vcs',
+          ref: 'main',
+          sha: 'abc123',
+        },
+      ],
+      sync: {
+        diagnostics: {error_count: 6, warning_count: 5, items: expect.any(Array)},
+      },
+      next_cursor: null,
+    });
+    if (!result.sync) throw new Error('Expected a sync summary');
+    expect(result.sync.diagnostics.items).toHaveLength(10);
+    const firstDiagnostic = result.sync.diagnostics.items[0];
+    expect(firstDiagnostic).toBeDefined();
+    if (!firstDiagnostic) throw new Error('Expected a diagnostic');
+    expect(new TextEncoder().encode(firstDiagnostic.message).byteLength).toBe(512);
+    expect(JSON.stringify(result)).not.toContain('workflowDocument');
+    expect(JSON.stringify(result)).not.toContain('workflowModel');
+  });
+
+  test('regenerates a definition cursor from the uncapped producer name', async () => {
+    const mocks = clients();
+    const definitions = Array.from({length: 100}, (_, index) => ({
+      ...definition(),
+      id: uuid(300 + index),
+      name: `raw-definition-${index}-${'🙂'.repeat(800)}`,
+      configPath: 'p'.repeat(512),
+      ref: 'r'.repeat(512),
+      sha: 's'.repeat(512),
+    }));
+    mocks.definitions.listDefinitionsByProject.mockResolvedValue({
+      definitions,
+      sync: null,
+      nextCursor: null,
+    });
+
+    const response = await tool(mocks, 'list_workflow_definitions').execute({
+      context,
+      arguments: {project_id: projectId, limit: 100},
+    });
+    const result = expectSuccess<DefinitionPageTestResult>(response);
+    const last = result.definitions.at(-1);
+
+    expect(result.definitions.length).toBeLessThan(100);
+    expect(response).toMatchObject({ok: true, response_truncated: true});
+    expect(response.response_total_bytes).toBeGreaterThan(128 * 1024);
+    expect(last).toBeDefined();
+    expect(decodeStringIdCursor(result.next_cursor ?? undefined)).toEqual({
+      value: definitions[result.definitions.length - 1]?.name,
+      id: last?.id,
+    });
+    expect(serializedAgentAccessEnvelopeByteLength(response)).toBeLessThanOrEqual(128 * 1024);
+  });
+
+  test('checks project ownership before listing runs and excludes payload, inputs, and jobs', async () => {
+    const mocks = clients();
+    mocks.projects.requireProjectForWorkspace.mockResolvedValue({project: project()});
+    mocks.workflows.listWorkflowRuns.mockResolvedValue({
+      runs: [run()],
+      nextCursor: null,
+      filteredTotalCount: 1,
+    });
+
+    const response = await tool(mocks, 'list_workflow_runs').execute({
+      context,
+      arguments: {project_id: projectId, status: 'failed', trigger_source: 'push'},
+    });
+    const result = expectSuccess<RunTestResult>(response);
+
+    expect(mocks.projects.requireProjectForWorkspace).toHaveBeenCalledWith({
+      workspaceId,
+      projectId,
+    });
+    expect(mocks.workflows.listWorkflowRuns).toHaveBeenCalledWith({
+      workspaceId,
+      projectId,
+      limit: 50,
+      cursor: undefined,
+      filters: {status: 'failed', triggerSource: 'push'},
+    });
+    expect(result.runs[0]).not.toHaveProperty('trigger_payload');
+    expect(result.runs[0]).not.toHaveProperty('inputs');
+    expect(result.runs[0]).not.toHaveProperty('jobs');
+  });
+
+  test('resolves the latest annotation attempt and marks UTF-8 body truncation', async () => {
+    const mocks = clients();
+    mocks.workflows.getLatestRunAttempt.mockResolvedValue({attempt: 2});
+    mocks.annotations.listAnnotationsForRunAttempt.mockResolvedValue({
+      annotations: [
+        {
+          id: annotationId,
+          job_id: uuid(9),
+          job_execution_id: uuid(10),
+          origin_step_id: uuid(11),
+          origin_step_attempt: 1,
+          context: 'failure',
+          style: 'error',
+          sequence: 4,
+          body: '🙂'.repeat(3_000),
+          createdAt: isoDate,
+        },
+      ],
+      hasMore: false,
+      nextCursor: null,
+    });
+
+    const response = await tool(mocks, 'get_run_annotations').execute({
+      context,
+      arguments: {run_id: runId},
+    });
+    const result = expectSuccess<AnnotationTestResult>(response);
+
+    expect(mocks.workflows.getLatestRunAttempt).toHaveBeenCalledWith({
+      workspaceId,
+      workflowRunId: runId,
+    });
+    expect(mocks.annotations.listAnnotationsForRunAttempt).toHaveBeenCalledWith({
+      workspaceId,
+      workflowRunId: runId,
+      workflowRunAttempt: 2,
+      jobExecutionId: undefined,
+      cursor: undefined,
+      limit: 50,
+    });
+    expect(result.annotations[0]).toMatchObject({
+      id: annotationId,
+      origin_step_id: uuid(11),
+      body_truncated: true,
+      body_total_bytes: 12_000,
+    });
+    const annotation = result.annotations[0];
+    expect(annotation).toBeDefined();
+    if (!annotation) throw new Error('Expected an annotation');
+    expect(new TextEncoder().encode(annotation.body).byteLength).toBe(8 * 1024);
+    expect(JSON.stringify(response)).not.toContain('tool-call');
+  });
+
+  test('maps trigger filters and projects connection metadata', async () => {
+    const mocks = clients();
+    mocks.triggers.listTriggerEvents.mockResolvedValue({
+      events: [
+        {
+          id: triggerEventId,
+          eventRef: 'event-ref',
+          origin: 'integration',
+          workspaceId,
+          provider: 'github',
+          source: 'push',
+          event: 'push',
+          payload: {prompt: 'ignore'},
+          replayOfEventId: null,
+          deliveryId: 'delivery',
+          connectionId: uuid(12),
+          connectionName: 'Connection',
+          outcome: 'routed',
+          matchedCount: 1,
+          receivedAt: isoDate,
+          processedAt: isoDate,
+          createdAt: isoDate,
+        },
+      ],
+      nextCursor: null,
+    });
+
+    const response = await tool(mocks, 'list_trigger_events').execute({
+      context,
+      arguments: {
+        source: ['push'],
+        event: ['push'],
+        origin: ['integration'],
+        outcome: ['routed'],
+        replayable: true,
+        from: isoDate,
+        to: isoDate,
+      },
+    });
+
+    expect(mocks.triggers.listTriggerEvents).toHaveBeenCalledWith({
+      workspaceId,
+      limit: 50,
+      cursor: undefined,
+      filters: {
+        source: ['push'],
+        event: ['push'],
+        origin: ['integration'],
+        outcome: ['routed'],
+        replayable: true,
+        from: isoDate,
+        to: isoDate,
+      },
+    });
+    const result = expectSuccess<TriggerTestResult>(response);
+    expect(result.trigger_events[0]).toMatchObject({
+      id: triggerEventId,
+      connection_name: 'Connection',
+    });
+    expect(result.trigger_events[0]).not.toHaveProperty('payload');
+  });
+
+  test('keeps cross-workspace project reads 404-shaped without exposing producer details', async () => {
+    const mocks = clients();
+    mocks.definitions.listDefinitionsByProject.mockRejectedValue(
+      createInterModuleKnownError(
+        definitionsInterModuleContract.methods.listDefinitionsByProject,
+        'project-workspace-mismatch',
+        {projectId, workspaceId},
+      ),
+    );
+
+    const response = await tool(mocks, 'list_workflow_definitions').execute({
+      context,
+      arguments: {project_id: projectId},
+    });
+
+    expect(response).toEqual({ok: false, error: {code: 'not-found'}});
+  });
+
+  test('does not query annotations for a run from another workspace', async () => {
+    const mocks = clients();
+    mocks.workflows.getLatestRunAttempt.mockResolvedValue({attempt: null});
+
+    const response = await tool(mocks, 'get_run_annotations').execute({
+      context,
+      arguments: {run_id: runId},
+    });
+
+    expect(response).toEqual({ok: false, error: {code: 'not-found'}});
+    expect(mocks.annotations.listAnnotationsForRunAttempt).not.toHaveBeenCalled();
+  });
+
+  test('reduces an oversized annotation page and anchors its cursor to the retained item', async () => {
+    const mocks = clients();
+    mocks.workflows.getLatestRunAttempt.mockResolvedValue({attempt: 1});
+    const annotations = Array.from({length: 100}, (_, index) => ({
+      id: uuid(100 + index),
+      job_id: uuid(200),
+      job_execution_id: uuid(201),
+      origin_step_id: uuid(202),
+      origin_step_attempt: 1,
+      context: `annotation-${index}`,
+      style: 'info' as const,
+      sequence: index + 1,
+      body: 'x'.repeat(9_000),
+      createdAt: isoDate,
+    }));
+    mocks.annotations.listAnnotationsForRunAttempt.mockResolvedValue({
+      annotations,
+      hasMore: false,
+      nextCursor: null,
+    });
+
+    const response = await tool(mocks, 'get_run_annotations').execute({
+      context,
+      arguments: {run_id: runId, limit: 100},
+    });
+    const result = expectSuccess<AnnotationPageTestResult>(response);
+    const last = result.annotations.at(-1);
+
+    expect(result.annotations.length).toBeLessThan(100);
+    expect(response).toMatchObject({ok: true, response_truncated: true});
+    expect(response.response_total_bytes).toBeGreaterThan(128 * 1024);
+    expect(last).toBeDefined();
+    expect(result.next_cursor).toBeDefined();
+    expect(decodeNumberIdCursor(result.next_cursor ?? undefined)).toEqual({
+      value: last?.sequence,
+      id: last?.id,
+    });
+    expect(serializedAgentAccessEnvelopeByteLength(response)).toBeLessThanOrEqual(128 * 1024);
+  });
+});
+
+function clients() {
+  return {
+    projects: {
+      listProjectCatalogByWorkspace: vi.fn(),
+      requireProjectForWorkspace: vi.fn(),
+    } as unknown as ProjectsModuleClient & {
+      listProjectCatalogByWorkspace: ReturnType<typeof vi.fn>;
+      requireProjectForWorkspace: ReturnType<typeof vi.fn>;
+    },
+    definitions: {
+      listDefinitionsByProject: vi.fn(),
+    } as unknown as DefinitionsInterModuleClient & {
+      listDefinitionsByProject: ReturnType<typeof vi.fn>;
+    },
+    workflows: {
+      listWorkflowRuns: vi.fn(),
+      getLatestRunAttempt: vi.fn(),
+      getWorkflowRunDetail: vi.fn(),
+    } as unknown as WorkflowsModuleClient & {
+      listWorkflowRuns: ReturnType<typeof vi.fn>;
+      getLatestRunAttempt: ReturnType<typeof vi.fn>;
+      getWorkflowRunDetail: ReturnType<typeof vi.fn>;
+    },
+    annotations: {
+      listAnnotationsForRunAttempt: vi.fn(),
+    } as unknown as AnnotationsInterModuleClient & {
+      listAnnotationsForRunAttempt: ReturnType<typeof vi.fn>;
+    },
+    triggers: {
+      listTriggerEvents: vi.fn(),
+    } as unknown as TriggersInterModuleClient & {
+      listTriggerEvents: ReturnType<typeof vi.fn>;
+    },
+  };
+}
+
+function tool(mocks: ReturnType<typeof clients>, name: string) {
+  const result = createAgentAccessTools(mocks).find((candidate) => candidate.name === name);
+  if (!result) throw new Error(`Missing tool ${name}`);
+  return result;
+}
+
+function expectSuccess<T>(response: AgentAccessEnvelopeDto): T {
+  expect(response.ok).toBe(true);
+  if (!response.ok) throw new Error('Expected a success response');
+  expect(agentAccessEnvelopeSchema.safeParse(response).success).toBe(true);
+  return response.result as T;
+}
+
+type DefinitionTestResult = {
+  definitions: Array<Record<string, unknown>>;
+  sync: {diagnostics: {items: Array<{message: string}>}} | null;
+  next_cursor: string | null;
+};
+
+type DefinitionPageTestResult = {
+  definitions: Array<{id: string}>;
+  next_cursor: string | null;
+};
+
+type RunTestResult = {
+  runs: Array<Record<string, unknown>>;
+};
+
+type AnnotationTestResult = {
+  annotations: Array<{body: string}>;
+};
+
+type AnnotationPageTestResult = {
+  annotations: Array<{id: string; sequence: number}>;
+  next_cursor: string | null;
+};
+
+type TriggerTestResult = {
+  trigger_events: Array<Record<string, unknown>>;
+};
+
+function project(id = projectId, name = 'Project', slug = 'project') {
+  return {
+    id,
+    workspaceId,
+    sourceConnectionId: uuid(20),
+    sourceExternalRepositoryId: 'external-repository',
+    sourceRepositoryOwner: 'shipfox',
+    sourceRepositoryName: 'platform',
+    sourceDefaultBranch: 'main',
+    name,
+    slug,
+    createdAt: isoDate,
+    updatedAt: isoDate,
+  };
+}
+
+function definition() {
+  return {
+    id: definitionId,
+    projectId,
+    configPath: '.shipfox/workflow.yml',
+    source: 'vcs' as const,
+    sha: 'abc123',
+    ref: 'main',
+    name: 'Definition',
+    workflowDocument: {prompt: 'ignore'},
+    workflowModel: {jobs: {build: {steps: []}}},
+    manualTrigger: null,
+    fetchedAt: isoDate,
+    createdAt: isoDate,
+    updatedAt: isoDate,
+  };
+}
+
+function run() {
+  return {
+    id: runId,
+    project_id: projectId,
+    definition_id: definitionId,
+    number: 1,
+    name: 'Run',
+    workflow_name: 'Workflow',
+    status: 'failed' as const,
+    origin: 'synced' as const,
+    dev_source: null,
+    current_attempt: 1,
+    latest_attempt: 1,
+    trigger_provider: 'github',
+    trigger_source: 'push',
+    trigger_event: 'push',
+    trigger_payload: {prompt: 'ignore'},
+    trigger_reference: {repository: 'shipfox/platform', ref: 'main', commit: 'abc', actor: 'noe'},
+    inputs: {prompt: 'ignore'},
+    source_snapshot: null,
+    created_at: isoDate,
+    updated_at: isoDate,
+    started_at: isoDate,
+    finished_at: isoDate,
+    jobs: [],
+    job_status_counts: [{status: 'failed' as const, count: 1}],
+    job_display_status_counts: [],
+    has_started_job_execution: true,
+  };
+}
+
+function uuid(value: number): string {
+  return `00000000-0000-4000-8000-${String(value).padStart(12, '0')}`;
+}