@namzu/sdk 0.1.1

package/src/runtime/query/executor.ts

@@ -0,0 +1,171 @@
+import type { ToolRegistry } from "../../registry/tool/execute.js";
+import type { ActivityStore } from "../../store/activity/memory.js";
+import type { RunId } from "../../types/ids/index.js";
+import { type Message, createToolMessage } from "../../types/message/index.js";
+import type { PermissionMode } from "../../types/permission/index.js";
+import type { ChatCompletionResponse } from "../../types/provider/index.js";
+import type { RunEvent } from "../../types/run/index.js";
+import type { ToolContext } from "../../types/tool/index.js";
+import type { Logger } from "../../utils/logger.js";
+
+export type EmitEvent = (event: RunEvent) => Promise<void>;
+
+export interface ToolExecutorConfig {
+	tools: ToolRegistry;
+	runId: RunId;
+	workingDirectory: string;
+	permissionMode: PermissionMode;
+	env: Record<string, string>;
+	abortSignal: AbortSignal;
+}
+
+export interface ToolExecutionBatch {
+	messages: Message[];
+	results: Array<{ toolCallId: string; output: string }>;
+}
+
+export class ToolExecutor {
+	private config: ToolExecutorConfig;
+	private activityStore: ActivityStore;
+	private emitEvent: EmitEvent;
+	private log: Logger;
+
+	constructor(
+		config: ToolExecutorConfig,
+		activityStore: ActivityStore,
+		emitEvent: EmitEvent,
+		log: Logger,
+	) {
+		this.config = config;
+		this.activityStore = activityStore;
+		this.emitEvent = emitEvent;
+		this.log = log;
+	}
+
+	async executeBatch(
+		response: ChatCompletionResponse,
+	): Promise<ToolExecutionBatch> {
+		const toolCalls = response.message.toolCalls;
+		if (!toolCalls) {
+			return { messages: [], results: [] };
+		}
+
+		this.log.debug('Executing tool batch', {
+			runId: this.config.runId,
+			toolCount: toolCalls.length,
+			tools: toolCalls.map((tc) => tc.function.name),
+		});
+
+		const toolContext = this.buildToolContext();
+
+		const results = await Promise.all(
+			toolCalls.map((toolCall) => this.executeSingle(toolCall, toolContext)),
+		);
+
+		const messages: Message[] = results.map((r) =>
+			createToolMessage(r.output, r.toolCallId),
+		);
+
+		return { messages, results };
+	}
+
+	private buildToolContext(): ToolContext {
+		return {
+			runId: this.config.runId,
+			workingDirectory: this.config.workingDirectory,
+			abortSignal: this.config.abortSignal,
+			env: this.config.env,
+			log: (level, message) => this.log[level](message),
+			permissionContext: {
+				mode: this.config.permissionMode,
+				sessionId: this.config.runId,
+				workingDirectory: this.config.workingDirectory,
+			},
+			toolRegistry: this.config.tools,
+		};
+	}
+
+	private async executeSingle(
+		toolCall: {
+			id: string;
+			type: string;
+			function: { name: string; arguments: string };
+		},
+		toolContext: ToolContext,
+	): Promise<{ toolCallId: string; output: string }> {
+		const toolName = toolCall.function.name;
+		let input: unknown;
+
+		try {
+			input = JSON.parse(toolCall.function.arguments);
+		} catch {
+			return {
+				toolCallId: toolCall.id,
+				output: `Error: Invalid JSON in tool arguments for "${toolName}"`,
+			};
+		}
+
+		const activity = this.activityStore.create({
+			type: "tool_call",
+			description: toolName,
+			input,
+			toolName,
+			toolCallId: toolCall.id,
+		});
+		if (activity) {
+			this.activityStore.start(activity.id);
+		}
+
+		await this.emitEvent({
+			type: "tool_executing",
+			runId: this.config.runId,
+			toolName,
+			input,
+		});
+
+		const startMs = Date.now();
+		const result = await this.config.tools.execute(
+			toolName,
+			input,
+			toolContext,
+		);
+		const durationMs = Date.now() - startMs;
+
+		const output = result.success
+			? result.output
+			: `Error: ${result.error ?? "Tool execution failed"}`;
+
+		if (result.success) {
+			this.log.debug('Tool executed successfully', {
+				runId: this.config.runId,
+				tool: toolName,
+				durationMs,
+				outputLength: output.length,
+			});
+		} else {
+			this.log.warn('Tool execution failed', {
+				runId: this.config.runId,
+				tool: toolName,
+				durationMs,
+				error: result.error ?? 'unknown',
+			});
+		}
+
+		if (activity) {
+			if (result.success) {
+				this.activityStore.complete(activity.id, output);
+			} else {
+				this.activityStore.fail(activity.id, result.error ?? "Tool execution failed");
+			}
+		}
+
+		await this.emitEvent({
+			type: "tool_completed",
+			runId: this.config.runId,
+			toolName,
+			result: output,
+		});
+
+		return { toolCallId: toolCall.id, output };
+	}
+}

