Agent SDK Documentation

# .env
KERNEL_ENGINE_URL=https://kernel.your-org.com
KERNEL_API_KEY=tk_live_xxxxxxxxxxxxxxxxxxxxx

# For development
KERNEL_ENGINE_URL=http://localhost:8080
KERNEL_API_KEY=tk_dev_xxxxxxxxxxxxxxxxxxxxx

interface SubmitProposalRequest {
  tenant_id: string        // Organization ID
  agent_id: string         // Your agent's unique ID
  handle_id: string        // Execution context/scope
  intent: ProposalIntent   // "execute" | "validate_only" | "dry_run" | "query"
  payload: Record<string, unknown>  // Action-specific data
  ordkey?: string          // Optional ordering key for sequencing
  idempotency_key?: string // Prevents duplicate execution
}

interface SubmitProposalResponse {
  proposal_id: string      // Unique proposal identifier
  status: string           // "pending" | "validated" | "rejected"
  request_hash: TupleHash  // Content-addressed hash of request
  created_at: string       // ISO timestamp
  errors: ValidationError[] // Any immediate validation errors
}

interface PolicySource {
  id: string
  name: string
  version: number
  
  // Allowed edge types in the lattice
  allowed_edges: AllowedEdge[]
  
  // Permitted rewrite rules
  allowed_rules: AllowedRule[]
  
  // Effect emission permissions
  allowed_effects: AllowedEffect[]
  
  // Execution bounds
  temperature: {
    min_steps?: number
    max_steps?: number
    gas_limit?: number
    timeout_ms?: number
  }
  
  // Trace configuration
  trace_config: {
    required?: boolean
    include_intermediate?: boolean
    hash_algorithm?: "sha256" | "blake3" | "poseidon"
  }
  
  // Sealing rules for finalization
  sealing_rules: SealingRule[]
}

interface AllowedEffect {
  kind: EffectKind           // "db_write" | "http_call" | "payment_send" | etc.
  max_per_epoch?: number     // Rate limit per epoch
  max_payload_bytes?: number // Size limit
  requires_approval?: boolean // Human-in-the-loop
}

interface Effect {
  id: string
  kind: EffectKind
  status: "pending" | "executing" | "completed" | "failed" | "cancelled"
  ordkey: string              // Ordering key for sequencing
  ordseq: number              // Sequence within ordkey
  idempotency_key: string     // Deduplication key
  request_hash: TupleHash     // Hash of the request tuple
  payload: Record<string, unknown>
  trace_id?: string           // Parent execution trace
  handle_id: string           // Execution context
  created_at: string
  executed_at?: string
}

interface Receipt {
  id: string
  effect_id: string
  receipt_hash: TupleHash     // Content-addressed receipt hash
  status: string
  response?: Record<string, unknown>
  error?: string
  before_root?: StateRoot     // State before effect
  after_root?: StateRoot      // State after effect  
  gateway_signature?: string  // Ed25519 signature from gateway
  created_at: string
}

interface Trace {
  id: string
  hash: TraceHash             // Deterministic trace hash
  before_root: StateRoot      // Initial state root
  after_root: StateRoot       // Final state root
  policy_hash: PolicyHash     // Policy used for validation
  gas_used: number            // Total gas consumed
  duration_ms: number         // Execution time
  step_count: number          // Number of rewrite steps
  status: "running" | "completed" | "failed" | "timeout" | "gas_exhausted"
  proposal_id?: string
  handle_id?: string
  created_at: string
}

interface TraceStep {
  id: string
  trace_id: string
  step_number: number
  rule_id: string             // Rewrite rule applied
  matched_at: string          // Pattern match location
  gas_used: number            // Gas for this step
  nodes_added: string[]       // New lattice nodes
  nodes_removed: string[]     // Deleted lattice nodes
  edges_added: string[]       // New lattice edges
  edges_removed: string[]     // Deleted lattice edges
  effects_emitted: string[]   // Effects produced
  intermediate_root?: StateRoot // State after this step
}

// Get a trace with all steps
const { trace, steps } = await kernel.getTrace({
  trace_id: result.trace_id,
  include_steps: true
})

