@meistrari/agent-core 0.0.0 → 0.1.0

package/src/agents/codex/index.ts

@@ -0,0 +1,2 @@
+export * from './codex-auth'
+export * from './codex-provider'

package/src/agents/index.ts

@@ -0,0 +1,14 @@
+export * from './agent-error-serializer'
+export * from './agent-event-stream'
+export * from './agent-operation'
+export * from './agent-provider'
+export * from './agent-run'
+export * from './agent-runtime-error'
+export * from './agent-session-events'
+export * from './agent-tool'
+export * from './agent-tool-runner'
+export * from './instructions'
+export * from './materialized-input-attachment'
+export * from './message-id'
+export * from './tools/ping.tool'
+export * from './user-input-request'

package/src/agents/input-attachment-preparation.ts

@@ -0,0 +1,86 @@
+import type { Buffer } from 'node:buffer'
+import type { MaterializedAgentInputAttachment } from './materialized-input-attachment'
+import { readFile } from 'node:fs/promises'
+import { AgentInputAttachmentPreparationFailure } from './input-attachment.errors'
+
+type NativeImageMimeType = 'image/jpeg' | 'image/png' | 'image/gif' | 'image/webp'
+
+export async function readAttachmentBytes(attachment: MaterializedAgentInputAttachment, signal: AbortSignal): Promise<Buffer> {
+    signal.throwIfAborted()
+    try {
+        const bytes = await readFile(attachment.localPath, { signal })
+        signal.throwIfAborted()
+        return bytes
+    }
+    catch (cause) {
+        if (signal.aborted)
+            throw signal.reason
+        if (!isErrnoBackedFilesystemError(cause))
+            throw cause
+        throw new AgentInputAttachmentPreparationFailure({ attachmentId: attachment.attachmentId, cause })
+    }
+}
+
+function isErrnoBackedFilesystemError(cause: unknown): cause is Error & { errno: number, syscall: string } {
+    if (!(cause instanceof Error))
+        return false
+    const filesystemError = cause as NodeJS.ErrnoException
+    return typeof filesystemError.errno === 'number' && typeof filesystemError.syscall === 'string'
+}
+
+export function nativeImageMimeType(mediaType: string, bytes: Uint8Array): NativeImageMimeType | undefined {
+    if (mediaType === 'image/jpeg' && bytes.length >= 2 && bytes[0] === 0xFF && bytes[1] === 0xD8)
+        return mediaType
+
+    if (mediaType === 'image/png' && bytes.length >= 9 && hasBytes(bytes, [0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A]))
+        return mediaType
+
+    if (mediaType === 'image/gif' && (hasAsciiPrefix(bytes, 'GIF87a') || hasAsciiPrefix(bytes, 'GIF89a')))
+        return mediaType
+
+    if (mediaType === 'image/webp' && bytes.length >= 12 && hasAsciiPrefix(bytes, 'RIFF') && hasAsciiAt(bytes, 8, 'WEBP'))
+        return mediaType
+
+    return undefined
+}
+
+export function nativeAttachmentLabel(attachment: MaterializedAgentInputAttachment): string {
+    return `Input attachment (native):\n${JSON.stringify({
+        attachmentId: attachment.attachmentId,
+        ordinal: attachment.ordinal,
+        filename: attachment.filename,
+        mediaType: attachment.mediaType,
+        byteSize: attachment.byteSize,
+        sha256: attachment.sha256,
+    })}`
+}
+
+export function filesystemFallbackLabel(attachment: MaterializedAgentInputAttachment): string {
+    return `Input attachment (filesystem fallback):\n${JSON.stringify({
+        attachmentId: attachment.attachmentId,
+        ordinal: attachment.ordinal,
+        filename: attachment.filename,
+        mediaType: attachment.mediaType,
+        byteSize: attachment.byteSize,
+        sha256: attachment.sha256,
+        path: attachment.localPath,
+    })}`
+}
+
+function hasBytes(bytes: Uint8Array, expected: readonly number[]): boolean {
+    return expected.every((byte, index) => bytes[index] === byte)
+}
+
+function hasAsciiPrefix(bytes: Uint8Array, expected: string): boolean {
+    return hasAsciiAt(bytes, 0, expected)
+}
+
+function hasAsciiAt(bytes: Uint8Array, offset: number, expected: string): boolean {
+    if (bytes.length < offset + expected.length)
+        return false
+    for (let index = 0; index < expected.length; index += 1) {
+        if (bytes[offset + index] !== expected.charCodeAt(index))
+            return false
+    }
+    return true
+}