package/src/runtime/query/guard.ts

@@ -0,0 +1,71 @@
+import type { StopReason, LimitCheckerConfig } from '../../types/run/index.js'
+import type { RunPersistence } from '../../manager/run/persistence.js'
+import { type LimitCheckResult, checkLimitsDetailed, buildLimitConfig } from '../../run/LimitChecker.js'
+
+export interface GuardConfig {
+  tokenBudget: number
+  timeoutMs: number
+  costLimitUsd?: number
+  maxIterations?: number
+}
+
+export interface GuardCheckResult {
+  shouldStop: boolean
+  forceFinalize: boolean
+  stopReason?: StopReason
+  isCancelled: boolean
+}
+
+export class GuardCoordinator {
+  private limitConfig: LimitCheckerConfig
+  private startTime: number
+
+  constructor(config: GuardConfig) {
+    this.limitConfig = buildLimitConfig(
+      config.tokenBudget,
+      config.timeoutMs,
+      config.costLimitUsd,
+      config.maxIterations,
+    )
+    this.startTime = Date.now()
+  }
+
+  beforeIteration(
+    sessionMgr: RunPersistence,
+    abortSignal: AbortSignal,
+  ): GuardCheckResult {
+    const limitState = {
+      aborted: abortSignal.aborted,
+      totalTokens: sessionMgr.tokenUsage.totalTokens,
+      totalCost: sessionMgr.costInfo.totalCost,
+      currentIteration: sessionMgr.currentIteration,
+      startTime: this.startTime,
+    }
+
+    const limitResult = checkLimitsDetailed(this.limitConfig, limitState)
+
+    if (limitResult.type === 'hard_stop') {
+      return {
+        shouldStop: true,
+        forceFinalize: false,
+        stopReason: limitResult.reason,
+        isCancelled: limitResult.reason === 'cancelled',
+      }
+    }
+
+    if (limitResult.type === 'warning') {
+      return {
+        shouldStop: false,
+        forceFinalize: true,
+        stopReason: limitResult.reason,
+        isCancelled: false,
+      }
+    }
+
+    return {
+      shouldStop: false,
+      forceFinalize: false,
+      isCancelled: false,
+    }
+  }
+}

package/src/runtime/query/index.ts

