@namzu/sdk 0.4.3 → 0.4.5

package/src/runtime/query/executor.ts

@@ -1,6 +1,9 @@
 import { extractFromToolCall, extractFromToolResult } from '../../compaction/extractor.js'
 import type { WorkingStateManager } from '../../compaction/manager.js'
 import type { PluginLifecycleManager } from '../../plugin/lifecycle.js'
+import { buildProbeContext } from '../../probe/context.js'
+import { ProbeVetoError } from '../../probe/errors.js'
+import { type ProbeRegistry, probe as defaultProbeRegistry } from '../../probe/registry.js'
 import type { ActivityStore } from '../../store/activity/memory.js'
 import type { RunId } from '../../types/ids/index.js'
 import type { InvocationState } from '../../types/invocation/index.js'
@@ -44,17 +47,20 @@ export class ToolExecutor {
 	private emitEvent: EmitEvent
 	private log: Logger
 	private workingStateManager?: WorkingStateManager
+	private probes: ProbeRegistry
 
 	constructor(
 		config: ToolExecutorConfig,
 		activityStore: ActivityStore,
 		emitEvent: EmitEvent,
 		log: Logger,
+		probes: ProbeRegistry = defaultProbeRegistry,
 	) {
 		this.config = config
 		this.activityStore = activityStore
 		this.emitEvent = emitEvent
 		this.log = log
+		this.probes = probes
 	}
 
 	setWorkingStateManager(manager: WorkingStateManager): void {
@@ -150,6 +156,34 @@ export class ToolExecutor {
 			input,
 		})
 
+		const vetoOutcome = this.probes.queryVeto(
+			{
+				type: 'tool_executing',
+				runId: this.config.runId,
+				toolName,
+				input,
+			},
+			buildProbeContext({ runId: this.config.runId }),
+		)
+		if (vetoOutcome.action === 'deny') {
+			const probeName = vetoOutcome.probeName ?? 'unnamed'
+			const reason = vetoOutcome.reason ?? 'no reason provided'
+			const veto = new ProbeVetoError(probeName, reason, 'tool_executing')
+			this.log.warn('Tool call denied by probe', {
+				runId: this.config.runId,
+				tool: toolName,
+				probeName,
+				reason,
+			})
+			if (activity) {
+				this.activityStore.fail(activity.id, veto.message)
+			}
+			return {
+				toolCallId: toolCall.id,
+				output: `Error: ${veto.message}`,
+			}
+		}
+
 		if (this.workingStateManager) {
 			extractFromToolCall(this.workingStateManager, toolName, JSON.stringify(input))
 		}

package/src/types/bus/index.ts

@@ -1,6 +1,8 @@
-import type { RunId } from '../ids/index.js'
+import type { CredentialId, LockId, RunId, SandboxId, TenantId } from '../ids/index.js'
 
-export type LockId = `lock_${string}`
+export type { LockId } from '../ids/index.js'
+
+export type ProviderCallId = `pcall_${string}`
 
 export type CircuitBreakerState = 'closed' | 'open' | 'half_open'
 
@@ -35,6 +37,15 @@ export type OwnershipClaimResult =
 	| { claimed: true; ownership: FileOwnership }
 	| { claimed: false; currentOwner: RunId; filePath: string }
 
+export interface ProviderCallUsage {
+	readonly inputTokens?: number
+	readonly outputTokens?: number
+	readonly totalTokens?: number
+	readonly costUsd?: number
+}
+
+export type SandboxDecisionAction = 'allow' | 'deny'
+
 export type AgentBusEvent =
 	| { type: 'lock_acquired'; lockId: LockId; filePath: string; owner: RunId }
 	| { type: 'lock_released'; lockId: LockId; filePath: string; owner: RunId }
@@ -49,5 +60,46 @@ export type AgentBusEvent =
 	| { type: 'breaker_half_open'; agentRunId: RunId }
 	| { type: 'breaker_probe_success'; agentRunId: RunId }
 	| { type: 'breaker_probe_failure'; agentRunId: RunId }
+	| {
+			type: 'provider_call_start'
+			providerId: string
+			model: string
+			callId: ProviderCallId
+			runId?: RunId
+	  }
+	| {
+			type: 'provider_call_completed'
+			providerId: string
+			model: string
+			callId: ProviderCallId
+			runId?: RunId
+			durationMs: number
+			usage?: ProviderCallUsage
+	  }
+	| {
+			type: 'provider_call_failed'
+			providerId: string
+			model: string
+			callId: ProviderCallId
+			runId?: RunId
+			durationMs: number
+			error: string
+	  }
+	| {
+			type: 'vault_lookup'
+			vaultId: string
+			credentialId?: CredentialId
+			tenantId?: TenantId
+			found: boolean
+			runId?: RunId
+	  }
+	| {
+			type: 'sandbox_decision'
+			sandboxId: SandboxId
+			action: SandboxDecisionAction
+			resource: string
+			ruleId?: string
+			runId?: RunId
+	  }
 
 export type AgentBusEventListener = (event: AgentBusEvent) => void

package/src/types/doctor/check.ts

@@ -0,0 +1,53 @@
+export type DoctorStatus = 'pass' | 'fail' | 'inconclusive' | 'warn'
+
+export type DoctorCategory =
+	| 'sandbox'
+	| 'providers'
+	| 'vault'
+	| 'telemetry'
+	| 'runtime'
+	| 'plugins'
+	| 'custom'
+
+export interface DoctorCheckContext {
+	readonly cwd: string
+	readonly env: Readonly<Record<string, string | undefined>>
+	readonly projectRoot: string | null
+}
+
+export interface DoctorCheckResult {
+	readonly status: DoctorStatus
+	readonly message?: string
+	readonly remediation?: string
+	readonly durationMs?: number
+}
+
+export interface DoctorCheck {
+	readonly id: string
+	readonly category: DoctorCategory
+	readonly run: (ctx: DoctorCheckContext) => Promise<DoctorCheckResult>
+	readonly fix?: (ctx: DoctorCheckContext) => Promise<DoctorCheckResult>
+}
+
+export interface DoctorCheckRecord {
+	readonly id: string
+	readonly category: DoctorCategory
+	readonly status: DoctorStatus
+	readonly message?: string
+	readonly remediation?: string
+	readonly durationMs: number
+}
+
+export interface DoctorReport {
+	readonly version: string
+	readonly timestamp: string
+	readonly checks: readonly DoctorCheckRecord[]
+	readonly summary: {
+		readonly pass: number
+		readonly fail: number
+		readonly inconclusive: number
+		readonly warn: number
+		readonly total: number
+	}
+	readonly exit: 0 | 1 | 2 | 70
+}

package/src/types/doctor/index.ts

@@ -0,0 +1,9 @@
+export type {
+	DoctorCategory,
+	DoctorCheck,
+	DoctorCheckContext,
+	DoctorCheckRecord,
+	DoctorCheckResult,
+	DoctorReport,
+	DoctorStatus,
+} from './check.js'

package/src/types/probe/event-kind.ts

@@ -0,0 +1,8 @@
+import type { AgentBusEvent } from '../bus/index.js'
+import type { RunEvent } from '../run/events.js'
+
+export type ProbeEventKind = RunEvent['type'] | AgentBusEvent['type']
+
+export type VetoableEventKind = 'tool_executing'
+
+export type ProbeEvent = RunEvent | AgentBusEvent

package/src/types/probe/event-of.ts

@@ -0,0 +1,3 @@
+import type { ProbeEvent, ProbeEventKind } from './event-kind.js'
+
+export type ProbeEventOf<K extends ProbeEventKind> = Extract<ProbeEvent, { type: K }>

package/src/types/probe/index.ts

@@ -0,0 +1,11 @@
+export type { ProbeEvent, ProbeEventKind, VetoableEventKind } from './event-kind.js'
+export type { ProbeEventOf } from './event-of.js'
+export type {
+	ProbeContext,
+	ProbeHandler,
+	ProbeOptions,
+	Unsubscribe,
+	VetoDecision,
+	VetoHandler,
+	VetoOutcome,
+} from './registry.js'

package/src/types/probe/registry.ts

@@ -0,0 +1,36 @@
+import type { RunId } from '../ids/index.js'
+import type { ProbeEventKind, VetoableEventKind } from './event-kind.js'
+import type { ProbeEventOf } from './event-of.js'
+
+export type Unsubscribe = () => void
+
+export interface ProbeContext {
+	readonly runId?: RunId
+	readonly isReplay: boolean
+}
+
+export type ProbeHandler<K extends ProbeEventKind> = (
+	event: ProbeEventOf<K>,
+	ctx: ProbeContext,
+) => void
+
+export type VetoDecision = 'allow' | 'deny' | { readonly action: 'deny'; readonly reason: string }
+
+export type VetoHandler<K extends VetoableEventKind> = (
+	event: ProbeEventOf<K>,
+	ctx: ProbeContext,
+) => VetoDecision
+
+export interface VetoOutcome {
+	readonly action: 'allow' | 'deny'
+	readonly probeName?: string
+	readonly reason?: string
+}
+
+export interface ProbeOptions<K extends ProbeEventKind = ProbeEventKind> {
+	readonly where?: (event: ProbeEventOf<K>) => boolean
+	readonly priority?: number
+	readonly name?: string
+	readonly otel?: boolean
+	readonly override?: boolean
+}

package/src/types/provider/interface.ts

@@ -1,3 +1,5 @@
+import type { DoctorCheckResult } from '../doctor/index.js'
+
 import type { ChatCompletionParams, ChatCompletionResponse } from './chat.js'
 import type { ModelInfo } from './model.js'
 import type { StreamChunk } from './stream.js'
@@ -13,4 +15,14 @@ export interface LLMProvider {
 	listModels?(): Promise<ModelInfo[]>
 
 	healthCheck?(): Promise<boolean>
+
+	/**
+	 * Optional structured health probe used by `runDoctor()`.
+	 *
+	 * Returns a `DoctorCheckResult` with provider-specific detail
+	 * (latency, model availability, auth status, …). Providers that
+	 * cannot be cheaply probed should return `{ status: 'inconclusive' }`
+	 * so the doctor doesn't mark them as failing — see ses_007 Q6.4.
+	 */
+	doctorCheck?(): Promise<DoctorCheckResult>
 }

package/src/vault/instrumentation.test.ts

@@ -0,0 +1,98 @@
+import { describe, expect, it } from 'vitest'
+
+import { createProbeRegistry } from '../probe/registry.js'
+import type { AgentBusEvent } from '../types/bus/index.js'
+import type { CredentialId, TenantId } from '../types/ids/index.js'
+
+import { InMemoryCredentialVault } from './InMemoryCredentialVault.js'
+import { wrapVaultWithProbes } from './instrumentation.js'
+
+const tenant = 'tnt_acme' as TenantId
+const connector = 'conn_x' as never
+
+describe('wrapVaultWithProbes', () => {
+	it('emits vault_lookup with found:true when retrieve hits', async () => {
+		const reg = createProbeRegistry()
+		const seen: AgentBusEvent[] = []
+		reg.onAny((event) => seen.push(event as AgentBusEvent))
+
+		const inner = new InMemoryCredentialVault()
+		const ref = await inner.store(tenant, connector, 'k', { type: 'apiKey', apiKey: 's' } as never)
+		const wrapped = wrapVaultWithProbes(inner, { probes: reg, vaultId: 'in-memory' })
+
+		const result = await wrapped.retrieve(ref.id)
+		expect(result).toBeDefined()
+		expect(seen.length).toBe(1)
+		const event = seen[0] as AgentBusEvent & { type: 'vault_lookup' }
+		expect(event.type).toBe('vault_lookup')
+		expect(event.found).toBe(true)
+		expect(event.vaultId).toBe('in-memory')
+		expect(event.credentialId).toBe(ref.id)
+	})
+
+	it('emits vault_lookup with found:false when retrieve misses', async () => {
+		const reg = createProbeRegistry()
+		const seen: AgentBusEvent[] = []
+		reg.onAny((event) => seen.push(event as AgentBusEvent))
+
+		const wrapped = wrapVaultWithProbes(new InMemoryCredentialVault(), {
+			probes: reg,
+			vaultId: 'in-memory',
+		})
+		const missing = 'cred_missing' as CredentialId
+		const result = await wrapped.retrieve(missing)
+
+		expect(result).toBeUndefined()
+		expect(seen.length).toBe(1)
+		const event = seen[0] as AgentBusEvent & { type: 'vault_lookup' }
+		expect(event.found).toBe(false)
+		expect(event.credentialId).toBe(missing)
+	})
+
+	it('does not emit on store/revoke/list — retrieve is the audit point', async () => {
+		const reg = createProbeRegistry()
+		const seen: AgentBusEvent[] = []
+		reg.onAny((event) => seen.push(event as AgentBusEvent))
+
+		const wrapped = wrapVaultWithProbes(new InMemoryCredentialVault(), { probes: reg })
+		const ref = await wrapped.store(tenant, connector, 'k', {
+			type: 'apiKey',
+			apiKey: 's',
+		} as never)
+		await wrapped.list(tenant)
+		await wrapped.revoke(ref.id)
+		expect(seen.length).toBe(0)
+	})
+
+	it('does not leak the secret value in the emitted event', async () => {
+		const reg = createProbeRegistry()
+		const seen: AgentBusEvent[] = []
+		reg.onAny((event) => seen.push(event as AgentBusEvent))
+
+		const inner = new InMemoryCredentialVault()
+		const ref = await inner.store(tenant, connector, 'k', {
+			type: 'apiKey',
+			apiKey: 'super-secret-value',
+		} as never)
+		const wrapped = wrapVaultWithProbes(inner, { probes: reg })
+		await wrapped.retrieve(ref.id)
+
+		const event = seen[0]
+		const serialized = JSON.stringify(event)
+		expect(serialized).not.toContain('super-secret-value')
+	})
+
+	it('falls back to constructor.name as vaultId when not specified', async () => {
+		const reg = createProbeRegistry()
+		const seen: AgentBusEvent[] = []
+		reg.onAny((event) => seen.push(event as AgentBusEvent))
+
+		const inner = new InMemoryCredentialVault()
+		const ref = await inner.store(tenant, connector, 'k', { type: 'apiKey', apiKey: 's' } as never)
+		const wrapped = wrapVaultWithProbes(inner, { probes: reg })
+		await wrapped.retrieve(ref.id)
+
+		const event = seen[0] as AgentBusEvent & { type: 'vault_lookup' }
+		expect(event.vaultId).toBe('InMemoryCredentialVault')
+	})
+})

package/src/vault/instrumentation.ts

@@ -0,0 +1,56 @@
+import { buildProbeContext } from '../probe/context.js'
+import { type ProbeRegistry, probe as defaultProbeRegistry } from '../probe/registry.js'
+import type { AuthConfig, CredentialRef, CredentialVault } from '../types/connector/index.js'
+import type { ConnectorId, CredentialId, RunId, TenantId } from '../types/ids/index.js'
+
+export interface VaultInstrumentationOptions {
+	readonly probes?: ProbeRegistry
+	readonly runId?: RunId
+	readonly vaultId?: string
+	readonly tenantId?: TenantId
+}
+
+export function wrapVaultWithProbes(
+	vault: CredentialVault,
+	opts: VaultInstrumentationOptions = {},
+): CredentialVault {
+	const probes = opts.probes ?? defaultProbeRegistry
+	const runId = opts.runId
+	const vaultId = opts.vaultId ?? vault.constructor.name
+	const tenantIdHint = opts.tenantId
+
+	return {
+		store(
+			tenantId: TenantId,
+			connectorId: ConnectorId,
+			label: string,
+			auth: AuthConfig,
+		): Promise<CredentialRef> {
+			return vault.store(tenantId, connectorId, label, auth)
+		},
+
+		async retrieve(credentialId: CredentialId): Promise<AuthConfig | undefined> {
+			const result = await vault.retrieve(credentialId)
+			probes.dispatch(
+				{
+					type: 'vault_lookup',
+					vaultId,
+					credentialId,
+					tenantId: tenantIdHint,
+					found: result !== undefined,
+					runId,
+				},
+				buildProbeContext({ runId }),
+			)
+			return result
+		},
+
+		revoke(credentialId: CredentialId): Promise<boolean> {
+			return vault.revoke(credentialId)
+		},
+
+		list(tenantId: TenantId, connectorId?: ConnectorId): Promise<CredentialRef[]> {
+			return vault.list(tenantId, connectorId)
+		},
+	}
+}