@meistrari/agent-core 0.0.0 → 0.1.0

package/src/agents/agent-session-events.ts

@@ -0,0 +1,32 @@
+import type { AgentReasoningEffort, AgentToolDefinition, SessionConfiguredAgentEvent } from '../protocol'
+import type { AgentEventDraft } from './agent-event-stream'
+
+type SessionConfiguredPayload = SessionConfiguredAgentEvent['payload']
+type SessionConfiguredEventDraft = Extract<AgentEventDraft, { type: 'session.configured' }>
+
+export type SessionConfiguredEventInput = Pick<SessionConfiguredPayload, 'model' | 'cwd'> & {
+    reasoningEffort?: AgentReasoningEffort
+    tools?: readonly AgentToolDefinition[]
+    toolNames?: readonly SessionConfiguredPayload['tools'][number][]
+    environment: Record<string, string | undefined>
+}
+
+export function sessionConfiguredEvent(input: SessionConfiguredEventInput): SessionConfiguredEventDraft {
+    const payload: SessionConfiguredPayload = {
+        model: input.model,
+        cwd: input.cwd,
+        approvalMode: 'full-access',
+        tools: [...(input.toolNames ?? (input.tools ?? []).map(tool => tool.name))],
+        reasoningEffort: input.reasoningEffort,
+        environment: redactedEnvironment(input.environment),
+    }
+
+    return {
+        type: 'session.configured',
+        payload,
+    }
+}
+
+export function redactedEnvironment(environment: Record<string, string | undefined>): SessionConfiguredPayload['environment'] {
+    return Object.fromEntries(Object.keys(environment).sort().map(key => [key, '[REDACTED]']))
+}

package/src/agents/agent-tool-runner.ts

@@ -0,0 +1,83 @@
+import type { AppError } from '../errors'
+import type { AgentToolResult, JsonValue } from '../protocol'
+import type { AgentTool, AgentToolActor, AgentToolContext } from './agent-tool'
+import { isAppError } from '../errors'
+import { AgentOperationAbortedError, AgentToolValidationError } from './agent-runtime-error'
+import { agentToolActorDenialMessage, agentToolAllowsActor } from './agent-tool'
+
+export async function runAgentTool(input: {
+    tool: AgentTool
+    actor: AgentToolActor
+    rawInput: JsonValue
+    context: AgentToolContext
+}): Promise<AgentToolResult> {
+    if (!agentToolAllowsActor(input.tool, input.actor))
+        throw new AgentToolValidationError({ message: agentToolActorDenialMessage(input.tool) })
+
+    const parsed = input.tool.inputSchema.safeParse(input.rawInput)
+    if (!parsed.success) {
+        return {
+            success: false,
+            content: [{ type: 'text', text: parsed.error.message }],
+        }
+    }
+
+    const abortController = new AbortController()
+    const abort = (): void => abortController.abort()
+    const timeout = setTimeout(abort, input.tool.timeoutMs)
+    input.context.signal.addEventListener('abort', abort, { once: true })
+    if (input.context.signal.aborted)
+        abort()
+
+    try {
+        const result = await Promise.race([
+            input.tool.execute({
+                input: parsed.data,
+                context: {
+                    ...input.context,
+                    signal: abortController.signal,
+                },
+            }),
+            waitForAbort(abortController.signal, input.tool.name, input.tool.timeoutMs),
+        ])
+
+        validateToolResult(result)
+        return result
+    }
+    catch (error) {
+        if (!isAppError(error))
+            throw error
+        return appErrorToolResult(error)
+    }
+    finally {
+        clearTimeout(timeout)
+        input.context.signal.removeEventListener('abort', abort)
+    }
+}
+
+async function waitForAbort(signal: AbortSignal, toolName: string, timeoutMs: number): Promise<never> {
+    const abortedError = new AgentOperationAbortedError({
+        message: `Tool ${toolName} exceeded ${timeoutMs}ms or was aborted.`,
+        details: { toolName, timeoutMs },
+    })
+    if (signal.aborted)
+        throw abortedError
+
+    return await new Promise((_, reject) => {
+        signal.addEventListener('abort', () => reject(abortedError), { once: true })
+    })
+}
+
+function appErrorToolResult(error: AppError): AgentToolResult {
+    const serializedDetails = error.details === undefined ? '' : `\n\nDetails:\n${JSON.stringify(error.details, null, 2)}`
+    return {
+        success: false,
+        content: [{ type: 'text', text: `${error.publicMessage}${serializedDetails}` }],
+    }
+}
+
+function validateToolResult(result: AgentToolResult): void {
+    if (typeof result.success !== 'boolean' || !Array.isArray(result.content)) {
+        throw new AgentToolValidationError({ message: 'Tool result must include success and content array.' })
+    }
+}

