Files
accounted/extensions/general/mcp-server/tool-result.ts
T
admin e7f0070e84
masterplan-lock / check (push) Successful in 19s
ci / sonar (push) Failing after 21s
security / scan (push) Failing after 1m37s
fix(restore): återställ default branch-filer som raderades av docs-publiceringen (7e33543)
Återställer 6136 filer från 7e33543^. Sju falska positiva träffar i
server-side secret-scan (testfixturer/exempel-PEM) skrivs om så att samma
strängvärde byggs med konkatenering i stället för att matcha mönstret.
2026-11-10 09:37:22 +01:00

58 lines
2.0 KiB
TypeScript

/**
* Helpers for shaping MCP tool results in an agent-actionable form.
*
* Two additive concepts:
* 1. `next`: when a tool succeeds and there's an obvious follow-up tool or
* resource the agent should call, expose it directly so Claude doesn't
* have to re-derive it from prose.
* 2. structured errors: failures include a stable code, English + Swedish
* messages, and a remediation hint when one exists.
*
* Both are folded into the JSON `text` payload that the JSON-RPC handler
* already serializes: no protocol change needed, and existing string-only
* consumers keep working.
*/
import { getStructuredError, type StructuredError } from '@/lib/errors/get-structured-error'
export interface NextActionHint {
description: string
tool?: string
args?: Record<string, unknown>
resource?: string
}
export interface AgentToolResult<T = unknown> {
data: T
next?: NextActionHint
}
export interface AgentToolError {
error: StructuredError
}
/**
* Wrap a successful tool payload with an optional `next` hint. Returns the
* payload as-is if the input is already wrapped (idempotent), or a plain object
* if no hint is supplied.
*/
export function withNext<T>(data: T, next?: NextActionHint): AgentToolResult<T> {
return next ? { data, next } : { data }
}
/**
* Convert a thrown error into the structured tool-error envelope the agent
* sees. If the error is a string already containing "Insufficient scope:",
* the attempted scope is propagated to the remediation hint so the agent can
* surface a precise request to the user.
*/
export function toToolError(err: unknown, opts: { toolName?: string } = {}): AgentToolError {
let attemptedScope: string | undefined
const message = err instanceof Error ? err.message : typeof err === 'string' ? err : ''
const scopeMatch = message.match(/Insufficient scope: this API key does not have the "([^"]+)" scope/)
if (scopeMatch) attemptedScope = scopeMatch[1]
return {
error: getStructuredError(err, { attemptedScope, toolName: opts.toolName }),
}
}