import { Agent } from 'assistme-agent-sdk'

const agent = new Agent({
  name: string,                          // Required. Unique identifier.
  model: ModelProvider,                   // Required. The model to use.
  instructions: string | InstructionFn,  // Required. System prompt or dynamic function.
  tools?: Tool[],                        // Optional. Available tools.
  guardrails?: GuardrailConfig,          // Optional. Input/output guardrails.
  memory?: MemoryConfig,                 // Optional. Persistent memory.
  handoffs?: Agent[] | HandoffConfig[],  // Optional. Handoff targets.
  hooks?: AgentHooks,                    // Optional. Lifecycle hooks.
  modelParams?: ModelParams,             // Optional. Temperature, maxTokens, etc.
  maxTurns?: number,                     // Optional. Max tool-call iterations.
  output?: z.ZodType,                    // Optional. Structured output schema.
  limits?: AgentLimits,                  // Optional. Token/cost budgets.
  fallbackModels?: ModelProvider[],      // Optional. Fallback models.
  context?: ContextConfig,               // Optional. Compaction, caching settings.
  approvalPolicy?: ApprovalPolicy,       // Optional. Tool approval rules.
})

clone(overrides: Partial<AgentConfig>): Agent

asTool(config: { name: string; description: string }): Tool

readonly config: AgentConfig

import { Tool } from 'assistme-agent-sdk'

const tool = Tool.create({
  name: string,                          // Required. Tool identifier.
  description: string,                   // Required. What the tool does.
  parameters: z.ZodType,                 // Required. Zod schema for params.
  execute: (params, context) => Promise, // Required. Implementation.
  allowedAgents?: string[],              // Optional. Restrict access.
  requiresApproval?: boolean | Function, // Optional. Human approval gate.
  timeout?: number,                      // Optional. Timeout in ms.
  onError?: (error, params) => any,      // Optional. Error handler.
})

Tool.compose({
  name: string,
  description: string,
  parameters: z.ZodType,
  steps: ToolStep[],
})

Tool.group({
  name: string,
  description: string,
  tools: Tool[],
  defaults?: Partial<ToolConfig>,
}): ToolGroup

import { Runner } from 'assistme-agent-sdk'

const result: RunResult = await Runner.run(agent, {
  messages: Message[],                 // Required. Conversation messages.
  hooks?: RunnerHooks,                 // Optional. Runner-level hooks.
  tracer?: TraceExporter,              // Optional. Trace exporter.
  logger?: Logger,                     // Optional. Logger.
  metadata?: Record<string, unknown>,  // Optional. Run metadata.
  retry?: RetryConfig,                 // Optional. Retry settings.
  rateLimiter?: RateLimiter,           // Optional. Rate limiter.
  circuitBreaker?: CircuitBreaker,     // Optional. Circuit breaker.
  userId?: string,                     // Optional. User identifier.
})

const stream: AgentStream = Runner.stream(agent, {
  // Same options as Runner.run
})

// Async iterator
for await (const event: StreamEvent of stream) { ... }

// Get final result
const result: RunResult = await stream.finalResult()

// Convert to SSE
const response: ReadableStream = stream.toSSE()

// Approval management
stream.approve(toolCallId: string): void
stream.deny(toolCallId: string, reason?: string): void
const manager = stream.approvalManager(): ApprovalManager

interface RunResult {
  status: 'completed' | 'max_turns_reached' | 'guardrail_blocked' | 'handoff' | 'error'
  output: string                          // Agent's final text output
  messages: Message[]                     // Full message history
  toolCalls: ToolCallRecord[]             // All tool calls made
  usage: TokenUsage                       // Token usage breakdown
  trace: RunTrace                         // Full execution trace
  guardrailResult?: GuardrailResult       // If guardrail blocked
  handoffTarget?: Agent                   // If handoff occurred
  error?: Error                           // If error occurred
}

interface TokenUsage {
  inputTokens: number
  outputTokens: number
  totalTokens: number
  cacheReadTokens?: number
  cacheWriteTokens?: number
  cacheHitRate?: number
  contextTokens: number
  contextWindow: number
  compactions: number
}

import { Guardrail } from 'assistme-agent-sdk'

const guard = Guardrail.input({
  name: string,                                        // Required.
  validate: (input: string, context) => GuardrailResult // Required.
})

const guard = Guardrail.output({
  name: string,                                         // Required.
  validate: (output: string, context) => GuardrailResult // Required.
})

Guardrail.parallel(guardrails: Guardrail[]): Guardrail

interface GuardrailResult {
  allow: boolean
  reason?: string
  modified?: string
  metadata?: Record<string, unknown>
}

import { Memory } from 'assistme-agent-sdk'

const memory = Memory.persistent({
  store: MemoryStore,                    // Required. Storage backend.
  namespace: string,                     // Required. Isolation key.
  auto?: {
    extract?: boolean,                   // Auto-extract memories. Default: false.
    recall?: boolean,                    // Auto-load memories. Default: false.
    maxRecall?: number,                  // Max memories to load. Default: 10.
  },
  indexing?: {
    linkRelated?: boolean,               // Link related memories. Default: false.
    embedding?: boolean,                 // Use embeddings for search. Default: false.
    decay?: { enabled: boolean; halfLife: string }, // Memory decay.
  },
})

Memory.stores.sqlite(path: string): MemoryStore
Memory.stores.redis(options: RedisOptions): MemoryStore
Memory.stores.postgres(options: PostgresOptions): MemoryStore
Memory.stores.inMemory(): MemoryStore

