@meistrari/agent-core 0.1.1 → 0.1.2

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@meistrari/agent-core",
     "type": "module",
-    "version": "0.1.1",
+    "version": "0.1.2",
     "packageManager": "bun@1.3.12",
     "description": "Shared contracts and runtime modules for Tela coding-agent sandboxes: agent protocol, supervisor wire protocol, resident supervisor, worker runtime client, and Claude/Codex harness adapters.",
     "license": "UNLICENSED",
@@ -14,6 +14,8 @@
         "registry": "https://registry.npmjs.org"
     },
     "exports": {
+        "./steps/contract": "./src/steps/contract.ts",
+        "./steps/projector": "./src/steps/projector.ts",
         "./errors": "./src/errors/index.ts",
         "./errors/application-error": "./src/errors/application-error.ts",
         "./logger": "./src/logger/index.ts",

package/src/agents/claude/claude-provider.ts

@@ -71,6 +71,7 @@ export class ClaudeProvider implements AgentProvider<'claude'> {
         const sdkOptions: Options = removeUndefined({
             abortController,
             cwd: input.cwd,
+            settingSources: ['project', 'local'],
             env: this.environment,
             model: input.model,
             thinking: { type: 'adaptive', display: 'summarized' },

package/src/provenance.gen.ts

@@ -1,6 +1,6 @@
 // Generated by scripts/write-provenance.ts. Do not edit by hand.
 export const generatedProvenance = {
-    version: "0.1.1",
-    sha: "00ac4425fb84e86e0adabba1067485b94f45c100",
-    buildTime: "2026-09-08T17:04:18.818Z",
+    version: "0.1.2",
+    sha: "85081b3dd3667033dfb1dfd399a6f59d3fd42d43",
+    buildTime: "2026-09-09T11:47:21.679Z",
 } as const

package/src/steps/contract.ts

@@ -0,0 +1,94 @@
+import { Buffer } from 'node:buffer'
+import { createHash } from 'node:crypto'
+import { z } from 'zod'
+import { agentEventActorSchema } from '../protocol/agent-event'
+import { jsonValueSchema } from '../protocol/agent-json'
+
+export const stepSummarySchema = z.object({
+    version: z.literal(1),
+    stepId: z.string().uuid(),
+    sessionId: z.string(),
+    provider: z.enum(['claude', 'codex']),
+    providerSessionId: z.string(),
+    sourceId: z.string(),
+    actor: agentEventActorSchema,
+    turnId: z.string(),
+    commandId: z.string().nullable(),
+    kind: z.enum(['message', 'tool', 'reasoning']),
+    role: z.enum(['assistant', 'user', 'system']).nullable(),
+    toolName: z.string().nullable(),
+    status: z.enum(['running', 'completed', 'failed', 'interrupted']),
+    incomplete: z.boolean(),
+    startedAt: z.string().datetime(),
+    endedAt: z.string().datetime().nullable(),
+    preview: z.string(),
+}).strict()
+export const stepDetailSchema = stepSummarySchema.extend({
+    content: z.record(z.string(), jsonValueSchema),
+}).strict()
+export type StepSummary = z.infer<typeof stepSummarySchema>
+export type StepDetailV1 = z.infer<typeof stepDetailSchema>
+
+/** Stable bytes across JSONB round trips and deterministic upload retries. */
+export function serializeStepDetail(value: unknown): string {
+    return JSON.stringify(value, (_key, item: unknown) => {
+        if (item && typeof item === 'object' && !Array.isArray(item))
+            return Object.fromEntries(Object.entries(item).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0))
+        return item
+    })
+}
+
+export const stepClosedSchema = z.object({
+    step: stepSummarySchema,
+    sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+    byteSize: z.number().int().positive(),
+    textParts: z.number().int().nonnegative(),
+    detail: stepDetailSchema.optional(),
+    reference: z.string().startsWith('vault://').optional(),
+}).strict().refine(value => Boolean(value.detail) !== Boolean(value.reference), 'Exactly one detail source is required')
+
+export function stepIdFor(input: Pick<StepSummary, 'sessionId' | 'providerSessionId' | 'actor' | 'turnId' | 'kind' | 'sourceId'>): string {
+    const hex = createHash('sha256').update(JSON.stringify([
+        input.sessionId,
+        input.providerSessionId,
+        input.actor.actorId,
+        input.turnId,
+        input.kind,
+        input.sourceId,
+    ])).digest('hex')
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-5${hex.slice(13, 16)}-8${hex.slice(17, 20)}-${hex.slice(20, 32)}`
+}
+
+/** Both decoded UTF-8 and JSON representation stay bounded without dropping text. */
+export function splitStepText(text: string): string[] {
+    const parts: string[] = []
+    let part = ''
+    let bytes = 2
+    for (const character of text) {
+        const size = Buffer.byteLength(JSON.stringify(character)) - 2
+        if (bytes + size > 16 * 1024) {
+            parts.push(part)
+            part = ''
+            bytes = 2
+        }
+        part += character
+        bytes += size
+    }
+    if (part)
+        parts.push(part)
+    return parts
+}
+
+export function stepPreview(value: unknown): string {
+    const text = (typeof value === 'string' ? value : JSON.stringify(value) ?? '').replaceAll('\0', '\\0')
+    let preview = ''
+    let bytes = 0
+    for (const character of text) {
+        const size = Buffer.byteLength(JSON.stringify(character)) - 2
+        if (bytes + size > 2048)
+            return `${preview}…`
+        bytes += size
+        preview += character
+    }
+    return preview
+}

package/src/steps/projector.ts

@@ -0,0 +1,195 @@
+import type { AgentEvent } from '../protocol'
+import type { WireEventBody } from '../supervisor-protocol/event-body'
+import type { StepDetailV1, StepSummary } from './contract'
+import { Buffer } from 'node:buffer'
+import { createHash } from 'node:crypto'
+import { Database } from 'bun:sqlite'
+import { wrapAgentEvent } from '../supervisor-protocol/agent-event-wrapper'
+import { serializeStepDetail, splitStepText, stepIdFor, stepPreview } from './contract'
+
+/**
+ * Same-binary local recovery. The journal is marked delivered only after emit
+ * synchronously commits all frames into the supervisor's own durable outbox.
+ */
+export class DurableStepProjector {
+    private readonly db: Database
+    private currentEventId = ''
+
+    constructor(private readonly options: {
+        path: string
+        upload: (input: { stepId: string, sha256: string, body: string, byteSize: number }) => Promise<string>
+    }) {
+        this.db = new Database(options.path, { create: true })
+        this.db.exec(`pragma journal_mode=WAL; pragma synchronous=FULL;
+            create table if not exists steps(id text primary key, body text not null, last_event_id text);
+            create table if not exists journal(id text primary key, event text, frames text);
+        `)
+        if (!this.db.query<{ name: string }, []>('pragma table_info(steps)').all().some(column => column.name === 'last_event_id'))
+            this.db.exec('alter table steps add column last_event_id text')
+    }
+
+    close(): void { this.db.close() }
+
+    async recover(emit: (body: WireEventBody) => void): Promise<void> {
+        for (;;) {
+            const row = this.db.query<{ id: string, event: string, frames: string | null }, []>(
+                'select id, event, frames from journal where event is not null order by rowid limit 1',
+            ).get()
+            if (!row)
+                return
+            await this.deliver(row.id, JSON.parse(row.event) as AgentEvent, row.frames, emit)
+        }
+    }
+
+    async process(event: AgentEvent, emit: (body: WireEventBody) => void): Promise<void> {
+        if (['message.delta', 'tool.output.delta', 'reasoning.summary.delta'].includes(event.type)) {
+            // Live deltas never become historical tool payloads. Large transport
+            // deltas are split rather than dropped by the supervisor frame limit.
+            const body = wrapAgentEvent(event)
+            const key = event.type === 'reasoning.summary.delta' ? 'text' : 'delta'
+            const payload = event.payload as Record<string, unknown>
+            for (const part of splitStepText(String(payload[key] ?? ''))) {
+                // Use smaller slices for envelope headroom within the 16 KiB cap.
+                for (const chunk of splitStepText(part).flatMap(part => [...part].length > 2000 ? part.match(/.{1,2000}/gsu)! : [part]))
+                    emit({ ...body, payload: { ...payload, [key]: chunk } } as WireEventBody)
+            }
+            return
+        }
+        const found = this.db.query<{ event: string | null, frames: string | null }, [string]>(
+            'select event, frames from journal where id=?',
+        ).get(event.eventId)
+        if (found?.event === null)
+            return
+        if (!found)
+            this.db.query('insert into journal(id,event) values (?,?)').run(event.eventId, JSON.stringify(event))
+        await this.deliver(event.eventId, event, found?.frames ?? null, emit)
+    }
+
+    private async deliver(id: string, event: AgentEvent, saved: string | null, emit: (body: WireEventBody) => void): Promise<void> {
+        this.currentEventId = id
+        const frames = saved ? JSON.parse(saved) as WireEventBody[] : await this.project(event)
+        if (!saved)
+            this.db.query('update journal set frames=? where id=?').run(JSON.stringify(frames), id)
+        for (const frame of frames)
+            emit(frame)
+        this.db.query('update journal set event=null, frames=null where id=?').run(id)
+    }
+
+    private async project(event: AgentEvent): Promise<WireEventBody[]> {
+        const kind = event.type.startsWith('message.')
+            ? 'message'
+            : event.type.startsWith('tool.call.')
+                ? 'tool'
+                : event.type.startsWith('reasoning.') ? 'reasoning' : undefined
+        if (!kind || !('turnId' in event)) {
+            const frames: WireEventBody[] = []
+            if (event.type === 'turn.ended' || event.type === 'session.ended') {
+                for (const row of this.db.query<{ body: string, last_event_id: string | null }, []>('select body, last_event_id from steps').all()) {
+                    const step = JSON.parse(row.body) as StepDetailV1
+                    if ((step.status !== 'running' && row.last_event_id !== event.eventId) || (event.type === 'turn.ended' && (step.turnId !== event.turnId || step.actor.actorId !== event.actor.actorId)))
+                        continue
+                    step.status = event.type === 'turn.ended' && event.payload.status === 'failed' ? 'failed' : 'interrupted'
+                    step.incomplete = true
+                    step.endedAt = event.timestamp
+                    frames.push(...await this.finish(step))
+                }
+            }
+            frames.push(wrapAgentEvent(event))
+            return frames
+        }
+        const payload = event.payload as Record<string, unknown>
+        const sourceId = String(payload.messageId ?? payload.toolCallId ?? payload.reasoningId)
+        const identity = { sessionId: event.sessionId, providerSessionId: event.providerSessionId, actor: event.actor, turnId: event.turnId, kind: kind as StepSummary['kind'], sourceId }
+        const stepId = stepIdFor(identity)
+        const row = this.db.query<{ body: string, last_event_id: string | null }, [string]>('select body, last_event_id from steps where id=?').get(stepId)
+        const step: StepDetailV1 = row
+            ? JSON.parse(row.body)
+            : {
+                    ...identity,
+                    stepId,
+                    version: 1,
+                    provider: event.provider,
+                    commandId: typeof payload.commandId === 'string' ? payload.commandId : null,
+                    role: kind === 'message' ? payload.role as StepSummary['role'] : null,
+                    toolName: typeof payload.toolName === 'string' ? payload.toolName : null,
+                    status: 'running',
+                    incomplete: !event.type.endsWith('started'),
+                    startedAt: event.timestamp,
+                    endedAt: null,
+                    preview: '',
+                    content: {},
+                }
+        if (step.status !== 'running' && row?.last_event_id !== event.eventId)
+            return []
+        if (event.type.endsWith('started')) {
+            if (row && row.last_event_id !== event.eventId)
+                return []
+            if (step.status !== 'running')
+                return []
+            if (kind === 'tool') {
+                step.content.input = payload.input as StepDetailV1['content'][string] ?? null
+                step.preview = stepPreview(payload.input)
+            }
+            this.save(step)
+            return [this.frame('product.step.started', { step: summary(step) })]
+        }
+        if (kind === 'message') {
+            step.content.text = typeof payload.text === 'string' ? payload.text : ''
+            step.preview = ''
+        }
+        else if (kind === 'tool') {
+            step.content.output = payload.output as StepDetailV1['content'][string] ?? null
+            step.content.error = payload.error as StepDetailV1['content'][string] ?? null
+            step.preview = stepPreview(payload.output ?? payload.error)
+        }
+        else {
+            step.content.summary = typeof payload.summary === 'string' ? payload.summary : ''
+            step.preview = stepPreview(payload.summary)
+        }
+        step.status = payload.status === 'failed' ? 'failed' : payload.status === 'cancelled' ? 'interrupted' : 'completed'
+        if (kind === 'tool' && payload.output === undefined && payload.error === undefined) {
+            step.incomplete = true
+            step.status = 'interrupted'
+        }
+        step.endedAt = event.timestamp
+        if (payload.overflow)
+            throw new Error('Step projection requires complete provider content before overflow truncation.')
+        return await this.finish(step)
+    }
+
+    private async finish(step: StepDetailV1): Promise<WireEventBody[]> {
+        if (step.kind === 'message') {
+            // References, not repeated complete tool payloads, connect message content.
+            step.content.toolSteps = this.db.query<{ id: string }, [string, string]>(`
+                select id from steps where json_extract(body,'$.kind')='tool'
+                and json_extract(body,'$.turnId')=? and json_extract(body,'$.actor.actorId')=? order by rowid
+            `).all(step.turnId, step.actor.actorId).map(row => row.id)
+        }
+        this.save(step)
+        const body = serializeStepDetail(step)
+        const sha256 = createHash('sha256').update(body).digest('hex')
+        const byteSize = Buffer.byteLength(body)
+        const text = step.kind === 'message' && typeof step.content.text === 'string' ? splitStepText(step.content.text) : []
+        const detailSource = byteSize <= 32 * 1024
+            ? { detail: step }
+            : { reference: await this.options.upload({ stepId: step.stepId, sha256, byteSize, body }) }
+        return [
+            ...text.map((part, index) => this.frame('product.step.text', { step: summary(step), index, count: text.length, text: part })),
+            this.frame('product.step.closed', { step: summary(step), sha256, byteSize, textParts: text.length, ...detailSource }),
+        ]
+    }
+
+    private save(step: StepDetailV1): void {
+        this.db.query('insert into steps(id,body,last_event_id) values (?,?,?) on conflict(id) do update set body=excluded.body,last_event_id=excluded.last_event_id')
+            .run(step.stepId, JSON.stringify(step), this.currentEventId)
+    }
+
+    private frame(type: `product.${string}`, payload: unknown): WireEventBody {
+        return { type, payload } as WireEventBody
+    }
+}
+
+function summary(step: StepDetailV1): StepSummary {
+    const { content: _content, ...value } = step
+    return value
+}

package/src/supervisor/agent-provider-factory.ts

@@ -16,6 +16,10 @@ export interface AgentProviderBindingStore {
 }
 
 export interface AgentSupervisorProviderFactoryOptions {
+    eventProcessor?: {
+        recover: (emit: (body: WireEventBody) => void) => Promise<void>
+        process: (event: AgentEvent, emit: (body: WireEventBody) => void) => Promise<void>
+    }
     createProvider: (input: {
         bootstrap: SessionBootstrapBody
         credentials?: EphemeralCredentials
@@ -69,6 +73,9 @@ export function createAgentSupervisorProviderFactory(
 
         return new AgentSupervisorRuntime({
             run,
+            emit: input.emit,
+            onFatal: input.onFatal,
+            eventProcessor: options.eventProcessor,
             prepareInputAttachments: options.prepareInputAttachments,
             onSecretsRefreshed: options.onSecretsRefreshed,
         })
@@ -76,17 +83,27 @@ export function createAgentSupervisorProviderFactory(
 }
 
 class AgentSupervisorRuntime implements SupervisorAgentRuntime {
+    private readonly attached = Promise.withResolvers<void>()
     private state: SupervisorAgentRunSnapshot = { status: 'attached', agentState: null }
     private emit: ((body: WireEventBody) => void) | undefined
     private readonly pendingEvents: WireEventBody[] = []
     private readonly eventPump: Promise<void>
+    private eventFailure: unknown
 
     constructor(private readonly input: {
         run: AgentRun
+        emit?: (body: WireEventBody) => void
+        onFatal?: (error: unknown) => void
+        eventProcessor?: AgentSupervisorProviderFactoryOptions['eventProcessor']
         prepareInputAttachments?: AgentSupervisorProviderFactoryOptions['prepareInputAttachments']
         onSecretsRefreshed?: AgentSupervisorProviderFactoryOptions['onSecretsRefreshed']
     }) {
-        this.eventPump = this.consumeEvents()
+        if (input.emit)
+            this.attachEmitter(input.emit)
+        this.eventPump = this.consumeEvents().catch((error: unknown) => {
+            this.eventFailure = error
+            input.onFatal?.(error)
+        })
     }
 
     snapshot(): SupervisorAgentRunSnapshot {
@@ -94,6 +111,8 @@ class AgentSupervisorRuntime implements SupervisorAgentRuntime {
     }
 
     async handle(input: Parameters<SupervisorAgentRuntime['handle']>[0]): Promise<void> {
+        if (this.eventFailure)
+            throw this.eventFailure
         this.attachEmitter(input.emit)
         const metadata = this.input.run.metadata
         if (input.body.type === 'agent.send-prompt') {
@@ -154,6 +173,7 @@ class AgentSupervisorRuntime implements SupervisorAgentRuntime {
     }
 
     async close(input: { signal: AbortSignal }): Promise<void> {
+        this.attached.resolve()
         const metadata = this.input.run.metadata
         await this.input.run.stop({
             type: 'agent.stop',
@@ -167,15 +187,25 @@ class AgentSupervisorRuntime implements SupervisorAgentRuntime {
 
     private attachEmitter(emit: (body: WireEventBody) => void): void {
         this.emit = emit
+        this.attached.resolve()
         for (const event of this.pendingEvents.splice(0))
             emit(event)
     }
 
     private async consumeEvents(): Promise<void> {
+        if (this.input.eventProcessor) {
+            await this.attached.promise
+            if (!this.emit)
+                return
+            await this.input.eventProcessor.recover(body => this.emit!(body))
+        }
         for await (const event of this.input.run.events) {
             if (event.type === 'session.state.changed')
                 this.state = { status: 'attached', agentState: event.payload.state }
-            this.emitEvent(event)
+            if (this.input.eventProcessor)
+                await this.input.eventProcessor.process(event, body => this.emit!(body))
+            else
+                this.emitEvent(event)
         }
     }
 

package/src/supervisor/provider-factory.ts

@@ -27,6 +27,8 @@ export interface SupervisorProviderFactory {
         gitToken?: SessionBootstrapGitToken
         rpc: SupervisorRpcClient
         signal: AbortSignal
+        emit?: (body: WireEventBody) => void
+        onFatal?: (error: unknown) => void
     }) => Promise<SupervisorAgentRuntime>
 }
 

package/src/supervisor/runtime-handler.ts

@@ -185,6 +185,8 @@ export class SupervisorRuntimeHandler implements RuntimeConnectionHandler {
                 ...initialSecrets,
                 rpc: this.rpc,
                 signal: this.lifecycleController.signal,
+                emit: body => this.emit(body),
+                onFatal: error => this.dependencies.onFatal(error),
             }).then(async (agent) => {
                 if ((this.dependencies.credentials !== initialSecrets.credentials
                     || this.dependencies.gitToken !== initialSecrets.gitToken) && agent.refreshSecrets) {