@foundation0/git 1.2.4 → 1.3.0

package/mcp/src/server.ts

@@ -16,6 +16,8 @@ type ToolInvocationPayload = {
   [key: string]: unknown
 }
 
+type McpToolOutputFormat = 'terse' | 'debug'
+
 type BatchToolCall = {
   tool: string
   args?: unknown[]
@@ -32,8 +34,7 @@ type BatchResult = {
   index: number
   tool: string
   isError: boolean
-  data: unknown
-}
+} & (McpTerseOk | McpTerseErr)
 
 type ToolDefinition = {
   name: string
@@ -44,21 +45,205 @@ type ToolDefinition = {
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   typeof value === 'object' && value !== null && !Array.isArray(value)
 
+const tryParseJsonObject = (value: string): unknown => {
+  const trimmed = value.trim()
+  if (!trimmed) return {}
+
+  try {
+    return JSON.parse(trimmed) as unknown
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    throw new Error(`Invalid args JSON: ${message}`)
+  }
+}
+
+const normalizeArgumentPayload = (payload: unknown): unknown => {
+  if (typeof payload === 'string' || payload instanceof String) {
+    const parsed = tryParseJsonObject(String(payload))
+    if (!isRecord(parsed)) {
+      const kind = Array.isArray(parsed) ? 'array' : typeof parsed
+      throw new Error(`Invalid args: expected a JSON object, got ${kind}`)
+    }
+    return parsed
+  }
+
+  return payload
+}
+
+const toTrimmedString = (value: unknown): string => (value === null || value === undefined ? '' : String(value)).trim()
+
+const toPositiveInteger = (value: unknown): number | null => {
+  if (typeof value === 'number' && Number.isFinite(value) && value > 0) {
+    return Math.floor(value)
+  }
+
+  if (typeof value !== 'string') return null
+
+  const trimmed = value.trim()
+  if (!trimmed) return null
+  const parsed = Number(trimmed)
+  if (!Number.isFinite(parsed) || parsed <= 0) return null
+  return Math.floor(parsed)
+}
+
+const pickFirst = <T>(...candidates: Array<T | null | undefined>): T | null => {
+  for (const candidate of candidates) {
+    if (candidate !== null && candidate !== undefined) return candidate
+  }
+  return null
+}
+
+const pickRecord = (value: unknown): Record<string, unknown> => (isRecord(value) ? (value as Record<string, unknown>) : {})
+
+const parseOutputFormat = (value: unknown): McpToolOutputFormat | null => {
+  if (value === null || value === undefined) return null
+  const raw = toTrimmedString(value).toLowerCase()
+  if (!raw) return null
+  if (raw === 'debug') return 'debug'
+  if (raw === 'terse') return 'terse'
+  return null
+}
+
+const extractOutputControls = (payload: unknown): { format: McpToolOutputFormat | null } => {
+  const normalized = normalizeArgumentPayload(payload)
+  if (!isRecord(normalized)) {
+    return { format: null }
+  }
+
+  const topLevelFormat = parseOutputFormat(normalized.format)
+  const optionsFormat = parseOutputFormat(pickRecord(normalized.options).format)
+
+  // Support either { format:"debug" } or { options:{ format:"debug" } }.
+  return { format: pickFirst(topLevelFormat, optionsFormat) }
+}
+
+type McpTerseOk = {
+  ok: true
+  data: unknown
+  meta: {
+    status: number
+  }
+  debug?: unknown
+}
+
+type McpTerseErr = {
+  ok: false
+  error: {
+    code: string
+    status?: number
+    message: string
+    details?: unknown
+    hint?: string
+    retryable: boolean
+  }
+  meta?: {
+    status?: number
+  }
+  debug?: unknown
+}
+
+const httpErrorCodeForStatus = (status: number): string => {
+  if (status === 400) return 'HTTP_BAD_REQUEST'
+  if (status === 401) return 'HTTP_UNAUTHORIZED'
+  if (status === 403) return 'HTTP_FORBIDDEN'
+  if (status === 404) return 'HTTP_NOT_FOUND'
+  if (status === 409) return 'HTTP_CONFLICT'
+  if (status === 422) return 'HTTP_UNPROCESSABLE_ENTITY'
+  if (status === 429) return 'HTTP_RATE_LIMITED'
+  if (status >= 500) return 'HTTP_SERVER_ERROR'
+  if (status >= 400) return 'HTTP_ERROR'
+  return 'UNKNOWN'
+}
+
+const buildErrorMessage = (status: number | undefined, body: unknown): string => {
+  if (typeof body === 'string') {
+    const trimmed = body.trim()
+    if (trimmed) {
+      const firstLine = trimmed.split(/\r?\n/, 1)[0]
+      return firstLine.length > 0 ? firstLine : trimmed
+    }
+  }
+
+  if (isRecord(body) && typeof body.message === 'string' && body.message.trim()) {
+    return body.message.trim()
+  }
+
+  if (typeof status === 'number') {
+    return `HTTP ${status}`
+  }
+
+  return 'Request failed'
+}
+
+const toMcpEnvelope = (
+  result: GitServiceApiExecutionResult,
+  format: McpToolOutputFormat,
+): { isError: boolean; envelope: McpTerseOk | McpTerseErr } => {
+  const sanitized = redactSecretsForMcpOutput(result)
+
+  if (result.ok && result.status < 400) {
+    const envelope: McpTerseOk = {
+      ok: true,
+      data: result.body,
+      meta: {
+        status: result.status,
+      },
+      ...(format === 'debug' ? { debug: sanitized } : {}),
+    }
+
+    return { isError: false, envelope: redactSecretsForMcpOutput(envelope) as McpTerseOk }
+  }
+
+  const status = result.status
+  const envelope: McpTerseErr = {
+    ok: false,
+    error: {
+      code: httpErrorCodeForStatus(status),
+      status,
+      message: buildErrorMessage(status, result.body),
+      details: result.body,
+      retryable: status >= 500 || status === 429,
+    },
+    meta: {
+      status,
+    },
+    ...(format === 'debug' ? { debug: sanitized } : {}),
+  }
+
+  return { isError: true, envelope: redactSecretsForMcpOutput(envelope) as McpTerseErr }
+}
+
+const toMcpThrownErrorEnvelope = (error: unknown): McpTerseErr => ({
+  ok: false,
+  error: {
+    code: 'TOOL_ERROR',
+    message: redactSecretsInText(error instanceof Error ? error.message : String(error)),
+    retryable: false,
+  },
+})
+
 const normalizePayload = (payload: unknown): { args: string[]; options: Record<string, unknown> } => {
-  if (!isRecord(payload)) {
+  const normalized = normalizeArgumentPayload(payload)
+
+  if (normalized === null || normalized === undefined) {
     return {
       args: [],
       options: {},
     }
   }
 
-  const explicitArgs = Array.isArray(payload.args) ? payload.args : undefined
-  const explicitOptions = isRecord(payload.options) ? payload.options : undefined
+  if (!isRecord(normalized)) {
+    const kind = Array.isArray(normalized) ? 'array' : typeof normalized
+    throw new Error(`Invalid args: expected a JSON object, got ${kind}`)
+  }
+
+  const explicitArgs = Array.isArray(normalized.args) ? normalized.args : undefined
+  const explicitOptions = isRecord(normalized.options) ? normalized.options : undefined
 
   const args = explicitArgs ? explicitArgs.map((entry) => String(entry)) : []
   const options: Record<string, unknown> = explicitOptions ? { ...explicitOptions } : {}
 
-  for (const [key, value] of Object.entries(payload)) {
+  for (const [key, value] of Object.entries(normalized)) {
     if (key === 'args' || key === 'options') {
       continue
     }
@@ -74,6 +259,17 @@ const normalizePayload = (payload: unknown): { args: string[]; options: Record<s
   }
 }
 
+const OMITTED_OPTION_KEYS = new Set(['format'])
+
+const stripMcpOnlyOptions = (options: Record<string, unknown>): Record<string, unknown> => {
+  const next: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(options)) {
+    if (OMITTED_OPTION_KEYS.has(key)) continue
+    next[key] = value
+  }
+  return next
+}
+
 const normalizeBatchToolCall = (
   call: unknown,
   index: number,
@@ -107,22 +303,23 @@ const normalizeBatchToolCall = (
 }
 
 const normalizeBatchPayload = (payload: unknown): BatchToolCallPayload => {
-  if (!isRecord(payload)) {
+  const normalized = normalizeArgumentPayload(payload)
+  if (!isRecord(normalized)) {
     throw new Error('Batch tool call requires an object payload')
   }
 
-  if (!Array.isArray(payload.calls)) {
+  if (!Array.isArray(normalized.calls)) {
     throw new Error('Batch tool call requires a "calls" array')
   }
 
-  const calls = payload.calls.map((call, index) => normalizeBatchToolCall(call, index))
+  const calls = (normalized.calls as unknown[]).map((call, index) => normalizeBatchToolCall(call, index))
 
   return {
     calls: calls.map(({ tool, payload }) => ({
       tool,
       ...payload,
     })),
-    continueOnError: Boolean(payload.continueOnError),
+    continueOnError: Boolean((normalized as Record<string, unknown>).continueOnError),
   }
 }
 
@@ -165,26 +362,216 @@ export type GitMcpServerInstance = {
 const buildToolName = (tool: ToolDefinition, prefix?: string): string =>
   prefix ? `${prefix}.${tool.name}` : tool.name
 
+const isLogsForRunTailTool = (toolName: string): boolean => toolName.endsWith('jobs.logsForRunTail')
+const isArtifactsByRunTool = (toolName: string): boolean => toolName.endsWith('runs.artifacts')
+const isDiagnoseLatestFailureTool = (toolName: string): boolean =>
+  toolName.endsWith('diagnoseLatestFailure') && toolName.includes('.actions.')
+
+const buildGenericToolSchema = (): Record<string, unknown> => ({
+  type: 'object',
+  additionalProperties: true,
+  properties: {
+    args: {
+      type: 'array',
+      items: { type: 'string' },
+      description: 'Positional arguments for the git API method (strings are safest).',
+    },
+    options: {
+      type: 'object',
+      additionalProperties: true,
+      description: 'Method options (query/headers/body payload). Extra top-level keys are merged into options.',
+    },
+    format: {
+      type: 'string',
+      enum: ['terse', 'debug'],
+      description: 'Output format. Default: "terse". Use "debug" to include request/mapping/headers.',
+    },
+  },
+})
+
+const buildArtifactsByRunSchema = (): Record<string, unknown> => ({
+  type: 'object',
+  additionalProperties: true,
+  properties: {
+    owner: {
+      type: 'string',
+      description: 'Repository owner/org. Optional if the server was started with a default owner.',
+    },
+    repo: {
+      type: 'string',
+      description: 'Repository name. Optional if the server was started with a default repo.',
+    },
+    runId: {
+      description: 'Workflow run id (alias: run_id).',
+      anyOf: [{ type: 'integer', minimum: 1 }, { type: 'string' }],
+    },
+    run_id: {
+      description: 'Alias for runId.',
+      anyOf: [{ type: 'integer', minimum: 1 }, { type: 'string' }],
+    },
+    format: {
+      type: 'string',
+      enum: ['terse', 'debug'],
+      description: 'Output format. Default: "terse". Use "debug" to include request/mapping/headers.',
+    },
+    // Legacy positional forms:
+    // - Preferred by humans/LLMs: [owner, repo, runId]
+    // - Back-compat with the underlying helper signature: [runId, owner, repo]
+    args: {
+      type: 'array',
+      items: {},
+      description:
+        'Legacy positional form. Prefer named params. If used, pass [owner, repo, runId] (recommended) or the legacy [runId, owner, repo]. You can also pass only [runId] if defaults are configured.',
+    },
+    options: {
+      type: 'object',
+      additionalProperties: true,
+      description: 'Options object (query/headers/body payload). Extra top-level keys are merged into options.',
+    },
+  },
+  anyOf: [{ required: ['runId'] }, { required: ['run_id'] }, { required: ['args'] }],
+})
+
+const buildLogsForRunTailSchema = (): Record<string, unknown> => ({
+  type: 'object',
+  additionalProperties: true,
+  properties: {
+    // Preferred named form (no positional confusion).
+    owner: {
+      type: 'string',
+      description: 'Repository owner/org. Optional if the server was started with a default owner.',
+    },
+    repo: {
+      type: 'string',
+      description: 'Repository name. Optional if the server was started with a default repo.',
+    },
+    headSha: {
+      type: 'string',
+      description: 'Commit SHA for the run (alias: head_sha).',
+    },
+    head_sha: {
+      type: 'string',
+      description: 'Alias for headSha.',
+    },
+    runNumber: {
+      type: 'integer',
+      minimum: 1,
+      description: 'Workflow run_number (alias: run_number).',
+    },
+    run_number: {
+      type: 'integer',
+      minimum: 1,
+      description: 'Alias for runNumber.',
+    },
+    maxLines: {
+      type: 'integer',
+      minimum: 1,
+      description: 'Max lines to return from the end of the logs.',
+    },
+    maxBytes: {
+      type: 'integer',
+      minimum: 1,
+      description: 'Max bytes to return from the end of the logs.',
+    },
+    contains: {
+      type: 'string',
+      description: 'If set, only return log lines containing this substring.',
+    },
+    format: {
+      type: 'string',
+      enum: ['terse', 'debug'],
+      description: 'Output format. Default: "terse". Use "debug" to include request/mapping/headers.',
+    },
+
+    // Legacy / compatibility: allow calling with positional args.
+    args: {
+      type: 'array',
+      items: {},
+      description:
+        'Legacy positional form. Preferred is named params. If used, pass [headSha, runNumber] (or the legacy-mistake [owner, repo] with options.headSha/options.runNumber).',
+    },
+    options: {
+      type: 'object',
+      additionalProperties: true,
+      description:
+        'Options object. Supports owner/repo, maxLines/maxBytes/contains, and format. Extra top-level keys are merged into options.',
+    },
+  },
+  anyOf: [
+    { required: ['headSha', 'runNumber'] },
+    { required: ['head_sha', 'run_number'] },
+    { required: ['headSha', 'run_number'] },
+    { required: ['head_sha', 'runNumber'] },
+  ],
+})
+
+const buildDiagnoseLatestFailureSchema = (): Record<string, unknown> => ({
+  type: 'object',
+  additionalProperties: true,
+  properties: {
+    owner: {
+      type: 'string',
+      description: 'Repository owner/org. Optional if the server was started with a default owner.',
+    },
+    repo: {
+      type: 'string',
+      description: 'Repository name. Optional if the server was started with a default repo.',
+    },
+    workflowName: {
+      type: 'string',
+      description: 'Optional filter: match failing runs by name/display_title (case-insensitive substring).',
+    },
+    limit: {
+      type: 'integer',
+      minimum: 1,
+      description: 'How many tasks/runs to fetch before filtering (default: 50).',
+    },
+    maxLines: {
+      type: 'integer',
+      minimum: 1,
+      description: 'Max lines to return from the end of the logs (default: 200).',
+    },
+    maxBytes: {
+      type: 'integer',
+      minimum: 1,
+      description: 'Max bytes to return from the end of the logs.',
+    },
+    contains: {
+      type: 'string',
+      description: 'If set, only return log lines containing this substring.',
+    },
+    format: {
+      type: 'string',
+      enum: ['terse', 'debug'],
+      description: 'Output format. Default: "terse". Use "debug" to include request/mapping/headers.',
+    },
+    args: {
+      type: 'array',
+      items: { type: 'string' },
+      description: 'Legacy positional form: [owner, repo] plus options.workflowName/maxLines/etc.',
+    },
+    options: {
+      type: 'object',
+      additionalProperties: true,
+      description: 'Options object. Extra top-level keys are merged into options.',
+    },
+  },
+})
+
+const buildToolInputSchema = (tool: ToolDefinition): Record<string, unknown> =>
+  isLogsForRunTailTool(tool.name)
+    ? buildLogsForRunTailSchema()
+    : isArtifactsByRunTool(tool.name)
+      ? buildArtifactsByRunSchema()
+      : isDiagnoseLatestFailureTool(tool.name)
+        ? buildDiagnoseLatestFailureSchema()
+      : buildGenericToolSchema()
+
 const buildToolList = (tools: ToolDefinition[], batchToolName: string, prefix?: string) => {
   const toolNames = tools.map((tool) => ({
     name: buildToolName(tool, prefix),
     description: `Call git API method ${tool.path.join('.')}`,
-    inputSchema: {
-      type: 'object',
-      additionalProperties: true,
-      properties: {
-        args: {
-          type: 'array',
-          items: { type: 'string' },
-          description: 'Positional path arguments for the git API method',
-        },
-        options: {
-          type: 'object',
-          additionalProperties: true,
-          description: 'Method options (for query, headers, payload/body/json/data)',
-        },
-      },
-    },
+    inputSchema: buildToolInputSchema(tool),
   }))
 
   const batchTool = {
@@ -216,6 +603,11 @@ const buildToolList = (tools: ToolDefinition[], batchToolName: string, prefix?:
                 additionalProperties: true,
                 description: 'Tool invocation options',
               },
+              format: {
+                type: 'string',
+                enum: ['terse', 'debug'],
+                description: 'Per-call output format (default: "terse").',
+              },
             },
             required: ['tool'],
           },
@@ -226,6 +618,11 @@ const buildToolList = (tools: ToolDefinition[], batchToolName: string, prefix?:
           description: 'Whether to continue when a call in the batch fails',
           default: false,
         },
+        format: {
+          type: 'string',
+          enum: ['terse', 'debug'],
+          description: 'Default output format for calls that do not specify one (default: "terse").',
+        },
       },
       required: ['calls'],
     },
@@ -242,15 +639,174 @@ const invokeTool = async (
   payload: unknown,
 ): Promise<GitServiceApiExecutionResult> => {
   const { args, options } = normalizePayload(payload)
+  const cleanedOptions = stripMcpOnlyOptions(options)
   const invocationArgs: unknown[] = args
 
-  if (Object.keys(options).length > 0) {
-    invocationArgs.push(options)
+  if (Object.keys(cleanedOptions).length > 0) {
+    invocationArgs.push(cleanedOptions)
   }
 
   return tool.method(...invocationArgs)
 }
 
+const pickArgsFromNormalizedPayload = (normalized: unknown, record: Record<string, unknown>): unknown[] => {
+  if (Array.isArray(normalized)) {
+    return normalized
+  }
+  return Array.isArray(record.args) ? record.args : []
+}
+
+const pickNestedRecord = (value: unknown): Record<string, unknown> => (isRecord(value) ? (value as Record<string, unknown>) : {})
+
+const normalizeQueryRecord = (query: unknown): Record<string, unknown> => {
+  if (isRecord(query)) {
+    return query
+  }
+
+  if (!Array.isArray(query)) {
+    return {}
+  }
+
+  const merged: Record<string, unknown> = {}
+
+  for (const entry of query) {
+    if (!isRecord(entry)) continue
+
+    const name = typeof entry.name === 'string' ? entry.name.trim() : ''
+    if (name) {
+      merged[name] = entry.value
+      continue
+    }
+
+    // Support [{ headSha: "..." }, { runNumber: 11 }] style arrays.
+    for (const [key, value] of Object.entries(entry)) {
+      if (value !== undefined) merged[key] = value
+    }
+  }
+
+  return merged
+}
+
+const invokeLogsForRunTailTool = async (tool: ToolDefinition, payload: unknown): Promise<GitServiceApiExecutionResult> => {
+  const normalized = normalizeArgumentPayload(payload)
+  const record = isRecord(normalized) ? normalized : {}
+  const args = pickArgsFromNormalizedPayload(normalized, record)
+  const options = pickRecord(record.options)
+  const query = normalizeQueryRecord(options.query)
+  const data = pickNestedRecord(options.data)
+
+  const headShaNamed = toTrimmedString(
+    pickFirst(
+      record.headSha,
+      record.head_sha,
+      options.headSha,
+      options.head_sha,
+      query.headSha,
+      query.head_sha,
+      data.headSha,
+      data.head_sha,
+    ),
+  )
+  const runNumberNamed = pickFirst(
+    toPositiveInteger(pickFirst(record.runNumber, record.run_number, options.runNumber, options.run_number)),
+    toPositiveInteger(pickFirst(query.runNumber, query.run_number, data.runNumber, data.run_number)),
+    null,
+  )
+
+  // Positional preferred legacy: [headSha, runNumber]
+  const headShaPositional = args.length >= 1 ? toTrimmedString(args[0]) : ''
+  const runNumberPositional = args.length >= 2 ? toPositiveInteger(args[1]) : null
+
+  // Legacy-mistake support: args=[owner, repo], options has headSha/runNumber.
+  const shouldTreatArgsAsOwnerRepo =
+    args.length >= 2 &&
+    (!headShaPositional || !runNumberPositional) &&
+    Boolean(headShaNamed) &&
+    Boolean(runNumberNamed)
+
+  const ownerFromArgs = shouldTreatArgsAsOwnerRepo ? toTrimmedString(args[0]) : ''
+  const repoFromArgs = shouldTreatArgsAsOwnerRepo ? toTrimmedString(args[1]) : ''
+
+  const owner =
+    toTrimmedString(pickFirst(record.owner, options.owner, query.owner, data.owner, ownerFromArgs)) || undefined
+  const repo = toTrimmedString(pickFirst(record.repo, options.repo, query.repo, data.repo, repoFromArgs)) || undefined
+
+  const sha = toTrimmedString(pickFirst(headShaNamed || null, headShaPositional || null)) || ''
+  const run = pickFirst(runNumberNamed, runNumberPositional) ?? null
+
+  if (!sha || !run) {
+    throw new Error(
+      'headSha (string) and runNumber (positive integer) are required. Preferred invocation: { owner, repo, headSha, runNumber, maxLines }. (Compatibility: options.query.{headSha,runNumber} is also accepted.)',
+    )
+  }
+
+  const containsFromQuery = typeof query.contains === 'string' ? query.contains : undefined
+  const maxLinesFromQuery = toPositiveInteger(query.maxLines)
+  const maxBytesFromQuery = toPositiveInteger(query.maxBytes)
+
+  const cleanedOptions = stripMcpOnlyOptions({
+    ...options,
+    ...(containsFromQuery ? { contains: containsFromQuery } : {}),
+    ...(maxLinesFromQuery ? { maxLines: maxLinesFromQuery } : {}),
+    ...(maxBytesFromQuery ? { maxBytes: maxBytesFromQuery } : {}),
+    ...(owner ? { owner } : {}),
+    ...(repo ? { repo } : {}),
+  })
+
+  return tool.method(sha, run, cleanedOptions)
+}
+
+const invokeArtifactsByRunTool = async (
+  tool: ToolDefinition,
+  payload: unknown,
+): Promise<GitServiceApiExecutionResult> => {
+  const normalized = normalizeArgumentPayload(payload)
+  const record = isRecord(normalized) ? normalized : {}
+  const args = pickArgsFromNormalizedPayload(normalized, record)
+  const options = pickRecord(record.options)
+
+  const runIdNamed = toTrimmedString(pickFirst(record.runId, record.run_id, options.runId, options.run_id)) || ''
+
+  const a0 = args.length >= 1 ? toTrimmedString(args[0]) : ''
+  const a1 = args.length >= 2 ? toTrimmedString(args[1]) : ''
+  const a2 = args.length >= 3 ? toTrimmedString(args[2]) : ''
+
+  // Heuristic:
+  // - If named runId is set, use it.
+  // - Else if args look like [owner, repo, runId], use that.
+  // - Else treat args as legacy [runId, owner, repo] (or [runId] with defaults).
+  const shouldTreatAsOwnerRepoRunId = Boolean(a0) && Boolean(a1) && Boolean(a2) && !runIdNamed
+
+  const owner =
+    toTrimmedString(pickFirst(record.owner, options.owner, shouldTreatAsOwnerRepoRunId ? a0 : a1)) || undefined
+  const repo =
+    toTrimmedString(pickFirst(record.repo, options.repo, shouldTreatAsOwnerRepoRunId ? a1 : a2)) || undefined
+  const runId = toTrimmedString(pickFirst(runIdNamed || null, shouldTreatAsOwnerRepoRunId ? a2 : a0)) || ''
+
+  if (!runId) {
+    throw new Error('runId is required. Preferred invocation: { owner, repo, runId }.')
+  }
+
+  const cleanedOptions = stripMcpOnlyOptions({
+    ...options,
+    ...(owner ? { owner } : {}),
+    ...(repo ? { repo } : {}),
+  })
+
+  // Underlying helper signature is (runId, owner?, repo?, options?).
+  // We always pass runId first, and owner/repo if we have them.
+  if (owner && repo) {
+    return tool.method(runId, owner, repo, cleanedOptions)
+  }
+
+  if (owner && !repo) {
+    // Unusual: allow passing only owner explicitly.
+    return tool.method(runId, owner, cleanedOptions)
+  }
+
+  return tool.method(runId, cleanedOptions)
+}
+
 export const createGitMcpServer = (options: GitMcpServerOptions = {}): GitMcpServerInstance => {
   const api = createGitServiceApi(options)
   const tools = collectGitTools(api)
@@ -281,6 +837,8 @@ export const createGitMcpServer = (options: GitMcpServerOptions = {}): GitMcpSer
     if (requestedName === batchToolName) {
       try {
         const { calls, continueOnError } = normalizeBatchPayload(request.params.arguments)
+        const batchControls = extractOutputControls(request.params.arguments)
+
         const executions = calls.map(({ tool, args = [], options = {} }, index) => ({ tool, args, options, index }))
         const results = await Promise.all(
           executions.map(async ({ tool, args, options, index }) => {
@@ -290,17 +848,34 @@ export const createGitMcpServer = (options: GitMcpServerOptions = {}): GitMcpSer
                 index,
                 tool,
                 isError: true,
-                data: `Unknown tool: ${tool}`,
+                ...({
+                  ok: false,
+                  error: {
+                    code: 'UNKNOWN_TOOL',
+                    message: `Unknown tool: ${tool}`,
+                    retryable: false,
+                  },
+                } satisfies McpTerseErr),
               } as BatchResult
             }
 
             try {
-              const data = await invokeTool(toolDefinition, { args, options })
+              const mergedPayload = { args, options }
+              const callControls = extractOutputControls(mergedPayload)
+              const effectiveFormat = callControls.format ?? batchControls.format ?? 'terse'
+
+              const data = await (isLogsForRunTailTool(toolDefinition.name)
+                ? invokeLogsForRunTailTool(toolDefinition, mergedPayload)
+                : isArtifactsByRunTool(toolDefinition.name)
+                  ? invokeArtifactsByRunTool(toolDefinition, mergedPayload)
+                : invokeTool(toolDefinition, mergedPayload))
+
+              const { isError, envelope } = toMcpEnvelope(data, effectiveFormat)
               return {
                 index,
                 tool,
-                isError: false,
-                data: redactSecretsForMcpOutput(data),
+                isError,
+                ...(envelope as McpTerseOk | McpTerseErr),
               } as BatchResult
             } catch (error) {
               if (continueOnError) {
@@ -308,7 +883,7 @@ export const createGitMcpServer = (options: GitMcpServerOptions = {}): GitMcpSer
                   index,
                   tool,
                   isError: true,
-                  data: redactSecretsInText(error instanceof Error ? error.message : String(error)),
+                  ...(toMcpThrownErrorEnvelope(error) as McpTerseErr),
                 } as BatchResult
               }
               throw error
@@ -321,7 +896,7 @@ export const createGitMcpServer = (options: GitMcpServerOptions = {}): GitMcpSer
           content: [
             {
               type: 'text',
-              text: JSON.stringify(redactSecretsForMcpOutput(results), null, 2),
+              text: JSON.stringify(redactSecretsForMcpOutput(results)),
             },
           ],
         }
@@ -331,7 +906,7 @@ export const createGitMcpServer = (options: GitMcpServerOptions = {}): GitMcpSer
           content: [
             {
               type: 'text',
-              text: redactSecretsInText(error instanceof Error ? error.message : String(error)),
+              text: JSON.stringify(toMcpThrownErrorEnvelope(error)),
             },
           ],
         }
@@ -345,13 +920,20 @@ export const createGitMcpServer = (options: GitMcpServerOptions = {}): GitMcpSer
     }
 
     try {
-      const result = await invokeTool(tool, request.params.arguments)
-      const sanitized = redactSecretsForMcpOutput(result)
+      const controls = extractOutputControls(request.params.arguments)
+      const result = await (isLogsForRunTailTool(tool.name)
+        ? invokeLogsForRunTailTool(tool, request.params.arguments)
+        : isArtifactsByRunTool(tool.name)
+          ? invokeArtifactsByRunTool(tool, request.params.arguments)
+        : invokeTool(tool, request.params.arguments))
+
+      const { isError, envelope } = toMcpEnvelope(result, controls.format ?? 'terse')
       return {
+        ...(isError ? { isError: true } : {}),
         content: [
           {
             type: 'text',
-            text: JSON.stringify(sanitized, null, 2),
+            text: JSON.stringify(envelope),
           },
         ],
       }
@@ -361,7 +943,7 @@ export const createGitMcpServer = (options: GitMcpServerOptions = {}): GitMcpSer
         content: [
           {
             type: 'text',
-            text: redactSecretsInText(error instanceof Error ? error.message : String(error)),
+            text: JSON.stringify(toMcpThrownErrorEnvelope(error)),
           },
         ],
       }