ShenQingchuan/locus-agent-sdk

@univedge/locus-agent-sdk

The shared SDK package for Locus Agent providing runtime contracts, hook event model, plugin system, SSE protocol, context management, and prompt building utilities.

Preferences

• Always import types directly from @univedge/locus-agent-sdk — never re-export from intermediate modules
• SDK defines only interfaces and pure logic; no heavy dependencies (AI SDK, database drivers, etc.)
• Use generic type parameters (TModel, TMessage) to stay framework-agnostic
• Hook handlers must return a HookDecision — use { type: 'noop' } when no action needed

Module Map

| Module | Purpose | Key Exports | |--------|---------|-------------| | runtime/ | Agent loop, tool execution, delegation, policy | AgentLoopOptions, AgentLoopCallbacks, ToolExecutor, StreamingToolExecutor, DelegateArgs, classifyTool | | hooks/ | Lifecycle events & hook bus | HookEventName, HookCategory, HOOK_CATEGORIES, HookBus, HookHandler, HookDecision, payload types | | plugins/ | Plugin manifest, permissions, scope | PluginManifest, PluginPermissions, PermissionScope, PluginScope, hasPermission | | context/ | Auto-compaction & tool result caching | shouldCompact, compactToolResults, CompactionStrategy, ResultCacheStorage | | prompt/ | System prompt assembly | PromptBuilder, PromptSection, createPromptBuilder | | sse/ | SSE parsing, dispatching, streaming | parseSSELine, serializeSSEEvent, consumeSSEStream, SSEEventHandlers, dispatchSSEEvent | | types/ | Shared base types | SSEEvent, ToolCall, ToolResult, CoreMessage, RiskLevel, DelegateDelta |

Runtime Contracts

Agent Loop

import type { AgentLoopCallbacks, AgentLoopOptions, AgentLoopResult, PendingToolCall, TokenUsage } from '@univedge/locus-agent-sdk'

• AgentLoopOptions<TModel, TMessage> — full config for an agent run (model, messages, callbacks, approval mode, tool allowlist)
• AgentLoopCallbacks — streaming callbacks: onTextDelta, onToolCallStart, onToolCallResult, onReasoningDelta, onToolPendingApproval, onToolOutputDelta, onDelegateDelta, onFinish
• AgentLoopResult<TMessage> — run result: text, finishReason, usage, iterations, messages

Tool Execution

import type { StreamingToolExecutor, ToolExecutionContext, ToolExecutor, ToolOutputCallbacks } from '@univedge/locus-agent-sdk'

• ToolExecutor<TArgs, TResult> — simple async executor
• StreamingToolExecutor<TArgs, TResult> — with ToolOutputCallbacks for stdout/stderr streaming
• ToolExecutionContext — conversationId, projectKey, workspaceRoot

Tool Policy

import type { ToolCategory, ToolPolicyConfig } from '@univedge/locus-agent-sdk'
import { classifyTool } from '@univedge/locus-agent-sdk'

const cat = classifyTool('bash', policy) // 'interactive' | 'trusted' | 'serial' | 'normal'

Delegation

import type { DelegateArgs, DelegateCallbacks, DelegateResult, SubAgentConfig } from '@univedge/locus-agent-sdk'

Hook Event Model

16 Lifecycle Events

| Domain | Events | Category | |--------|--------|----------| | session | session:start, session:end | observe | | message | message:user_received | observe | | context | context:resolve | enrich | | prompt | prompt:assemble | enrich | | model | model:before_call (guard), model:after_call (enrich) | mixed | | tool | tool:before_execute (guard), tool:approval_required (observe), tool:after_execute (enrich) | mixed | | delegate | delegate:before_run (guard), delegate:after_run (enrich) | mixed | | artifact | artifact:plan_written, artifact:file_change_detected | observe | | run | run:finish, run:error | observe |

HookBus Interface

import type { HookBus, HookDecision, HookHandler } from '@univedge/locus-agent-sdk'

bus.on('tool:before_execute', async (invocation) => {
  // invocation.payload is typed per event
  return { type: 'noop' }
})

HookDecision Types

• { type: 'noop' } — no action
• { type: 'append_context', items: ContextItem[] } — inject extra context
• { type: 'patch_prompt', patches: PromptPatch[] } — modify system prompt sections
• { type: 'suggest', suggestions: SuggestionItem[] } — provide suggestions
• { type: 'require_confirmation', reason: string } — pause for user approval
• { type: 'block', reason: string, code?: string } — block the operation
• { type: 'emit_artifact', artifact: PluginArtifact } — output a plugin artifact

Plugin System

Manifest

import type { PluginManifest } from '@univedge/locus-agent-sdk'

const manifest: PluginManifest = {
  id: 'com.example.git-guardian',
  name: 'Git Guardian',
  version: '1.0.0',
  apiVersion: '1',
  entry: { runtime: './index.js' },
  hooks: [
    { event: 'tool:before_execute', handler: 'onToolBeforeExecute' },
  ],
  permissions: { workspace: ['read'], tools: ['bash'] },
}

Permissions & Scope

import type { PermissionScope, PluginScope } from '@univedge/locus-agent-sdk'
import { hasPermission, PLUGIN_SCOPE_ORDER } from '@univedge/locus-agent-sdk'

// Scopes: 'global' > 'workspace' > 'project' > 'conversation'
// Permission strings: 'workspace.read', 'tools.invoke:bash', 'network.domain:api.example.com', etc.

Context Management

Auto-Compaction

import { COMPACTION_SYSTEM_PROMPT, DEFAULT_COMPACTION_THRESHOLD, shouldCompact } from '@univedge/locus-agent-sdk'

if (shouldCompact(inputTokens, contextWindow)) {
  // trigger compaction via MessageSummarizer
}

Tool Result Cache

import type { ResultCacheStorage, ToolResultCacheOptions } from '@univedge/locus-agent-sdk'
import { compactToolResults } from '@univedge/locus-agent-sdk'

// Implement ResultCacheStorage for your backend (fs, sqlite, etc.)
const entries = compactToolResults(messages, { storage, hotTailCount: 5, minSizeToCache: 500 })

Prompt Builder

import { createPromptBuilder } from '@univedge/locus-agent-sdk'

const prompt = createPromptBuilder()
  .addSection({ id: 'role', content: 'You are a coding assistant.', priority: 0 })
  .addSection({ id: 'rules', content: 'Follow best practices.', priority: 10 })
  .build()

Plugins can patch sections via patchSection(id, { sectionId, action: 'append' | 'prepend' | 'replace' | 'remove', content }).

SSE Protocol

Server Side

import { createSSEEventPayload, serializeSSEEvent } from '@univedge/locus-agent-sdk'

const line = serializeSSEEvent(createSSEEventPayload('text-delta', { textDelta: 'Hello' }))
// => "data: {\"type\":\"text-delta\",\"textDelta\":\"Hello\"}\n\n"

Client Side

import type { SSEEventHandlers } from '@univedge/locus-agent-sdk'
import { consumeSSEStream } from '@univedge/locus-agent-sdk'

await consumeSSEStream(response.body.getReader(), {
  onTextDelta: d => append(d),
  onDone: (id, usage) => finish(id),
})

Anti-Patterns to Avoid

1. No re-export chains — import directly from @univedge/locus-agent-sdk, never from an intermediate barrel that re-exports SDK types
2. No heavy deps in SDK — SDK must not import ai (Vercel AI SDK), drizzle-orm, or any runtime-specific library
3. No concrete implementations for IO — use interfaces like ResultCacheStorage, MessageSummarizer; let consumers inject implementations