Orchestration MCP

Instructions

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(),
  });