get_event_artifact

Retrieve sanitized event artifacts from orchestrated coding-agent runs using run_id, sequence number, and JSON Pointer field_path to access specific data points.

Instructions

Read a sanitized event artifact by run_id, seq, and JSON Pointer field_path.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`run_id`	Yes
`seq`	Yes
`field_path`	Yes
`offset`	No
`limit`	No

Implementation Reference

src/tools/get-event-artifact.ts:11-28 (registration)

Registers the 'get_event_artifact' MCP tool with the server, defining its name, description, input/output schemas, and the async handler that calls manager.getEventArtifact()

export function registerGetEventArtifactTool(server: McpServer, manager: RunManager): void {
  server.registerTool(
    'get_event_artifact',
    {
      description: 'Read a sanitized event artifact by run_id, seq, and JSON Pointer field_path.',
      inputSchema: getEventArtifactSchema,
      outputSchema: getEventArtifactResultSchema,
    },
    async (args) => {
      try {
        const result = await manager.getEventArtifact(args);
        return asToolResult(result);
      } catch (error) {
        return asToolError(String(error));
      }
    },
  );
}

src/core/run-manager.ts:260-280 (handler)

Main handler method in RunManager that processes get_event_artifact requests. Delegates to storage.readEventArtifact() for active runs or storage.readEventArtifactById() for persisted runs.

async getEventArtifact(input: GetEventArtifactInput): Promise<GetEventArtifactResult> {
  const managed = this.findManagedRun(input.run_id);
  if (managed) {
    return this.storage.readEventArtifact(
      managed.record.cwd,
      managed.record.runId,
      input.seq,
      input.field_path,
      input.offset ?? 0,
      input.limit ?? 65536,
    );
  }

  return this.storage.readEventArtifactById(
    input.run_id,
    input.seq,
    input.field_path,
    input.offset ?? 0,
    input.limit ?? 65536,
  );
}

src/core/storage.ts:238-283 (handler)

Core storage implementation that reads artifact data from manifest files and chunked binary files, returning the artifact content with metadata (mime type, encoding, offset, has_more, etc.)

async readEventArtifact(
  cwd: string,
  runId: string,
  seq: number,
  fieldPath: string,
  offset: number,
  limit: number,
): Promise<GetEventArtifactResult> {
  const manifest = await this.readArtifactManifest(cwd, runId, seq);
  const field = manifest.fields[fieldPath];
  if (!field) {
    throw new Error(
      `No artifact for field_path ${fieldPath}. Available field paths: ${Object.keys(manifest.fields).join(', ') || '(none)'}`,
    );
  }

  const eventDir = path.join(this.getArtifactsDir(cwd, runId), eventDirName(seq, manifest.event_type));
  const buffer = await readFieldBuffer(eventDir, field, offset, limit);
  return {
    run_id: runId,
    seq,
    field_path: fieldPath,
    mime: field.mime,
    encoding: field.encoding,
    relpath: field.relpath,
    total_bytes: field.total_bytes,
    offset,
    returned_bytes: buffer.length,
    has_more: offset + buffer.length < field.total_bytes,
    content: buffer.toString('utf8'),
  };
}

async readEventArtifactById(
  runId: string,
  seq: number,
  fieldPath: string,
  offset: number,
  limit: number,
): Promise<GetEventArtifactResult> {
  const cwd = await this.resolveRunCwd(runId);
  if (!cwd) {
    throw new Error(`Unknown run_id: ${runId}`);
  }
  return this.readEventArtifact(cwd, runId, seq, fieldPath, offset, limit);
}

src/core/schemas.ts:144-150 (schema)

Input schema for get_event_artifact: validates run_id, seq, field_path, and optional offset/limit parameters

export const getEventArtifactSchema = z.object({
  run_id: z.string().min(1),
  seq: z.number().int().min(1),
  field_path: z.string().min(1),
  offset: z.number().int().min(0).default(0),
  limit: z.number().int().min(1).max(262144).default(65536),
});

src/core/schemas.ts:243-255 (schema)

Output schema for get_event_artifact result: defines run_id, seq, field_path, mime, encoding, relpath, total_bytes, offset, returned_bytes, has_more, and content fields

export const getEventArtifactResultSchema = z.object({
  run_id: z.string(),
  seq: z.number().int().min(1),
  field_path: z.string(),
  mime: z.string(),
  encoding: z.string(),
  relpath: z.string(),
  total_bytes: z.number().int().min(0),
  offset: z.number().int().min(0),
  returned_bytes: z.number().int().min(0),
  has_more: z.boolean(),
  content: z.string(),
});

Orchestration MCP