@@ -0,0 +1,321 @@
+import type {
+  AgentRun,
+  AgentRunConfig,
+  RunEvent,
+  RunEventListener,
+} from '../../types/run/index.js'
+import type { LLMProvider } from '../../types/provider/index.js'
+import type { ModelPricing } from '../../utils/cost.js'
+import type { AgentPersona } from '../../types/persona/index.js'
+import type { Skill } from '../../types/skills/index.js'
+import type { ToolRegistry } from '../../registry/tool/execute.js'
+import type { ResumeHandler, CheckpointId } from '../../types/hitl/index.js'
+import type { ThreadId, RunId } from '../../types/ids/index.js'
+import type { AgentContextLevel } from '../../types/agent/factory.js'
+import type { RuntimeToolOverrides } from '../../types/agent/base.js'
+import type { TaskStore } from '../../types/task/index.js'
+import type { ContextCache } from './context-cache.js'
+import { buildTaskTools } from '../../tools/task/index.js'
+import { SearchToolsTool } from '../../tools/builtins/search-tools.js'
+import { autoApproveHandler } from '../../types/hitl/index.js'
+import { type Message, createSystemMessage } from '../../types/message/index.js'
+import { getTracer } from '../../provider/telemetry/setup.js'
+import {
+  GENAI,
+  NAMZU,
+  agentSessionSpanName,
+} from '../../telemetry/attributes.js'
+import { RunContextFactory } from './context.js'
+import { PromptBuilder } from './prompt.js'
+import { ToolingBootstrap } from './tooling.js'
+import { GuardCoordinator } from './guard.js'
+import { EventTranslator } from './events.js'
+import { IterationOrchestrator } from './iteration/index.js'
+import { ResultAssembler } from './result.js'
+import { CheckpointManager } from './checkpoint.js'
+
+export interface QueryParams {
+  systemPrompt?: string
+  persona?: AgentPersona
+  skills?: Skill[]
+  basePrompt?: string
+  provider: LLMProvider
+  tools: ToolRegistry
+  sessionConfig: AgentRunConfig
+  allowedTools?: string[]
+  agentId: string
+  agentName: string
+  workingDirectory?: string
+  pricing?: ModelPricing
+  enableActivityTracking?: boolean
+  messages: Message[]
+  signal?: AbortSignal
+  resumeHandler: ResumeHandler
+  resumeFromCheckpoint?: CheckpointId
+
+  threadId: ThreadId
+
+  runId?: RunId
+
+  parentRunId?: RunId
+
+  depth?: number
+
+  contextCache?: ContextCache
+
+  contextLevel?: AgentContextLevel
+
+  continuationMode?: boolean
+
+  taskStore?: TaskStore
+
+  runtimeToolOverrides?: RuntimeToolOverrides
+
+  taskGateway?: import('../../types/agent/gateway.js').TaskGateway
+
+  launchedTasks?: Map<import('../../types/ids/index.js').TaskId, import('./iteration/phases/context.js').LaunchedTaskMeta>
+
+  onContextCreated?: (ctx: { planManager: import('../../manager/plan/lifecycle.js').PlanManager }) => void
+}
+
+export async function* query(
+  params: QueryParams,
+): AsyncGenerator<RunEvent, AgentRun> {
+  const ctx = RunContextFactory.build({
+    agentId: params.agentId,
+    agentName: params.agentName,
+    sessionConfig: params.sessionConfig,
+    provider: params.provider,
+    workingDirectory: params.workingDirectory,
+    pricing: params.pricing,
+    enableActivityTracking: params.enableActivityTracking,
+    messages: params.messages,
+    signal: params.signal,
+    threadId: params.threadId,
+    runId: params.runId,
+    parentRunId: params.parentRunId,
+    depth: params.depth,
+  })
+
+  ctx.planManager.setApprovalHandler(async (request) => {
+    const decision = await params.resumeHandler({
+      type: 'plan_approval',
+      runId: ctx.runId,
+      checkpointId: `cp_plan_${request.planId}` as import('../../types/ids/index.js').CheckpointId,
+      plan: {
+        planId: request.planId,
+        title: request.title,
+        steps: request.steps.map((s, i) => ({
+          id: s.id,
+          description: s.description,
+          toolName: s.toolName,
+          dependsOn: s.dependsOn,
+          order: s.order ?? i + 1,
+        })),
+        summary: request.summary,
+      },
+    })
+
+    if (decision.action === 'approve_plan') {
+      return { approved: true }
+    }
+    if (decision.action === 'reject_plan') {
+      return { approved: false, feedback: decision.feedback }
+    }
+
+    return { approved: false, feedback: `Action: ${decision.action}` }
+  })
+
+  params.onContextCreated?.({ planManager: ctx.planManager })
+
+  const eventTranslator = new EventTranslator(ctx.sessionMgr)
+  eventTranslator.wireActivityStore(ctx.activityStore, ctx.runId)
+  eventTranslator.wirePlanManager(ctx.planManager, ctx.runId)
+  const unsubscribeTaskStore = params.taskStore
+    ? eventTranslator.wireTaskStore(params.taskStore, ctx.runId)
+    : undefined
+
+  if (params.taskStore) {
+    const taskTools = buildTaskTools(params.taskStore, ctx.runId)
+    const overrides = params.runtimeToolOverrides
+    for (const tool of taskTools) {
+      const override = overrides?.[tool.name]
+      if (override === 'disabled') continue
+      params.tools.register(tool, override ?? 'deferred')
+    }
+  }
+
+  if (!params.tools.has(SearchToolsTool.name)) {
+    const hasDeferred = params.tools.listNames().some(
+      (n) => params.tools.getAvailability(n) === 'deferred',
+    )
+    if (hasDeferred) {
+      params.tools.register(SearchToolsTool)
+    }
+  }
+
+  const toolExecutor = ToolingBootstrap.init(
+    {
+      tools: params.tools,
+      runId: ctx.runId,
+      workingDirectory: ctx.cwd,
+      permissionMode: ctx.permissionMode,
+      env: params.sessionConfig.env ?? {},
+      abortSignal: ctx.abortController.signal,
+    },
+    ctx.activityStore,
+    eventTranslator.emitEvent,
+    ctx.log,
+  )
+
+  const promptBuilder = new PromptBuilder({
+    systemPrompt: params.systemPrompt,
+    persona: params.persona,
+    skills: params.skills,
+    basePrompt: params.basePrompt,
+    tools: params.tools,
+    allowedTools: params.allowedTools,
+  })
+
+  const guard = new GuardCoordinator({
+    tokenBudget: params.sessionConfig.tokenBudget,
+    timeoutMs: params.sessionConfig.timeoutMs,
+    costLimitUsd: params.sessionConfig.costLimitUsd,
+    maxIterations: params.sessionConfig.maxIterations,
+  })
+
+  const checkpointMgr = new CheckpointManager(ctx.sessionMgr.getRunStore())
+
+  const resultAssembler = new ResultAssembler({
+    sessionMgr: ctx.sessionMgr,
+    planManager: ctx.planManager,
+    activityStore: ctx.activityStore,
+    log: ctx.log,
+    emitEvent: eventTranslator.emitEvent,
+    drainPending: () => eventTranslator.drainPending(),
+  })
+
+  const iterationOrchestrator = new IterationOrchestrator(
+    {
+      provider: params.provider,
+      sessionConfig: params.sessionConfig,
+      tools: params.tools,
+      allowedTools: params.allowedTools,
+      taskGateway: params.taskGateway,
+      taskStore: params.taskStore,
+      launchedTasks: params.launchedTasks,
+    },
+    ctx.sessionMgr,
+    toolExecutor,
+    guard,
+    ctx.activityStore,
+    eventTranslator.emitEvent,
+    () => eventTranslator.drainPending(),
+    ctx.abortController,
+    ctx.log,
+    params.resumeHandler,
+    checkpointMgr,
+    ctx.planManager,
+  )
+
+  const tracer = getTracer()
+
+  return yield* (async function* (): AsyncGenerator<RunEvent, AgentRun> {
+    const rootSpan = tracer.startSpan(agentSessionSpanName(params.agentName))
+    rootSpan.setAttributes({
+      [NAMZU.SESSION_ID]: ctx.sessionMgr.id,
+      [GENAI.AGENT_NAME]: params.agentName,
+      [GENAI.AGENT_ID]: params.agentId,
+      [GENAI.REQUEST_MODEL]: params.sessionConfig.model,
+      [GENAI.SYSTEM]: params.provider.id,
+    })
+
+    try {
+      await ctx.sessionMgr.init()
+
+      ctx.log.info('Starting query', {
+        runId: ctx.sessionMgr.id,
+        agent: params.agentName,
+        model: params.sessionConfig.model,
+        tokenBudget: params.sessionConfig.tokenBudget,
+        activityTracking: ctx.activityStore.enabled,
+        permissionMode: ctx.permissionMode,
+        resumeFromCheckpoint: params.resumeFromCheckpoint ?? null,
+      })
+
+      const contextLevel = params.contextLevel ?? 'full'
+      const assembledPrompt = params.contextCache
+        ? params.contextCache.getSystemPrompt({
+            systemPrompt: params.systemPrompt,
+            persona: params.persona,
+            skills: params.skills,
+            basePrompt: contextLevel === 'full' ? params.basePrompt : undefined,
+            tools: params.tools,
+            allowedTools: params.allowedTools,
+          })
+        : promptBuilder.build(contextLevel, params.workingDirectory)
+
+      if (params.resumeFromCheckpoint) {
+        const checkpoint = await checkpointMgr.restore(params.resumeFromCheckpoint)
+        await eventTranslator.emitEvent({
+          type: 'run_resuming',
+          runId: ctx.sessionMgr.id,
+          fromCheckpointId: checkpoint.id,
+        })
+        yield* eventTranslator.drainPending()
+
+        ctx.sessionMgr.pushMessage(createSystemMessage(assembledPrompt))
+        for (const msg of checkpoint.messages) {
+          if (msg.role === 'system') continue
+          ctx.sessionMgr.pushMessage(msg)
+        }
+      } else if (params.continuationMode) {
+        for (const msg of params.messages) {
+          ctx.sessionMgr.pushMessage(msg)
+        }
+      } else {
+        ctx.sessionMgr.pushMessage(createSystemMessage(assembledPrompt))
+        for (const msg of params.messages) {
+          if (msg.role === 'system') continue
+          ctx.sessionMgr.pushMessage(msg)
+        }
+      }
+
+      ctx.sessionMgr.markRunning()
+      await eventTranslator.emitEvent({ type: 'run_started', runId: ctx.sessionMgr.id, systemPrompt: assembledPrompt })
+      yield* eventTranslator.drainPending()
+
+      yield* iterationOrchestrator.runLoop()
+
+      yield* resultAssembler.completeRun(rootSpan)
+    } catch (err) {
+      yield* resultAssembler.handleError(err, rootSpan)
+    } finally {
+      unsubscribeTaskStore?.()
+      rootSpan.end()
+    }
+
+    return await resultAssembler.finalize()
+  })()
+}
+
+export async function drainQuery(
+  params: Omit<QueryParams, 'resumeHandler'> & { resumeHandler?: ResumeHandler },
+  listener?: RunEventListener,
+): Promise<AgentRun> {
+  const fullParams: QueryParams = {
+    ...params,
+    resumeHandler: params.resumeHandler ?? autoApproveHandler,
+  }
+  const gen = query(fullParams)
+  let result = await gen.next()
+
+  while (!result.done) {
+    if (listener) {
+      await listener(result.value)
+    }
+    result = await gen.next()
+  }
+
+  return result.value
+}