memory.get(key: string): Promise<MemoryEntry | null>
memory.set(key: string, entry: MemoryEntry): Promise<void>
memory.search(query: string, options?: { limit?: number }): Promise<MemoryEntry[]>
memory.list(): Promise<MemoryEntry[]>
memory.delete(key: string): Promise<void>

interface MemoryEntry {
  type: 'semantic' | 'episodic' | 'procedural'
  content: string
  metadata?: Record<string, unknown>
  createdAt?: Date
  updatedAt?: Date
  relevanceScore?: number
}

import { claude } from 'assistme-agent-sdk-provider-claude'

claude(modelId: string, options?: {
  apiKey?: string,
  baseUrl?: string,
  maxRetries?: number,
}): ModelProvider

import { openai } from 'assistme-agent-sdk-provider-openai'

openai(modelId: string, options?: {
  apiKey?: string,
  baseUrl?: string,
  organization?: string,
}): ModelProvider

import { gemini } from 'assistme-agent-sdk-provider-gemini'

gemini(modelId: string, options?: {
  apiKey?: string,
}): ModelProvider

import { openaiCompatible } from 'assistme-agent-sdk-provider-openai-compatible'

openaiCompatible(modelId: string, options: {
  baseUrl: string,
  apiKey?: string,
}): ModelProvider

interface ModelProvider {
  name: string
  generate(request: ModelRequest): Promise<ModelResponse>
  stream(request: ModelRequest): AsyncGenerator<ModelStreamEvent>
  supports?(feature: ProviderFeature): boolean
}

type ProviderFeature = 'tool_use' | 'streaming' | 'structured_output' | 'vision' | 'extended_thinking'

import { Pipeline } from 'assistme-agent-sdk'

const pipeline = Pipeline.create(steps: PipelineStep[])
await pipeline.run(input: string): Promise<RunResult>

import { Parallel } from 'assistme-agent-sdk'

const results = await Parallel.run(
  tasks: ParallelTask[],
  options?: { aggregate?: (results) => Promise<RunResult> }
): Promise<RunResult[]>

import { Router } from 'assistme-agent-sdk'

const router = Router.create({
  model: ModelProvider,
  routes: RouteConfig[],
  fallback?: Agent,
})

await Router.run(router, input): Promise<RunResult>

import { MCPToolProvider } from 'assistme-agent-sdk/mcp'

const provider = await MCPToolProvider.connect({
  transport: 'stdio' | 'sse',
  command?: string,
  args?: string[],
  env?: Record<string, string>,
  url?: string, // For SSE transport
})

provider.tools(filter?: { include?: string[]; exclude?: string[] }): Tool[]
provider.disconnect(): Promise<void>

import { Sandbox } from 'assistme-agent-sdk'

const sandbox = Sandbox.create({
  type: 'container' | 'microvm' | 'wasm',
  image?: string,
  limits: {
    memory: string,
    cpu?: string,
    timeout: number,
    network: boolean | NetworkPolicy,
    filesystem?: FilesystemPolicy,
  },
  hermetic?: boolean,
  monitoring?: SandboxMonitoring,
})

await sandbox.run(code: string, options?: {
  language?: string,
  stdin?: string,
  env?: Record<string, string | SecretRef>,
}): Promise<SandboxResult>

import { TestRunner, MockModel } from 'assistme-agent-sdk/testing'

const mockModel = new MockModel(responses: MockResponse[])
const result = await TestRunner.run(agent, input)

import { EvalRunner, EvalDataset, EvalCriteria } from 'assistme-agent-sdk/eval'

const dataset = EvalDataset.fromJSON(entries)
const results = await EvalRunner.run(agent, dataset, options)
await EvalRunner.consistency(agent, config)
await EvalRunner.safety(agent, config)

interface Message {
  role: 'user' | 'assistant' | 'system'
  content: string | ContentBlock[]
}

type ContentBlock =
  | { type: 'text'; text: string }
  | { type: 'image'; source: ImageSource }
  | { type: 'tool_use'; id: string; name: string; input: unknown }
  | { type: 'tool_result'; tool_use_id: string; content: string }

type StreamEvent =
  | { type: 'run_start'; runId: string; agent: string }
  | { type: 'text_delta'; delta: string }
  | { type: 'text_done'; text: string }
  | { type: 'tool_call_start'; id: string; name: string }
  | { type: 'tool_call_args_delta'; id: string; delta: string }
  | { type: 'tool_call_done'; id: string; name: string; args: unknown }
  | { type: 'tool_result'; id: string; name: string; result: unknown }
  | { type: 'tool_approval_required'; id: string; name: string; args: unknown }
  | { type: 'guardrail_triggered'; guardrail: string; phase: 'input' | 'output'; allow: boolean; reason?: string }
  | { type: 'handoff'; from: string; to: string; reason?: string }
  | { type: 'agent_start'; agent: string }
  | { type: 'agent_end'; agent: string }
  | { type: 'memory_recall'; memories: MemoryEntry[] }
  | { type: 'memory_extract'; entries: MemoryEntry[] }
  | { type: 'turn_start'; turn: number }
  | { type: 'turn_end'; turn: number }
  | { type: 'run_end'; runId: string; status: RunStatus; usage: TokenUsage }
  | { type: 'error'; error: Error }

interface RunTrace {
  runId: string
  agent: string
  status: RunStatus
  startedAt: string
  completedAt: string
  durationMs: number
  turns: TraceTurn[]
  usage: TokenUsage
  guardrails: GuardrailTraceEntry[]
  handoffs: HandoffTraceEntry[]
  approvals: ApprovalTraceEntry[]
}