package/src/agents/agent-tool.ts

@@ -0,0 +1,111 @@
+import type { ZodRawShape } from 'zod'
+import type { AgentProviderId, AgentToolDefinition, AgentToolResult, AgentUserInputQuestion } from '../protocol'
+import { z } from 'zod'
+import { jsonObjectSchema } from '../protocol'
+import { AgentToolValidationError } from './agent-runtime-error'
+
+export interface AgentToolContext {
+    provider: AgentProviderId
+    sessionId: string
+    providerSessionId: string
+    turnId: string
+    toolCallId: string
+    cwd: string
+    signal: AbortSignal
+    requestUserInput: (input: { prompt: string, questions: AgentUserInputQuestion[] }) => Promise<{ requestId: string }>
+}
+
+export interface AgentToolExecuteInput<TShape extends ZodRawShape = ZodRawShape> {
+    input: z.infer<z.ZodObject<TShape>>
+    context: AgentToolContext
+}
+
+export type AgentToolActor = 'main' | 'subagent'
+export type AgentToolActorScope = 'all' | 'main'
+
+export interface AgentTool {
+    readonly name: string
+    readonly description: string
+    readonly actorScope: AgentToolActorScope
+    readonly inputShape: ZodRawShape
+    readonly inputSchema: z.ZodObject<ZodRawShape>
+    readonly timeoutMs: number
+    execute: (input: AgentToolExecuteInput) => Promise<AgentToolResult>
+    definition: () => AgentToolDefinition
+}
+
+export interface CreateAgentToolInput<TShape extends ZodRawShape> {
+    name: string
+    description: string
+    actorScope?: AgentToolActorScope
+    inputSchema: z.ZodObject<TShape>
+    timeoutMs?: number
+    execute: (input: AgentToolExecuteInput<TShape>) => Promise<AgentToolResult>
+}
+
+const DEFAULT_TOOL_TIMEOUT_MS = 60_000
+const TOOL_NAME_PATTERN = /^[\w-]{1,128}$/
+
+export function tool<TShape extends ZodRawShape>(input: CreateAgentToolInput<TShape>): AgentTool {
+    if (!TOOL_NAME_PATTERN.test(input.name)) {
+        throw new AgentToolValidationError({ message: `Invalid tool name: ${input.name}` })
+    }
+
+    if (!input.description.trim()) {
+        throw new AgentToolValidationError({ message: `Tool ${input.name} must have a description.` })
+    }
+
+    const timeoutMs = input.timeoutMs ?? DEFAULT_TOOL_TIMEOUT_MS
+    const inputShape = input.inputSchema.shape
+
+    return {
+        name: input.name,
+        description: input.description,
+        actorScope: input.actorScope ?? 'all',
+        inputShape,
+        inputSchema: input.inputSchema,
+        timeoutMs,
+        execute: async ({ input: rawInput, context }) => await input.execute({
+            input: input.inputSchema.parse(rawInput),
+            context,
+        }),
+        definition: () => ({
+            name: input.name,
+            description: input.description,
+            inputSchema: jsonObjectSchema.parse(z.toJSONSchema(input.inputSchema)),
+        }),
+    }
+}
+
+export function toolDefinitions(tools: readonly AgentTool[]): AgentToolDefinition[] {
+    return tools.map(runtimeTool => runtimeTool.definition())
+}
+
+export function selectAgentTools(tools: readonly AgentTool[], definitions: readonly AgentToolDefinition[] | undefined): readonly AgentTool[] {
+    if (!definitions)
+        return tools
+
+    const selectedNames = new Set(definitions.map(definition => definition.name))
+    return tools.filter(runtimeTool => selectedNames.has(runtimeTool.name))
+}
+
+export function agentToolAllowsActor(tool: AgentTool, actor: AgentToolActor): boolean {
+    return tool.actorScope === 'all' || actor === 'main'
+}
+
+export function agentToolActorDenialMessage(tool: AgentTool): string {
+    return `${tool.name} is available only to the main agent.`
+}
+
+export function toolByName(tools: readonly AgentTool[]): Map<string, AgentTool> {
+    const byName = new Map<string, AgentTool>()
+
+    for (const runtimeTool of tools) {
+        if (byName.has(runtimeTool.name)) {
+            throw new AgentToolValidationError({ message: `Duplicate tool name: ${runtimeTool.name}` })
+        }
+        byName.set(runtimeTool.name, runtimeTool)
+    }
+
+    return byName
+}

