ai-agent

Enterprise Part of the commercial Kumiko Enterprise offering — not in the open framework.

In-app tool-loop agent. ai-agent:stream:turn resolves a user prompt against the tenant’s LLM provider and the role-filtered tool catalog derived from the registry (search/find/get/list for every mounted entity, plus navigate/open_form/ask_user), streaming persisted ai-agent-turn rows back to the caller as they’re produced. A tool call needs human approval whenever its handler is a write, or a query whose agent.risk is above “low” (e.g. one that spends provider budget or reads sensitive data) — in approval mode such a call is never dispatched directly, it turns into a proposal turn that ai-agent:write:approve / :reject resolve explicitly. read-only mode never exposes an approval-required tool to the model at all. edit mode (opt-in via editEnabled) auto-dispatches an approval-required call whose handler has an always permission rule and isn’t high-risk; see permissions.ts. Requires ai-foundation (LLM provider), prompt-store (system prompt and model settings under the key ai-agent:system), tenant, and cap-counter (monthly token budget for the agent’s own provider calls — a query handler dispatched as a tool call, e.g. ai-pipeline’s dry-run, spends its own provider budget outside this cap). tokenMeterCapName additionally books every provider response’s full token count (cache tokens included) to a usage-only cap-counter meter that is never enforced. The provider is resolved through prompt-store/ai-foundation, so turns on the platform key also count against ai-foundation’s platform token budget, which the tenant shares with all other AI features.

Build it yourself

This Enterprise implementation is optional. If you need a narrower or domain-specific version, you can build an app-owned feature, handler, or job with Kumiko’s public extension points.

Use this package when you want the maintained implementation, its existing contracts, and the surrounding operational behavior. A custom implementation is not drop-in compatible automatically: your app owns its authorization, validation, integrations, tests, security review, and production operations.

Start with Features and composition and Custom write handlers.

How it fits

What this feature needs to run (Requires, top) and the write commands this feature provides (Provides, bottom).

flowchart TB
  n_ai_agent["ai-agent"]
  subgraph how_reqs["Requires"]
    n_ai_foundation["ai-foundation"]
    n_prompt_store["prompt-store"]
    n_tenant["tenant"]
    n_cap_counter["cap-counter"]
  end
  subgraph how_provides["Provides"]
    n_cmd_ai_agent_write_approve(["approve"])
    n_cmd_ai_agent_write_approve_always(["approve-always"])
    n_cmd_ai_agent_write_live_transcription_book(["live-transcription-book"])
    n_cmd_ai_agent_write_live_transcription_reserve(["live-transcription-reserve"])
    n_cmd_ai_agent_write_live_transcription_start(["live-transcription-start"])
    n_cmd_ai_agent_write_reject(["reject"])
    n_cmd_more(["+5 more"])
  end
  n_ai_foundation --> n_ai_agent
  n_prompt_store --> n_ai_agent
  n_tenant --> n_ai_agent
  n_cap_counter --> n_ai_agent
  n_ai_agent --> n_cmd_ai_agent_write_approve
  n_ai_agent --> n_cmd_ai_agent_write_approve_always
  n_ai_agent --> n_cmd_ai_agent_write_live_transcription_book
  n_ai_agent --> n_cmd_ai_agent_write_live_transcription_reserve
  n_ai_agent --> n_cmd_ai_agent_write_live_transcription_start
  n_ai_agent --> n_cmd_ai_agent_write_reject
  n_ai_agent --> n_cmd_more

Provides — write commands this feature registers (dispatch them through the command bus):

• ai-agent:write:approve
• ai-agent:write:approve-always
• ai-agent:write:live-transcription-book
• ai-agent:write:live-transcription-reserve
• ai-agent:write:live-transcription-start
• ai-agent:write:reject
• ai-agent:write:rename-conversation
• ai-agent:write:reopen
• ai-agent:write:set-permission
• ai-agent:write:speak
• ai-agent:write:transcribe

Dependencies

• Requires: ai-foundation, prompt-store, tenant, cap-counter
• Activation: always on (not toggleable)

Configuration

Per-tenant config keys, set via the tenant-admin UI or a seed. 🔒 = encrypted at rest.

Key	Type	Default	Scope	Who can write	Who can read
hands-free	boolean	false	user	User, TenantAdmin, SystemAdmin	all
mode	select (read-only | approval | edit)	approval	tenant	TenantAdmin, SystemAdmin	all
monthly-token-limit	number (1–100000000)	1000000	tenant	TenantAdmin, SystemAdmin	all
send-after-dictation	boolean	false	user	User, TenantAdmin, SystemAdmin	all

Extensions & cross-feature APIs

• Registers extension: promptTemplate → ai-agent:system