package/src/agents/input-attachment.errors.ts

@@ -0,0 +1,16 @@
+import { InfrastructureError } from '../errors'
+
+export class AgentInputAttachmentPreparationFailure extends InfrastructureError {
+    readonly attachmentId: string
+
+    constructor(input: { attachmentId: string, cause: unknown }) {
+        super({
+            code: 'agents.input-attachment-preparation-failed',
+            message: 'Failed to prepare a materialized input attachment.',
+            publicMessage: 'Agent input attachment could not be prepared.',
+            retryable: false,
+            cause: input.cause,
+        })
+        this.attachmentId = input.attachmentId
+    }
+}

package/src/agents/instructions.ts

@@ -0,0 +1,8 @@
+import type { AgentProviderId } from '../protocol'
+
+export type InstructionComposer = (input: {
+    provider: AgentProviderId
+    tools: readonly { name: string }[]
+}) => string
+
+export const emptyInstructionComposer: InstructionComposer = () => ''

package/src/agents/materialized-input-attachment.ts

@@ -0,0 +1,26 @@
+export type MaterializedAgentInputAttachment = Readonly<{
+    attachmentId: string
+    ordinal: number
+    filename: string
+    mediaType: string
+    byteSize: number
+    sha256: string
+    localPath: string
+}>
+
+export type AgentInputAttachmentProjection = Readonly<{
+    attachmentId: string
+    ordinal: number
+    sha256: string
+} & (
+    | { route: 'native', nativeKind: 'image' | 'document' }
+    | { route: 'filesystem_fallback' }
+)>
+
+export type AgentInputAttachmentPreparation = Readonly<{
+    attachments: readonly MaterializedAgentInputAttachment[]
+    signal: AbortSignal
+    recordInputAttachmentProjections: (
+        records: readonly AgentInputAttachmentProjection[],
+    ) => void
+}>

package/src/agents/message-id.ts