package/src/agents/author-context.ts

@@ -0,0 +1,36 @@
+import type { AgentAuthor } from '../protocol'
+import type { AgentSenderContext } from './agent-operation'
+
+const OPEN_TAG = '<coding-agent-context>'
+const CLOSE_TAG = '</coding-agent-context>'
+
+const AUTHOR_CONTEXT_PATTERN = /^<coding-agent-context>[\s\S]*?<\/coding-agent-context>\n*/
+const slackMentionPattern = /^<@([\w-]+)(?:\|[^>]*)?>$/u
+
+export function renderAuthorContext(author: AgentAuthor, senderContext: AgentSenderContext = { kind: 'application' }): string {
+    const attributes = [
+        `name="${escapeXmlAttribute(author.name)}"`,
+        author.email ? `email="${escapeXmlAttribute(author.email)}"` : undefined,
+        author.gitEmail ? `git-email="${escapeXmlAttribute(author.gitEmail)}"` : undefined,
+    ].filter((attribute): attribute is string => attribute !== undefined)
+    const providerUserId = senderContext.kind === 'slack'
+        ? slackMentionPattern.exec(senderContext.mention)?.[1]
+        : undefined
+    const sender = providerUserId
+        ? `  <sender ${attributes.join(' ')}>\n    <mention kind="user" provider="slack" provider_user_id="${escapeXmlAttribute(providerUserId)}"/>\n  </sender>`
+        : `  <sender ${attributes.join(' ')} />`
+    return `${OPEN_TAG}\n${sender}\n${CLOSE_TAG}`
+}
+
+export function stripAuthorContext(text: string): string {
+    return text.replace(AUTHOR_CONTEXT_PATTERN, '')
+}
+
+function escapeXmlAttribute(value: string): string {
+    return value
+        .replaceAll('&', '&amp;')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replaceAll('"', '&quot;')
+        .replaceAll('\'', '&apos;')
+}

package/src/agents/claude/claude-command-mapper.ts

