@shipfox/api-agent-access 20.2.0 → 20.3.0

package/src/core/response.test.ts

@@ -0,0 +1,65 @@
+import {agentAccessSuccess} from './envelope.js';
+import {
+  reducePagedAgentAccessResponse,
+  serializedAgentAccessEnvelopeByteLength,
+  truncateAgentAccessUtf8,
+} from './response.js';
+
+describe('agent-access response bounds', () => {
+  test('truncates on a complete UTF-8 code-point boundary', () => {
+    const result = truncateAgentAccessUtf8('🙂'.repeat(4), 7);
+
+    expect(result).toEqual({value: '🙂', truncated: true, totalBytes: 16});
+  });
+
+  test('regenerates a page cursor from the last retained item', () => {
+    const items = Array.from({length: 20}, (_, index) => ({
+      id: `item-${index}-${'x'.repeat(20)}`,
+    }));
+    const envelope = agentAccessSuccess({items, next_cursor: 'producer-cursor'});
+    const initialBytes = serializedAgentAccessEnvelopeByteLength(envelope);
+    const reduced = reducePagedAgentAccessResponse({
+      envelope,
+      itemKey: 'items',
+      items,
+      cursorForItem: (item) => `cursor:${String(item.id)}`,
+      maxBytes: initialBytes - 20,
+    });
+    if (!reduced.ok) throw new Error('Expected a reduced page');
+    const result = reduced.result as {items: Array<{id: string}>; next_cursor: string | null};
+    const last = result.items.at(-1);
+
+    expect(reduced).toMatchObject({
+      response_truncated: true,
+      response_total_bytes: initialBytes,
+    });
+    expect(result.items.length).toBeLessThan(items.length);
+    expect(last).toBeDefined();
+    expect(result.next_cursor).toBe(`cursor:${last?.id}`);
+    expect(serializedAgentAccessEnvelopeByteLength(reduced)).toBeLessThanOrEqual(initialBytes - 20);
+  });
+
+  test('returns a content-too-large error instead of dropping every item', () => {
+    const envelope = agentAccessSuccess({
+      items: [{id: 'x'.repeat(1_000)}],
+      next_cursor: null,
+    });
+    const initialBytes = serializedAgentAccessEnvelopeByteLength(envelope);
+    const emptyTruncatedEnvelope = {
+      ...envelope,
+      result: {items: [], next_cursor: null},
+      response_truncated: true,
+      response_total_bytes: initialBytes,
+    };
+
+    expect(
+      reducePagedAgentAccessResponse({
+        envelope,
+        itemKey: 'items',
+        items: [{id: 'x'.repeat(1_000)}],
+        cursorForItem: () => 'cursor',
+        maxBytes: serializedAgentAccessEnvelopeByteLength(emptyTruncatedEnvelope),
+      }),
+    ).toEqual({ok: false, error: {code: 'content-too-large'}});
+  });
+});

package/src/core/response.ts