@@ -0,0 +1,23 @@
+import type { UUID } from 'node:crypto'
+import { Buffer } from 'node:buffer'
+import { createHash } from 'node:crypto'
+
+// Frozen: the namespace must never change, or a restarted supervisor would derive a different
+// correlation id when it redrives the same durable command.
+const NAMESPACE = 'b9d7a3f1-6e2c-5a48-9c1d-3f8e0a7b2c64'
+
+// Deterministic UUIDv5 correlation id: a redelivered command re-derives the same id across restarts.
+// It is correlation only — the provider is not assumed to deduplicate, so under at-least-once a
+// duplicate may be accepted; distinct command ids derive distinct ids, so genuine repeats are never
+// conflated.
+export function deriveMessageId(commandId: string): UUID {
+    const digest = createHash('sha1')
+        .update(Buffer.from(NAMESPACE.replaceAll('-', ''), 'hex'))
+        .update(commandId, 'utf8')
+        .digest()
+    const view = new DataView(digest.buffer, digest.byteOffset, 16)
+    view.setUint8(6, (view.getUint8(6) & 0x0F) | 0x50) // version 5
+    view.setUint8(8, (view.getUint8(8) & 0x3F) | 0x80) // RFC-4122 variant
+    const hex = digest.subarray(0, 16).toString('hex')
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`
+}

package/src/agents/normalize.ts

@@ -0,0 +1,8 @@
+export function removeUndefined<T extends object>(value: T): T {
+    return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined)) as T
+}
+
+export function optionalNonEmpty(value: string | null | undefined): string | undefined {
+    const trimmed = value?.trim()
+    return trimmed || undefined
+}

package/src/agents/sandbox-environment.ts

@@ -0,0 +1 @@
+export const SANDBOX_WORKSPACE_ROOT = '/home/user/workspace'

package/src/agents/tools/ping.tool.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod'
+import { tool } from '../agent-tool'
+
+export const pingTool = tool({
+    name: 'ping',
+    description: 'Return pong for smoke and contract checks.',
+    inputSchema: z.object({}),
+    timeoutMs: 5_000,
+    execute: async () => ({
+        success: true,
+        content: [{ type: 'text', text: 'pong' }],
+    }),
+})

package/src/agents/user-input-request.ts

@@ -0,0 +1,470 @@
+import type {
+    AgentPrompt,
+    AgentUserInputAnswers,
+    AgentUserInputQuestion,
+    RespondUserInputAgentCommand,
+    UserInputRequestedAgentEvent,
+    UserInputResolvedAgentEvent,
+} from '../protocol'
+import type { AgentEventDraft } from './agent-event-stream'
+import { Buffer } from 'node:buffer'
+import { randomUUID } from 'node:crypto'
+import { mkdirSync, renameSync, writeFileSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { basename, dirname, join } from 'node:path'
+import z from 'zod'
+import {
+    agentUserInputAnswersSchema,
+    agentUserInputQuestionSchema,
+} from '../protocol'
+import { createUserInputRequestId } from './agent-id'
+import { AgentRunStateError, AgentUserInputRequestStoreError } from './agent-runtime-error'
+
+const mainActor = { type: 'main', actorId: 'main' } as const
+
+const STORE_VERSION = 1
+const STORE_FILE_NAME = 'user-input-requests.json'
+const USER_INPUT_STORE_DIR = 'coding-agent-user-input'
+
+const userInputRequestStatusSchema = z.enum(['pending', 'answered', 'delivered', 'cancelled'])
+
+const userInputRequestRecordSchema = z.object({
+    requestId: z.string().min(1),
+    sessionId: z.string().min(1),
+    turnId: z.string().min(1),
+    toolCallId: z.string().min(1),
+    prompt: z.string().min(1),
+    questions: z.array(agentUserInputQuestionSchema).min(1),
+    status: userInputRequestStatusSchema,
+    answers: agentUserInputAnswersSchema.optional(),
+    createdAt: z.string().datetime(),
+    answeredAt: z.string().datetime().optional(),
+    deliveredAt: z.string().datetime().optional(),
+}).strict()
+
+const userInputRequestStoreFileSchema = z.object({
+    version: z.literal(STORE_VERSION),
+    sessionId: z.string().min(1),
+    requests: z.array(userInputRequestRecordSchema),
+}).strict()
+
+export interface UserInputRequestInput {
+    turnId: string
+    toolCallId: string
+    prompt: string
+    questions: readonly AgentUserInputQuestion[]
+}
+
+export type UserInputRequestRecord = z.infer<typeof userInputRequestRecordSchema>
+export type UserInputRequestStoreFile = z.infer<typeof userInputRequestStoreFileSchema>
+
+export interface OpenUserInputRequestStoreInput {
+    sessionId: string
+    rootDir: string
+}
+
+interface ResolvedUserInputRequest {
+    record: UserInputRequestRecord
+    event?: Extract<AgentEventDraft, { type: 'user-input.resolved' }>
+    prompt: AgentPrompt
+}
+
+export class UserInputRequestStore {
+    private readonly requests: Map<string, UserInputRequestRecord>
+
+    private constructor(
+        private readonly sessionId: string,
+        private readonly filePath: string,
+        requests: readonly UserInputRequestRecord[],
+    ) {
+        this.requests = new Map(requests.map(request => [request.requestId, request]))
+    }
+
+    static async open(input: OpenUserInputRequestStoreInput): Promise<UserInputRequestStore> {
+        if (!input.sessionId.trim()) {
+            throw new AgentUserInputRequestStoreError({ message: 'User-input request store requires a sessionId.' })
+        }
+        if (!input.rootDir.trim()) {
+            throw new AgentUserInputRequestStoreError({ message: 'User-input request store requires a rootDir.' })
+        }
+
+        const filePath = userInputRequestStoreFilePath(input)
+        const file = await readStoreFile({ sessionId: input.sessionId, filePath })
+        return new UserInputRequestStore(input.sessionId, filePath, file.requests)
+    }
+
+    create(input: UserInputRequestInput): {
+        requestId: string
+        event: Extract<AgentEventDraft, { type: 'user-input.requested' }>
+    } {
+        validateQuestions(input.questions)
+        const requestId = createUserInputRequestId()
+        const record: UserInputRequestRecord = {
+            requestId,
+            sessionId: this.sessionId,
+            turnId: input.turnId,
+            toolCallId: input.toolCallId,
+            prompt: input.prompt,
+            questions: userInputQuestions(input.questions),
+            status: 'pending',
+            createdAt: new Date().toISOString(),
+        }
+        this.requests.set(requestId, record)
+        this.persist()
+
+        return {
+            requestId,
+            event: {
+                type: 'user-input.requested',
+                turnId: input.turnId,
+                actor: mainActor,
+                payload: {
+                    requestId,
+                    toolCallId: input.toolCallId,
+                    prompt: input.prompt,
+                    questions: record.questions,
+                },
+            } satisfies UserInputRequestedEventDraft,
+        }
+    }
+
+    decorateTurnEnded(draft: AgentEventDraft): AgentEventDraft {
+        if (draft.type !== 'turn.ended' || draft.payload.status !== 'completed' || !this.hasPendingForTurn(draft.turnId))
+            return draft
+
+        return {
+            ...draft,
+            payload: {
+                ...draft.payload,
+                reason: 'user_input_requested',
+            },
+        }
+    }
+
+    shouldHoldIdle(): boolean {
+        return [...this.requests.values()].some(request => request.status === 'pending')
+    }
+
+    resolve(command: RespondUserInputAgentCommand): ResolvedUserInputRequest | null {
+        if (command.sessionId !== this.sessionId) {
+            throw new AgentRunStateError({
+                message: `User input request store for ${this.sessionId} cannot resolve command for ${command.sessionId}.`,
+                details: { storeSessionId: this.sessionId, commandSessionId: command.sessionId },
+            })
+        }
+
+        const record = this.requests.get(command.requestId)
+        if (!record) {
+            throw new AgentRunStateError({
+                message: `Unknown user input request: ${command.requestId}`,
+                details: { requestId: command.requestId },
+            })
+        }
+
+        if (record.status === 'delivered')
+            return null
+
+        if (record.status === 'answered') {
+            assertSameAnswers(record, command.answers)
+            return {
+                record,
+                prompt: promptForResolvedUserInput(record, record.answers),
+            }
+        }
+
+        if (record.status !== 'pending') {
+            throw new AgentRunStateError({
+                message: `User input request ${command.requestId} is ${record.status}.`,
+                details: { requestId: command.requestId, status: record.status },
+            })
+        }
+
+        validateAnswers(record, command.answers)
+        const answered: UserInputRequestRecord = {
+            ...record,
+            status: 'answered',
+            answers: command.answers,
+            answeredAt: new Date().toISOString(),
+        }
+        this.requests.set(answered.requestId, answered)
+        this.persist()
+
+        return {
+            record: answered,
+            event: {
+                type: 'user-input.resolved',
+                payload: {
+                    requestId: answered.requestId,
+                    requestedTurnId: answered.turnId,
+                    toolCallId: answered.toolCallId,
+                    answers: command.answers,
+                },
+            } satisfies UserInputResolvedEventDraft,
+            prompt: promptForResolvedUserInput(answered, command.answers),
+        }
+    }
+
+    markDelivered(requestId: string): void {
+        const record = this.requests.get(requestId)
+        if (!record || record.status !== 'answered')
+            return
+
+        this.requests.set(requestId, {
+            ...record,
+            status: 'delivered',
+            deliveredAt: new Date().toISOString(),
+        })
+        this.persist()
+    }
+
+    private hasPendingForTurn(turnId: string): boolean {
+        return [...this.requests.values()].some(request => request.turnId === turnId && request.status === 'pending')
+    }
+
+    private persist(): void {
+        const file: UserInputRequestStoreFile = {
+            version: STORE_VERSION,
+            sessionId: this.sessionId,
+            requests: [...this.requests.values()],
+        }
+        const parent = dirname(this.filePath)
+        const tempPath = join(parent, `.${basename(this.filePath)}.${process.pid}.${randomUUID()}.tmp`)
+
+        try {
+            mkdirSync(parent, { recursive: true })
+            writeFileSync(tempPath, `${JSON.stringify(file, null, 2)}\n`, 'utf8')
+            renameSync(tempPath, this.filePath)
+        }
+        catch (error) {
+            throw new AgentUserInputRequestStoreError({
+                message: `Failed to persist user-input request store for session ${this.sessionId}.`,
+                details: { sessionId: this.sessionId },
+                cause: error,
+            })
+        }
+    }
+}
+
+type UserInputRequestedEventDraft = Omit<UserInputRequestedAgentEvent, 'eventId' | 'provider' | 'sessionId' | 'providerSessionId' | 'timestamp' | 'sequence'>
+type UserInputResolvedEventDraft = Omit<UserInputResolvedAgentEvent, 'eventId' | 'provider' | 'sessionId' | 'providerSessionId' | 'timestamp' | 'sequence'>
+
+export function userInputRequestStoreRootFromTranscriptPath(transcriptPath: string): string {
+    return join(dirname(transcriptPath), USER_INPUT_STORE_DIR)
+}
+
+export function userInputRequestStoreFilePath(input: OpenUserInputRequestStoreInput): string {
+    return join(input.rootDir, safeSessionPathSegment(input.sessionId), STORE_FILE_NAME)
+}
+
+async function readStoreFile(input: { sessionId: string, filePath: string }): Promise<UserInputRequestStoreFile> {
+    let raw: string
+    try {
+        raw = await readFile(input.filePath, 'utf8')
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === 'ENOENT') {
+            return { version: STORE_VERSION, sessionId: input.sessionId, requests: [] }
+        }
+        throw new AgentUserInputRequestStoreError({
+            message: `Failed to read user-input request store for session ${input.sessionId}.`,
+            details: { sessionId: input.sessionId },
+            cause: error,
+        })
+    }
+
+    let parsed: unknown
+    try {
+        parsed = JSON.parse(raw)
+    }
+    catch (error) {
+        throw new AgentUserInputRequestStoreError({
+            message: `User-input request store for session ${input.sessionId} contains invalid JSON.`,
+            details: { sessionId: input.sessionId },
+            cause: error,
+        })
+    }
+
+    const result = userInputRequestStoreFileSchema.safeParse(parsed)
+    if (!result.success) {
+        throw new AgentUserInputRequestStoreError({
+            message: `User-input request store for session ${input.sessionId} has invalid shape.`,
+            details: { sessionId: input.sessionId },
+            cause: result.error,
+        })
+    }
+
+    if (result.data.sessionId !== input.sessionId) {
+        throw new AgentUserInputRequestStoreError({
+            message: `User-input request store session mismatch: expected ${input.sessionId}, found ${result.data.sessionId}.`,
+            details: { expectedSessionId: input.sessionId, actualSessionId: result.data.sessionId },
+        })
+    }
+
+    const seenRequestIds = new Set<string>()
+    for (const request of result.data.requests) {
+        if (request.sessionId !== input.sessionId) {
+            throw new AgentUserInputRequestStoreError({
+                message: `User-input request ${request.requestId} belongs to session ${request.sessionId}, not ${input.sessionId}.`,
+                details: { expectedSessionId: input.sessionId, actualSessionId: request.sessionId, requestId: request.requestId },
+            })
+        }
+        if (seenRequestIds.has(request.requestId)) {
+            throw new AgentUserInputRequestStoreError({
+                message: `User-input request store contains duplicate request id ${request.requestId}.`,
+                details: { sessionId: input.sessionId, requestId: request.requestId },
+            })
+        }
+        seenRequestIds.add(request.requestId)
+    }
+
+    return result.data
+}
+
+function userInputQuestions(questions: readonly AgentUserInputQuestion[]): AgentUserInputQuestion[] {
+    return z.array(agentUserInputQuestionSchema).parse(questions)
+}
+
+function validateQuestions(questions: readonly AgentUserInputQuestion[]): void {
+    const ids = new Set<string>()
+    for (const question of questions) {
+        if (ids.has(question.id)) {
+            throw new AgentRunStateError({
+                message: `Duplicate user-input question id: ${question.id}`,
+                details: { questionId: question.id },
+            })
+        }
+        ids.add(question.id)
+
+        if (question.type !== 'single_select')
+            continue
+
+        const optionValues = new Set<string>()
+        for (const option of question.options) {
+            if (optionValues.has(option.value)) {
+                throw new AgentRunStateError({
+                    message: `Duplicate option value ${option.value} for user-input question ${question.id}.`,
+                    details: { questionId: question.id, optionValue: option.value },
+                })
+            }
+            optionValues.add(option.value)
+        }
+    }
+}
+
+function validateAnswers(record: UserInputRequestRecord, answers: AgentUserInputAnswers): void {
+    const questionsById = new Map(record.questions.map(question => [question.id, question]))
+
+    for (const answerId of Object.keys(answers)) {
+        if (!questionsById.has(answerId)) {
+            throw new AgentRunStateError({
+                message: `Answer provided for unknown user-input question: ${answerId}`,
+                details: { requestId: record.requestId, questionId: answerId },
+            })
+        }
+    }
+
+    for (const question of record.questions) {
+        const answer = answers[question.id]
+        if (answer === undefined || answer === null) {
+            if (question.required === false)
+                continue
+            throw new AgentRunStateError({
+                message: `Missing answer for user-input question: ${question.id}`,
+                details: { requestId: record.requestId, questionId: question.id },
+            })
+        }
+
+        if (question.type === 'text') {
+            if (typeof answer !== 'string') {
+                throw new AgentRunStateError({
+                    message: `Answer for user-input question ${question.id} must be a string.`,
+                    details: { requestId: record.requestId, questionId: question.id },
+                })
+            }
+            if (question.required !== false && !answer.trim()) {
+                throw new AgentRunStateError({
+                    message: `Answer for user-input question ${question.id} must not be empty.`,
+                    details: { requestId: record.requestId, questionId: question.id },
+                })
+            }
+            continue
+        }
+
+        if (typeof answer !== 'string' || !question.options.some(option => option.value === answer)) {
+            throw new AgentRunStateError({
+                message: `Answer for user-input question ${question.id} must be one of the allowed options.`,
+                details: { requestId: record.requestId, questionId: question.id },
+            })
+        }
+    }
+}
+
+function assertSameAnswers(record: UserInputRequestRecord, answers: AgentUserInputAnswers): asserts record is UserInputRequestRecord & { answers: AgentUserInputAnswers } {
+    const existing = record.answers
+    if (!existing) {
+        throw new AgentRunStateError({
+            message: `User input request ${record.requestId} is answered without stored answers.`,
+            details: { requestId: record.requestId },
+        })
+    }
+
+    if (!sameAnswerValues(existing, answers)) {
+        throw new AgentRunStateError({
+            message: `User input request ${record.requestId} was already answered with different answers.`,
+            details: { requestId: record.requestId },
+        })
+    }
+}
+
+function sameAnswerValues(left: AgentUserInputAnswers, right: AgentUserInputAnswers): boolean {
+    return stableJson(left) === stableJson(right)
+}
+
+function stableJson(value: unknown): string {
+    return JSON.stringify(stableValue(value))
+}
+
+function stableValue(value: unknown): unknown {
+    if (Array.isArray(value))
+        return value.map(stableValue)
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, entry]) => [key, stableValue(entry)]))
+    }
+    return value
+}
+
+function promptForResolvedUserInput(record: UserInputRequestRecord, answers: AgentUserInputAnswers): AgentPrompt {
+    return {
+        blocks: [{
+            type: 'text',
+            text: [
+                'The user answered a previous user-input request.',
+                '',
+                `Request ID: ${record.requestId}`,
+                'Original prompt:',
+                record.prompt,
+                '',
+                'Answers:',
+                ...record.questions.map(question => `- ${question.id}: ${formatAnswer(answers[question.id])}`),
+                '',
+                'Continue from where you left off. Treat these answers as the result of the previous ask_user request. Do not ask the same question again unless the answer is insufficient.',
+            ].join('\n'),
+        }],
+    }
+}
+
+function formatAnswer(value: AgentUserInputAnswers[string] | undefined): string {
+    if (value === undefined)
+        return '(no answer)'
+    if (typeof value === 'string')
+        return value
+    return JSON.stringify(value)
+}
+
+function safeSessionPathSegment(sessionId: string): string {
+    return Buffer.from(sessionId, 'utf8').toString('base64url')
+}
+
+function isNodeError(error: unknown): error is NodeJS.ErrnoException {
+    return error instanceof Error && 'code' in error
+}