@@ -0,0 +1,234 @@
+import type { SDKUserMessage } from '@anthropic-ai/claude-agent-sdk'
+import type { MessageParam } from '@anthropic-ai/sdk/resources'
+import type { AgentAuthor, AgentInputBlock, AgentPrompt } from '../../protocol'
+import type { AgentSenderContext } from '../agent-operation'
+import type { AgentInputAttachmentPreparation, AgentInputAttachmentProjection, MaterializedAgentInputAttachment } from '../materialized-input-attachment'
+import { Buffer } from 'node:buffer'
+import { AgentUnsupportedPromptBlockError } from '../agent-runtime-error'
+import { renderAuthorContext } from '../author-context'
+import { filesystemFallbackLabel, nativeAttachmentLabel, nativeImageMimeType, readAttachmentBytes } from '../input-attachment-preparation'
+import { deriveMessageId } from '../message-id'
+
+const claudeNativeImageEncodedByteLimit = 10_000_000
+const claudeNativeCurrentMessageByteLimit = 24_000_000
+const pdfSignature = '%PDF-'
+const pdfSignatureStartLimit = 1024
+
+type ClaudeContentBlock = Exclude<MessageParam['content'], string>[number]
+type ClaudeImageMimeType = 'image/jpeg' | 'image/png' | 'image/gif' | 'image/webp'
+interface ClaudeUserMessageInput {
+    prompt: AgentPrompt
+    mode?: 'next' | 'steer'
+    commandId: string
+    origin?: 'user' | 'supervisor'
+    author?: AgentAuthor
+    senderContext?: AgentSenderContext
+}
+type ClaudeAttachmentProjection
+    = | {
+        attachment: MaterializedAgentInputAttachment
+        route: 'native'
+        nativeKind: 'image' | 'document'
+        nativeBlock: ClaudeContentBlock
+    }
+    | {
+        attachment: MaterializedAgentInputAttachment
+        route: 'filesystem_fallback'
+    }
+
+export function toClaudeUserMessage(input: ClaudeUserMessageInput): SDKUserMessage {
+    return claudeUserMessage(input, claudeMessageContent(input))
+}
+
+export async function mapClaudeUserMessage(input: ClaudeUserMessageInput, preparation?: AgentInputAttachmentPreparation): Promise<SDKUserMessage> {
+    return preparation
+        ? await prepareClaudeUserMessage({ ...input, preparation })
+        : toClaudeUserMessage(input)
+}
+
+async function prepareClaudeUserMessage(input: ClaudeUserMessageInput & { preparation: AgentInputAttachmentPreparation }): Promise<SDKUserMessage> {
+    input.preparation.signal.throwIfAborted()
+    const originalContent = claudeMessageContent(input)
+    const projections: ClaudeAttachmentProjection[] = []
+
+    for (const attachment of input.preparation.attachments) {
+        const bytes = await readAttachmentBytes(attachment, input.preparation.signal)
+        projections.push(claudeAttachmentProjection(attachment, bytes))
+    }
+
+    demoteForCurrentMessageBudget(originalContent, projections)
+    const content = [...originalContent, ...projections.flatMap(claudeAttachmentBlocks)]
+    const records = projections.map(toProjectionRecord)
+    input.preparation.recordInputAttachmentProjections(records)
+    return claudeUserMessage(input, content)
+}
+
+function claudeUserMessage(input: ClaudeUserMessageInput, content: ClaudeContentBlock[]): SDKUserMessage {
+    const { mode = 'next', commandId, origin = 'user' } = input
+    return {
+        type: 'user',
+        message: {
+            role: 'user',
+            content,
+        },
+        parent_tool_use_id: null,
+        priority: mode === 'steer' ? 'now' : 'next',
+        uuid: deriveMessageId(commandId),
+        ...(origin === 'supervisor' ? { isSynthetic: true, origin: { kind: 'coordinator' as const } } : {}),
+    }
+}
+
+function claudeMessageContent({ prompt, origin = 'user', author, senderContext }: ClaudeUserMessageInput): ClaudeContentBlock[] {
+    const blocks = prompt.blocks.map(toClaudeContentBlock)
+    return origin === 'user' && author
+        ? [{ type: 'text', text: renderAuthorContext(author, senderContext) }, ...blocks]
+        : blocks
+}
+
+function claudeAttachmentProjection(attachment: MaterializedAgentInputAttachment, bytes: Buffer): ClaudeAttachmentProjection {
+    const imageMimeType = nativeImageMimeType(attachment.mediaType, bytes)
+    if (imageMimeType && encodedBase64ByteSize(attachment.byteSize) <= claudeNativeImageEncodedByteLimit) {
+        return {
+            attachment,
+            route: 'native',
+            nativeKind: 'image',
+            nativeBlock: {
+                type: 'image',
+                source: {
+                    type: 'base64',
+                    media_type: imageMimeType,
+                    data: bytes.toString('base64'),
+                },
+            },
+        }
+    }
+
+    if (attachment.mediaType === 'application/pdf') {
+        const signatureOffset = bytes
+            .subarray(0, pdfSignatureStartLimit + pdfSignature.length)
+            .indexOf(pdfSignature)
+        if (signatureOffset >= 0) {
+            return {
+                attachment,
+                route: 'native',
+                nativeKind: 'document',
+                nativeBlock: {
+                    type: 'document',
+                    title: attachment.filename,
+                    source: {
+                        type: 'base64',
+                        media_type: 'application/pdf',
+                        data: bytes.toString('base64'),
+                    },
+                },
+            }
+        }
+    }
+
+    if (attachment.mediaType === 'text/plain' || attachment.mediaType === 'text/markdown') {
+        const text = decodeNonemptyUtf8(bytes)
+        if (text !== undefined) {
+            return {
+                attachment,
+                route: 'native',
+                nativeKind: 'document',
+                nativeBlock: {
+                    type: 'document',
+                    title: attachment.filename,
+                    source: {
+                        type: 'text',
+                        media_type: 'text/plain',
+                        data: text,
+                    },
+                },
+            }
+        }
+    }
+
+    return { attachment, route: 'filesystem_fallback' }
+}
+
+function demoteForCurrentMessageBudget(originalContent: readonly ClaudeContentBlock[], projections: ClaudeAttachmentProjection[]): void {
+    while (serializedContentByteSize(originalContent, projections) > claudeNativeCurrentMessageByteLimit) {
+        const index = projections.findLastIndex(projection => projection.route === 'native')
+        if (index < 0)
+            return
+        const projection = projections[index]!
+        projections[index] = { attachment: projection.attachment, route: 'filesystem_fallback' }
+    }
+}
+
+function serializedContentByteSize(originalContent: readonly ClaudeContentBlock[], projections: readonly ClaudeAttachmentProjection[]): number {
+    const content = [...originalContent, ...projections.flatMap(claudeAttachmentBlocks)]
+    return Buffer.byteLength(JSON.stringify(content))
+}
+
+function claudeAttachmentBlocks(projection: ClaudeAttachmentProjection): ClaudeContentBlock[] {
+    if (projection.route === 'filesystem_fallback')
+        return [{ type: 'text', text: filesystemFallbackLabel(projection.attachment) }]
+    return [
+        { type: 'text', text: nativeAttachmentLabel(projection.attachment) },
+        projection.nativeBlock,
+    ]
+}
+
+function toProjectionRecord(projection: ClaudeAttachmentProjection): AgentInputAttachmentProjection {
+    const { attachment } = projection
+    if (projection.route === 'filesystem_fallback') {
+        return {
+            attachmentId: attachment.attachmentId,
+            ordinal: attachment.ordinal,
+            sha256: attachment.sha256,
+            route: 'filesystem_fallback',
+        }
+    }
+    return {
+        attachmentId: attachment.attachmentId,
+        ordinal: attachment.ordinal,
+        sha256: attachment.sha256,
+        route: 'native',
+        nativeKind: projection.nativeKind,
+    }
+}
+
+function decodeNonemptyUtf8(bytes: Uint8Array): string | undefined {
+    const text = new TextDecoder('utf-8', { ignoreBOM: true }).decode(bytes)
+    if (text.length === 0)
+        return undefined
+    const encoded = new TextEncoder().encode(text)
+    if (encoded.length !== bytes.length || !encoded.every((byte, index) => byte === bytes[index]))
+        return undefined
+    return text
+}
+
+function encodedBase64ByteSize(byteSize: number): number {
+    return 4 * Math.ceil(byteSize / 3)
+}
+
+function toClaudeContentBlock(block: AgentInputBlock): ClaudeContentBlock {
+    if (block.type === 'text')
+        return { type: 'text', text: block.text }
+
+    if (block.type === 'image' && block.source.kind === 'base64') {
+        return {
+            type: 'image',
+            source: {
+                type: 'base64',
+                media_type: toClaudeImageMimeType(block.source.mimeType),
+                data: block.source.data,
+            },
+        }
+    }
+
+    if (block.type === 'file' && block.source.kind === 'text') {
+        return { type: 'text', text: `<file name="${block.source.name ?? 'file'}">\n${block.source.text}\n</file>` }
+    }
+
+    throw new AgentUnsupportedPromptBlockError({ provider: 'claude', blockType: block.type })
+}
+
+function toClaudeImageMimeType(mimeType: string): ClaudeImageMimeType {
+    if (mimeType === 'image/jpeg' || mimeType === 'image/png' || mimeType === 'image/gif' || mimeType === 'image/webp')
+        return mimeType
+    throw new AgentUnsupportedPromptBlockError({ provider: 'claude', blockType: `image:${mimeType}` })
+}