@@ -0,0 +1,101 @@
+import {
+  AGENT_ACCESS_RESPONSE_MAX_BYTES,
+  type AgentAccessEnvelopeDto,
+} from '@shipfox/api-agent-access-dto';
+import {agentAccessError} from './envelope.js';
+
+const utf8Encoder = new TextEncoder();
+
+export interface AgentAccessUtf8Truncation {
+  value: string;
+  truncated: boolean;
+  totalBytes: number;
+}
+
+export function truncateAgentAccessUtf8(
+  value: string,
+  maxBytes: number,
+): AgentAccessUtf8Truncation {
+  const totalBytes = utf8Encoder.encode(value).byteLength;
+  if (totalBytes <= maxBytes) return {value, truncated: false, totalBytes};
+  if (maxBytes <= 0) return {value: '', truncated: true, totalBytes};
+
+  let bytes = 0;
+  let result = '';
+  for (const codePoint of value) {
+    const codePointBytes = utf8Encoder.encode(codePoint).byteLength;
+    if (bytes + codePointBytes > maxBytes) break;
+    result += codePoint;
+    bytes += codePointBytes;
+  }
+
+  return {value: result, truncated: true, totalBytes};
+}
+
+export function serializedAgentAccessEnvelopeByteLength(envelope: AgentAccessEnvelopeDto): number {
+  const serialized = JSON.stringify(envelope);
+  if (serialized === undefined) throw new Error('Agent-access envelope is not serializable');
+  return utf8Encoder.encode(serialized).byteLength;
+}
+
+export interface ReducePagedAgentAccessResponseParams {
+  envelope: AgentAccessEnvelopeDto;
+  itemKey: string;
+  items: readonly Record<string, unknown>[];
+  cursorForItem: (item: Record<string, unknown>, index: number) => string;
+  maxBytes?: number | undefined;
+}
+
+/**
+ * Fits a paged success response without reusing a producer cursor that points past dropped rows.
+ * The cursor is always rebuilt from the final retained item.
+ */
+export function reducePagedAgentAccessResponse(
+  params: ReducePagedAgentAccessResponseParams,
+): AgentAccessEnvelopeDto {
+  const maxBytes = params.maxBytes ?? AGENT_ACCESS_RESPONSE_MAX_BYTES;
+  const initialBytes = serializedAgentAccessEnvelopeByteLength(params.envelope);
+  if (initialBytes <= maxBytes) return params.envelope;
+  if (!params.envelope.ok || !isRecord(params.envelope.result)) {
+    return agentAccessError('content-too-large');
+  }
+
+  const itemCounts =
+    params.items.length === 0
+      ? [0]
+      : Array.from(
+          {length: Math.max(0, params.items.length - 1)},
+          (_, index) => params.items.length - index - 1,
+        );
+  for (const itemCount of itemCounts) {
+    const retained = params.items.slice(0, itemCount);
+    const last = retained.at(-1);
+    const nextCursor = last === undefined ? null : params.cursorForItem(last, itemCount - 1);
+    const candidate: AgentAccessEnvelopeDto = {
+      ...params.envelope,
+      result: {
+        ...params.envelope.result,
+        [params.itemKey]: retained,
+        next_cursor: nextCursor,
+      },
+      response_truncated: true,
+      response_total_bytes: initialBytes,
+    };
+    if (serializedAgentAccessEnvelopeByteLength(candidate) <= maxBytes) return candidate;
+  }
+
+  return agentAccessError('content-too-large');
+}
+
+export function fitAgentAccessResponseToCeiling(
+  envelope: AgentAccessEnvelopeDto,
+  maxBytes = AGENT_ACCESS_RESPONSE_MAX_BYTES,
+): AgentAccessEnvelopeDto {
+  return serializedAgentAccessEnvelopeByteLength(envelope) <= maxBytes
+    ? envelope
+    : agentAccessError('content-too-large');
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/src/core/tools.ts

@@ -17,8 +17,10 @@ export interface AgentAccessTool {
   description: string;
   inputSchema: AgentAccessObjectSchema;
   outputSchema: AgentAccessObjectSchema;
+  validateInput?: ((input: unknown) => boolean) | undefined;
   annotations: {readonly readOnlyHint: true};
   execute: (call: AgentAccessToolCall) => Promise<AgentAccessEnvelopeDto> | AgentAccessEnvelopeDto;
+  validateResult?: ((result: unknown) => boolean) | undefined;
 }
 
 export type AgentAccessToolMap = ReadonlyMap<string, AgentAccessTool>;

package/src/index.ts

@@ -13,12 +13,23 @@ export {
   parseAgentAccessEnvelope,
   serializeAgentAccessEnvelope,
 } from '#core/envelope.js';
+export {
+  type AgentAccessPagedToolsOptions,
+  createAgentAccessTools,
+} from '#core/paged-tools.js';
 export {
   type AgentAccessRateLimitDecision,
   type AgentAccessRateLimiter,
   type CreateAgentAccessRateLimiterOptions,
   createAgentAccessRateLimiter,
 } from '#core/rate-limiter.js';
+export {
+  type AgentAccessUtf8Truncation,
+  fitAgentAccessResponseToCeiling,
+  reducePagedAgentAccessResponse,
+  serializedAgentAccessEnvelopeByteLength,
+  truncateAgentAccessUtf8,
+} from '#core/response.js';
 export {
   type AgentAccessTool,
   type AgentAccessToolCall,

package/src/presentation/mcp-server.test.ts

@@ -1,9 +1,15 @@
 import {Client} from '@modelcontextprotocol/sdk/client/index.js';
 import {InMemoryTransport} from '@modelcontextprotocol/sdk/inMemory.js';
 import {CallToolResultSchema} from '@modelcontextprotocol/sdk/types.js';
+import type {AnnotationsInterModuleClient} from '@shipfox/annotations-dto/inter-module';
 import {agentAccessEnvelopeSchema} from '@shipfox/api-agent-access-dto';
 import type {AgentAccessContext} from '@shipfox/api-auth-context';
+import type {DefinitionsInterModuleClient} 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 {agentAccessSuccess} from '#core/envelope.js';
+import {createAgentAccessTools} from '#core/paged-tools.js';
 import {createAgentAccessRateLimiter} from '#core/rate-limiter.js';
 import {createAgentAccessFixtureTool} from '#core/tools.js';
 import {AGENT_ACCESS_PACKAGE_VERSION} from '#version.js';
@@ -71,6 +77,35 @@ describe('buildAgentAccessMcpServer', () => {
     ]);
   });
 