console.log(`Trace ${trace.id}:`)
console.log(`  Status: ${trace.status}`)
console.log(`  Steps: ${trace.step_count}`)
console.log(`  Gas used: ${trace.gas_used}`)
console.log(`  Before root: ${trace.before_root}`)
console.log(`  After root: ${trace.after_root}`)

// Examine individual steps
for (const step of steps) {
  console.log(`  Step ${step.step_number}: ${step.rule_id}`)
  console.log(`    Nodes added: ${step.nodes_added.length}`)
  console.log(`    Effects: ${step.effects_emitted.length}`)
}

// Query a specific node by hash
const nodeResult = await kernel.queryLattice({
  tenant_id: "org_acme",
  query: { type: "node", hash: "sha256:abc123..." }
})

// Query neighborhood (radius-limited BFS)
const neighborhood = await kernel.queryLattice({
  tenant_id: "org_acme",
  query: {
    type: "neighborhood",
    center: "sha256:abc123...",
    radius: 2,
    labels: ["references", "created_by"]
  }
})

// Query edges by criteria
const edges = await kernel.queryLattice({
  tenant_id: "org_acme",
  query: {
    type: "edges",
    src: "sha256:abc123...",
    status: "committed"
  }
})

// Get current state root
const { state_root } = await kernel.queryLattice({
  tenant_id: "org_acme",
  query: { type: "state_root" }
})

// Get lattice statistics
const { stats } = await kernel.queryLattice({
  tenant_id: "org_acme",
  query: { type: "stats" }
})
console.log(`Nodes: ${stats.node_count}, Edges: ${stats.edge_count}`)

// Check if action requires approval
const validation = await kernel.validateProposal({
  proposal_id: proposal.proposal_id
})

const requiresApproval = validation.computed_effects.some(
  e => e.requires_approval
)

if (requiresApproval) {
  // Submit for governance approval
  const govProposal = await kernel.governance.createProposal({
    tenant_id: "org_acme",
    proposal_type: "execute_action",
    title: "Approve high-value refund",
    description: "Customer refund exceeding $1000 threshold",
    linked_proposal_id: proposal.proposal_id,
    threshold_id: "high_value_actions"
  })
  
  // Approvers vote
  await kernel.governance.vote({
    proposal_id: govProposal.id,
    voter_id: "admin_1",
    vote: "approve",
    comment: "Verified customer complaint"
  })
  
  // Check if threshold met
  const status = await kernel.governance.getProposalStatus(govProposal.id)
  if (status.approved) {
    // Now execute with governance approval
    await kernel.executeProposal({
      proposal_id: proposal.proposal_id,
      approved_by: govProposal.id
    })
  }
}

// Get current usage meters
const usage = await kernel.economics.getUsage({
  tenant_id: "org_acme",
  agent_id: "support-agent-1"
})

console.log("Usage this epoch:")
console.log(`  Compute: ${usage.compute_gas} gas`)
console.log(`  Storage: ${usage.storage_bytes} bytes`)
console.log(`  Bandwidth: ${usage.bandwidth_bytes} bytes`)
console.log(`  Effects: ${usage.effect_count}`)

// Check account balance
const balance = await kernel.economics.getBalance({
  tenant_id: "org_acme"
})

console.log(`Balance: ${balance.available} credits`)
console.log(`Reserved: ${balance.reserved} credits`)

import { KernelError } from "@trustkernels/sdk"

try {
  const result = await kernel.executeProposal({
    proposal_id: "...",
    approved_by: "system"
  })
} catch (error) {
  if (error instanceof KernelError) {
    switch (error.statusCode) {
      case 400:
        // Invalid request - check payload
        console.error("Invalid request:", error.body)
        break
      case 401:
        // Authentication failed - check API key
        console.error("Authentication failed")
        break
      case 403:
        // Policy violation - action not allowed
        console.error("Policy violation:", error.body)
        break
      case 404:
        // Resource not found
        console.error("Proposal not found")
        break
      case 409:
        // Conflict - maybe idempotency key collision
        console.error("Conflict:", error.body)
        break
      case 429:
        // Rate limited - back off
        console.error("Rate limited, retry later")
        break
      case 503:
        // Engine paused or unavailable
        console.error("Service unavailable")
        break
      default:
        console.error("Kernel error:", error.message)
    }
  } else {
    // Network or other error
    console.error("Unexpected error:", error)
  }
}