@shipfox/api-agent-access 21.0.0 → 21.1.0

package/src/core/paged-tools.ts

@@ -6,8 +6,6 @@ import {
   AGENT_ACCESS_DIAGNOSTIC_MAX_ITEMS,
   AGENT_ACCESS_DIAGNOSTIC_MESSAGE_MAX_BYTES,
   AGENT_ACCESS_DIAGNOSTIC_PATH_MAX_BYTES,
-  AGENT_ACCESS_TEXT_MAX_BYTES,
-  type AgentAccessEnvelopeDto,
   agentAccessOutputSchema,
   type GetRunAnnotationsInputDto,
   getRunAnnotationsInputJsonSchema,
@@ -45,17 +43,23 @@ import {
 import type {TriggersInterModuleClient} from '@shipfox/api-triggers-dto/inter-module';
 import type {WorkflowsModuleClient} from '@shipfox/api-workflows-dto/inter-module';
 import {isInterModuleKnownError} from '@shipfox/inter-module';
+import {encodeNumberIdCursor, encodeStringIdCursor} from '@shipfox/node-drizzle';
+import {agentAccessSuccess} from './envelope.js';
 import {
-  decodeNumberIdCursor,
-  decodeStringIdCursor,
-  decodeTimestampIdCursor,
-  encodeNumberIdCursor,
-  encodeStringIdCursor,
-  encodeTimestampIdCursor,
-} from '@shipfox/node-drizzle';
-import {agentAccessError, agentAccessSuccess} from './envelope.js';
-import {reducePagedAgentAccessResponse, truncateAgentAccessUtf8} from './response.js';
+  cap,
+  capNullable,
+  decodeNumberCursor,
+  decodeStringCursor,
+  decodeTimestampCursor,
+  encodeTimestampCursor,
+  invalidRequest,
+  notFound,
+  parseInput,
+  reducePage,
+  truncateAgentAccessUtf8,
+} from './tool-utils.js';
 import type {AgentAccessTool} from './tools.js';
+import {createAgentAccessWorkflowTools} from './workflow-tools.js';
 
 export interface AgentAccessPagedToolsOptions {
   projects: ProjectsModuleClient;
@@ -72,6 +76,7 @@ export function createAgentAccessTools(
     createListProjectsTool(options.projects),
     createListWorkflowDefinitionsTool(options.definitions),
     createListWorkflowRunsTool(options.projects, options.workflows),
+    ...createAgentAccessWorkflowTools(options.workflows),
     createGetRunAnnotationsTool(options.workflows, options.annotations),
     createListTriggerEventsTool(options.triggers),
   ];
@@ -316,12 +321,12 @@ async function resolveRunAttempt(
     ).attempt;
   }
 
-  const detail = await workflows.getWorkflowRunDetail({
+  const overview = await workflows.getWorkflowRunOverview({
     workspaceId: context.workspaceId,
     workflowRunId: input.run_id,
     attempt: input.attempt,
   });
-  return detail.run === null ? null : input.attempt;
+  return overview === null ? null : input.attempt;
 }
 
 function toProjectResult(project: {
@@ -578,15 +583,6 @@ function triggerEventFilters(input: ListTriggerEventsInputDto) {
   };
 }
 
-function reducePage(
-  envelope: AgentAccessEnvelopeDto,
-  itemKey: string,
-  items: readonly Record<string, unknown>[],
-  cursorForItem: (item: Record<string, unknown>, index: number) => string,
-): AgentAccessEnvelopeDto {
-  return reducePagedAgentAccessResponse({envelope, itemKey, items, cursorForItem});
-}
-
 function projectCursor(item: Record<string, unknown>): string {
   return encodeTimestampCursor(String(item.created_at), String(item.id));
 }
@@ -610,48 +606,3 @@ function annotationCursor(item: Record<string, unknown>): string {
 function triggerEventCursor(item: Record<string, unknown>): string {
   return encodeTimestampCursor(String(item.received_at), String(item.id));
 }
-
-function decodeTimestampCursor(
-  value: string | undefined,
-): {createdAt: string; id: string} | undefined {
-  if (value === undefined) return undefined;
-  const cursor = decodeTimestampIdCursor(value);
-  return cursor ? {createdAt: cursor.createdAt.toISOString(), id: cursor.id} : undefined;
-}
-
-function decodeStringCursor(value: string | undefined): {value: string; id: string} | undefined {
-  return value === undefined ? undefined : decodeStringIdCursor(value);
-}
-
-function decodeNumberCursor(value: string | undefined): {value: number; id: string} | undefined {
-  return value === undefined ? undefined : decodeNumberIdCursor(value);
-}
-
-function encodeTimestampCursor(createdAt: string, id: string): string {
-  return encodeTimestampIdCursor({createdAt: new Date(createdAt), id});
-}
-
-function cap(value: string, maxBytes = AGENT_ACCESS_TEXT_MAX_BYTES): string {
-  return truncateAgentAccessUtf8(value, maxBytes).value;
-}
-
-function capNullable(value: string | null, maxBytes = AGENT_ACCESS_TEXT_MAX_BYTES): string | null {
-  return value === null ? null : cap(value, maxBytes);
-}
-
-function invalidRequest(): AgentAccessEnvelopeDto {
-  return agentAccessError('invalid-request');
-}
-
-function notFound(): AgentAccessEnvelopeDto {
-  return agentAccessError('not-found');
-}
-
-interface SafeParseSchema<T> {
-  safeParse(value: unknown): {success: true; data: T} | {success: false};
-}
-
-function parseInput<T>(schema: SafeParseSchema<T>, value: unknown): T | undefined {
-  const parsed = schema.safeParse(value);
-  return parsed.success ? parsed.data : undefined;
-}

package/src/core/response.ts

@@ -46,6 +46,13 @@ export interface ReducePagedAgentAccessResponseParams {
   maxBytes?: number | undefined;
 }
 
+interface PagedResponseFitState {
+  emptyCandidate: AgentAccessEnvelopeDto;
+  emptyResult: Record<string, unknown>;
+  candidateBytes: readonly number[];
+  itemCursors: readonly string[];
+}
+
 /**
  * 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.
@@ -60,33 +67,68 @@ export function reducePagedAgentAccessResponse(
     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,
+  const producerResult = params.envelope.result;
+  const fitState = buildPagedResponseFitState(params, producerResult, initialBytes);
+  const itemCount = largestFittingItemCount(fitState.candidateBytes, params.items.length, maxBytes);
+  if (itemCount !== undefined) {
+    const nextCursor = itemCount === 0 ? null : fitState.itemCursors[itemCount - 1];
+    if (nextCursor === undefined && itemCount > 0) return agentAccessError('content-too-large');
+    return {
+      ...fitState.emptyCandidate,
       result: {
-        ...params.envelope.result,
-        [params.itemKey]: retained,
-        next_cursor: nextCursor,
+        ...fitState.emptyResult,
+        [params.itemKey]: params.items.slice(0, itemCount),
+        next_cursor: nextCursor ?? null,
       },
-      response_truncated: true,
-      response_total_bytes: initialBytes,
     };
-    if (serializedAgentAccessEnvelopeByteLength(candidate) <= maxBytes) return candidate;
   }
 
   return agentAccessError('content-too-large');
 }
 
+function buildPagedResponseFitState(
+  params: ReducePagedAgentAccessResponseParams,
+  producerResult: Record<string, unknown>,
+  initialBytes: number,
+): PagedResponseFitState {
+  const emptyResult = {...producerResult, [params.itemKey]: [], next_cursor: null};
+  const emptyCandidate: AgentAccessEnvelopeDto = {
+    ...params.envelope,
+    result: emptyResult,
+    response_truncated: true,
+    response_total_bytes: initialBytes,
+  };
+  const emptyCandidateBytes = serializedAgentAccessEnvelopeByteLength(emptyCandidate);
+  const nullCursorBytes = serializedJsonByteLength(null);
+  const candidateBytes: number[] = [emptyCandidateBytes];
+  const itemCursors: string[] = [];
+  let retainedItemBytes = 0;
+
+  for (const [index, item] of params.items.entries()) {
+    retainedItemBytes += serializedJsonByteLength(item) + (index === 0 ? 0 : 1);
+    const cursor = params.cursorForItem(item, index);
+    itemCursors.push(cursor);
+    candidateBytes.push(
+      emptyCandidateBytes + retainedItemBytes + serializedJsonByteLength(cursor) - nullCursorBytes,
+    );
+  }
+
+  return {emptyCandidate, emptyResult, candidateBytes, itemCursors};
+}
+
+function largestFittingItemCount(
+  candidateBytes: readonly number[],
+  itemCount: number,
+  maxBytes: number,
+): number | undefined {
+  const minimumItemCount = itemCount === 0 ? 0 : 1;
+  for (let count = itemCount; count >= minimumItemCount; count -= 1) {
+    const candidateByteLength = candidateBytes[count];
+    if (candidateByteLength !== undefined && candidateByteLength <= maxBytes) return count;
+  }
+  return undefined;
+}
+
 export function fitAgentAccessResponseToCeiling(
   envelope: AgentAccessEnvelopeDto,
   maxBytes = AGENT_ACCESS_RESPONSE_MAX_BYTES,
@@ -99,3 +141,9 @@ export function fitAgentAccessResponseToCeiling(
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+
+function serializedJsonByteLength(value: unknown): number {
+  const serialized = JSON.stringify(value);
+  if (serialized === undefined) throw new Error('Agent-access value is not serializable');
+  return utf8Encoder.encode(serialized).byteLength;
+}

package/src/core/tool-utils.ts

@@ -0,0 +1,109 @@
+import {
+  AGENT_ACCESS_TEXT_MAX_BYTES,
+  type AgentAccessEnvelopeDto,
+} from '@shipfox/api-agent-access-dto';
+import {
+  decodeNumberIdCursor,
+  decodeStringIdCursor,
+  decodeTimestampIdCursor,
+  encodeTimestampIdCursor,
+} from '@shipfox/node-drizzle';
+import {agentAccessError} from './envelope.js';
+import {reducePagedAgentAccessResponse, truncateAgentAccessUtf8} from './response.js';
+
+export {truncateAgentAccessUtf8};
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
+const DECIMAL_RE = /^\d+$/u;
+
+export interface SafeParseSchema<T> {
+  safeParse(value: unknown): {success: true; data: T} | {success: false};
+}
+
+export function parseInput<T>(schema: SafeParseSchema<T>, value: unknown): T | undefined {
+  const parsed = schema.safeParse(value);
+  return parsed.success ? parsed.data : undefined;
+}
+
+export function reducePage(
+  envelope: AgentAccessEnvelopeDto,
+  itemKey: string,
+  items: readonly Record<string, unknown>[],
+  cursorForItem: (item: Record<string, unknown>, index: number) => string,
+): AgentAccessEnvelopeDto {
+  return reducePagedAgentAccessResponse({envelope, itemKey, items, cursorForItem});
+}
+
+export function decodeTimestampCursor(
+  value: string | undefined,
+): {createdAt: string; id: string} | undefined {
+  if (value === undefined) return undefined;
+  const cursor = decodeTimestampIdCursor(value);
+  return cursor ? {createdAt: cursor.createdAt.toISOString(), id: cursor.id} : undefined;
+}
+
+export function decodeStringCursor(
+  value: string | undefined,
+): {value: string; id: string} | undefined {
+  return value === undefined ? undefined : decodeStringIdCursor(value);
+}
+
+export function decodeNumberCursor(
+  value: string | undefined,
+): {value: number; id: string} | undefined {
+  const cursor = value === undefined ? undefined : decodeNumberIdCursor(value);
+  return cursor !== undefined && Number.isSafeInteger(cursor.value) ? cursor : undefined;
+}
+
+export function validateBoundedNumberCursor(
+  value: string | undefined,
+  bounds: {minValue: number; maxValue: number},
+): string | undefined {
+  if (value === undefined) return undefined;
+  const cursor = decodeNumberCursor(value);
+  return cursor !== undefined &&
+    UUID_RE.test(cursor.id) &&
+    Number.isSafeInteger(cursor.value) &&
+    cursor.value >= bounds.minValue &&
+    cursor.value <= bounds.maxValue
+    ? value
+    : undefined;
+}
+
+export function validateBoundedPositionCursor(
+  value: string | undefined,
+  maxValue: number,
+): string | undefined {
+  if (value === undefined) return undefined;
+  const cursor = decodeStringCursor(value);
+  if (cursor === undefined || !UUID_RE.test(cursor.id) || !DECIMAL_RE.test(cursor.value)) {
+    return undefined;
+  }
+  const position = Number(cursor.value);
+  return Number.isSafeInteger(position) && position >= 0 && position <= maxValue
+    ? value
+    : undefined;
+}
+
+export function encodeTimestampCursor(createdAt: string, id: string): string {
+  return encodeTimestampIdCursor({createdAt: new Date(createdAt), id});
+}
+
+export function cap(value: string, maxBytes = AGENT_ACCESS_TEXT_MAX_BYTES): string {
+  return truncateAgentAccessUtf8(value, maxBytes).value;
+}
+
+export function capNullable(
+  value: string | null,
+  maxBytes = AGENT_ACCESS_TEXT_MAX_BYTES,
+): string | null {
+  return value === null ? null : cap(value, maxBytes);
+}
+
+export function invalidRequest(): AgentAccessEnvelopeDto {
+  return agentAccessError('invalid-request');
+}
+
+export function notFound(): AgentAccessEnvelopeDto {
+  return agentAccessError('not-found');
+}