+  test('rejects multibyte input at the MCP boundary before calling a producer', async () => {
+    const listWorkflowRuns = vi.fn();
+    const tool = createAgentAccessTools({
+      projects: {} as unknown as ProjectsModuleClient,
+      definitions: {} as unknown as DefinitionsInterModuleClient,
+      workflows: {listWorkflowRuns} as unknown as WorkflowsModuleClient,
+      annotations: {} as unknown as AnnotationsInterModuleClient,
+      triggers: {} as unknown as TriggersInterModuleClient,
+    }).find((candidate) => candidate.name === 'list_workflow_runs');
+    if (!tool) throw new Error('Expected list_workflow_runs tool');
+
+    const {client, close} = await connectClient(createAgentAccessRateLimiter(), [tool]);
+    const result = await client.callTool(
+      {
+        name: 'list_workflow_runs',
+        arguments: {
+          project_id: '00000000-0000-4000-8000-000000000001',
+          trigger_source: '🙂'.repeat(129),
+        },
+      },
+      CallToolResultSchema,
+    );
+    await close();
+
+    expect(result.isError).toBe(true);
+    expect(result.structuredContent).toEqual({ok: false, error: {code: 'invalid-request'}});
+    expect(listWorkflowRuns).not.toHaveBeenCalled();
+  });
+
   test('records only the exception when serializing a tool result fails', async () => {
     const recordCall = vi.fn();
     const fixture = createAgentAccessFixtureTool();
@@ -125,6 +160,29 @@ describe('buildAgentAccessMcpServer', () => {
     ]);
   });
 
+  test('converts an oversized unpaged success into a bounded content-too-large error', async () => {
+    const fixture = createAgentAccessFixtureTool();
+    const oversizedTool = {
+      ...fixture,
+      name: 'oversized_fixture',
+      execute: () => agentAccessSuccess({message: 'x'.repeat(128 * 1024)}),
+    };
+    const {client, close} = await connectClient(createAgentAccessRateLimiter(), [oversizedTool]);
+
+    const result = await client.callTool(
+      {name: 'oversized_fixture', arguments: {message: 'ignored'}},
+      CallToolResultSchema,
+    );
+    await close();
+
+    expect(result.isError).toBe(true);
+    expect(result.structuredContent).toEqual({
+      ok: false,
+      error: {code: 'content-too-large'},
+    });
+    expect(agentAccessEnvelopeSchema.safeParse(result.structuredContent).success).toBe(true);
+  });
+
   test('does not count tool discovery against the credential window', async () => {
     const limiter = createAgentAccessRateLimiter({limit: 1, now: () => 1_000});
     const {client, close} = await connectClient(limiter);

package/src/presentation/mcp-server.ts

@@ -11,6 +11,7 @@ import {logger} from '@shipfox/node-opentelemetry';
 import {AGENT_ACCESS_MCP_INSTRUCTIONS, AGENT_ACCESS_MCP_SERVER_NAME} from '#constants.js';
 import {agentAccessError, serializeAgentAccessEnvelope} from '#core/envelope.js';
 import {type AgentAccessRateLimiter, createAgentAccessRateLimiter} from '#core/rate-limiter.js';
+import {fitAgentAccessResponseToCeiling} from '#core/response.js';
 import {
   type AgentAccessTool,
   type AgentAccessToolMap,
@@ -124,6 +125,16 @@ async function executeAgentAccessTool(params: {
   recordCall: AgentAccessToolCallRecorder;
 }): Promise<CallToolResult> {
   try {
+    if (params.tool.validateInput?.(params.input) === false) {
+      recordToolCall(params.recordCall, {
+        tool: params.tool.name,
+        outcome: 'invalid-request',
+        errorCode: 'invalid-request',
+        context: params.context,
+      });
+      return toolResult(agentAccessError('invalid-request'), true);
+    }
+
     const response = await params.tool.execute({context: params.context, arguments: params.input});
     const envelope = agentAccessEnvelopeSchema.safeParse(response);
     if (!envelope.success) {
@@ -136,12 +147,23 @@ async function executeAgentAccessTool(params: {
       return toolResult(agentAccessError('invalid-tool-response'), true);
     }
 
-    const outcome: AgentAccessToolCallOutcome = envelope.data.ok ? 'success' : 'tool-error';
-    const result = toolResult(envelope.data, !envelope.data.ok);
+    if (envelope.data.ok && params.tool.validateResult?.(envelope.data.result) === false) {
+      recordToolCall(params.recordCall, {
+        tool: params.tool.name,
+        outcome: 'exception',
+        errorCode: 'invalid-tool-response',
+        context: params.context,
+      });
+      return toolResult(agentAccessError('invalid-tool-response'), true);
+    }
+
+    const boundedEnvelope = fitAgentAccessResponseToCeiling(envelope.data);
+    const outcome: AgentAccessToolCallOutcome = boundedEnvelope.ok ? 'success' : 'tool-error';
+    const result = toolResult(boundedEnvelope, !boundedEnvelope.ok);
     recordToolCall(params.recordCall, {
       tool: params.tool.name,
       outcome,
-      errorCode: envelope.data.ok ? 'none' : (envelope.data.error?.code ?? 'unknown'),
+      errorCode: boundedEnvelope.ok ? 'none' : (boundedEnvelope.error?.code ?? 'unknown'),
       context: params.context,
     });
     return result;

package/src/presentation/routes.ts

@@ -1,6 +1,11 @@
 import {StreamableHTTPServerTransport} from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import type {Transport} from '@modelcontextprotocol/sdk/shared/transport.js';
+import type {AnnotationsInterModuleClient} from '@shipfox/annotations-dto/inter-module';
 import {AUTH_AGENT_ACCESS, requireAgentAccessContext} from '@shipfox/api-auth-context';
+import type {DefinitionsInterModuleClient} 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 {reportError} from '@shipfox/node-error-monitoring';
 import {
   ClientError,
@@ -14,6 +19,7 @@ import {
 } from '@shipfox/node-fastify';
 import {logger} from '@shipfox/node-opentelemetry';
 import {AGENT_ACCESS_MCP_PATH, AGENT_ACCESS_PROTECTED_RESOURCE_METADATA_PATH} from '#constants.js';
+import {createAgentAccessTools} from '#core/paged-tools.js';
 import {type AgentAccessRateLimiter, createAgentAccessRateLimiter} from '#core/rate-limiter.js';
 import {type AgentAccessTool, createAgentAccessFixtureTool} from '#core/tools.js';
 import {recordAgentAccessAuthFailure} from '#metrics/index.js';
@@ -29,10 +35,15 @@ export interface CreateAgentAccessRoutesOptions {
   rateLimiter?: AgentAccessRateLimiter | undefined;
   recordCall?: AgentAccessToolCallRecorder | undefined;
   isOriginAllowed?: ((origin: string | undefined) => boolean) | undefined;
+  projects?: ProjectsModuleClient | undefined;
+  definitions?: DefinitionsInterModuleClient | undefined;
+  workflows?: WorkflowsModuleClient | undefined;
+  annotations?: AnnotationsInterModuleClient | undefined;
+  triggers?: TriggersInterModuleClient | undefined;
 }
 
 export function createAgentAccessRoutes(options: CreateAgentAccessRoutesOptions = {}): RouteGroup {
-  const tools = options.tools ?? [createAgentAccessFixtureTool()];
+  const tools = options.tools ?? toolsFromProducerClients(options);
   const rateLimiter = options.rateLimiter ?? createAgentAccessRateLimiter();
   const recordCall = options.recordCall ?? createAgentAccessToolCallRecorder();
   const originMatcher = options.isOriginAllowed ?? createAllowedOriginMatcher();
@@ -107,6 +118,31 @@ export function createAgentAccessRoutes(options: CreateAgentAccessRoutesOptions
   };
 }
 
+function toolsFromProducerClients(
+  options: CreateAgentAccessRoutesOptions,
+): readonly AgentAccessTool[] {
+  const {projects, definitions, workflows, annotations, triggers} = options;
+  if (
+    projects === undefined &&
+    definitions === undefined &&
+    workflows === undefined &&
+    annotations === undefined &&
+    triggers === undefined
+  ) {
+    return [createAgentAccessFixtureTool()];
+  }
+  if (
+    projects === undefined ||
+    definitions === undefined ||
+    workflows === undefined ||
+    annotations === undefined ||
+    triggers === undefined
+  ) {
+    throw new Error('Agent-access producer clients must be configured together');
+  }
+  return createAgentAccessTools({projects, definitions, workflows, annotations, triggers});
+}
+
 function methodNotAllowed(_request: FastifyRequest, reply: FastifyReply) {
   return reply.code(405).header('allow', 'POST').send({code: 'method-not-allowed'});
 }