@bosun-sh/sounder

@bosun-sh/sounder

Local-first library and MCP server for deterministic task and model estimation, scoped feedback learning, inventory-driven model recommendations, and subagent recommendations.

Note: sounder is a library + MCP server — it has no CLI bin entrypoint by design. Consume it as a library or mount it as an MCP server in your agent host.

Installation

bun add @bosun-sh/sounder

Quickstart

Library usage

import { createSounderApp, sounderPlugin, sounderToolIds } from "@bosun-sh/sounder";

// Create a fully-wired Sounder app (SQLite-backed, local-first)
const app = await createSounderApp();

// Estimate a task by Fibonacci bucket
const result = await app.run("sounder.estimate.task", {
  description: "Implement OAuth login flow",
});

// Record feedback after a task completes
await app.run("sounder.feedback.task", {
  toolId: "sounder.estimate.task",
  outcome: "completed",
  actual: 5,
});

// Recommend a model for a given task
const recommendation = await app.run("sounder.recommend.model", {
  description: "Summarize a long legal document",
  tier: "mid",
});

MCP server usage

Mount sounder as an MCP tool server in your agent host:

import { createSounderMcpApp } from "@bosun-sh/sounder/mcp";

const mcpApp = await createSounderMcpApp();
// Pass mcpApp to your MCP host / stdio transport

Ohtools default app

import sounder from "@bosun-sh/sounder/ohtools";

// Pre-built default app instance — zero config required
const result = await sounder.run("sounder.inventory.list", {});

Features

Tools

Tool ID	Description
sounder.estimate.task	Estimate task effort using Fibonacci bucketing and learned weights
sounder.estimate.model	Estimate token/cost for a model invocation
sounder.feedback.task	Record task outcome to improve future estimates
sounder.feedback.model	Record model outcome feedback
sounder.recommend.model	Recommend the best model for a task given tier and inventory
sounder.recommend.subagent	Recommend subagents for a composite task
sounder.history.list	Query estimation history
sounder.inventory.list	List available models in inventory
sounder.inventory.upsert	Add or update a model in the inventory

Exports

Import path	What it provides
@bosun-sh/sounder	createSounderApp, createSounderCliApp, createSounderMcpApp, sounderPlugin, sounderToolIds, schemas, types
@bosun-sh/sounder/ohtools	Default pre-built app instance
@bosun-sh/sounder/mcp	createSounderMcpApp for MCP server mounting
@bosun-sh/sounder/cli	createSounderCliApp for CLI adapter

Plugin integration

Use the plugin directly with your own Ohtools host:

import { sounderPlugin, sounderToolIds } from "@bosun-sh/sounder";

// Register the sounder plugin into your own ohtools host
myOhtoolsHost.register(sounderPlugin);

Development

git clone https://github.com/bosun-sh/sounder.git
cd sounder
bun install

bun test               # full test suite
bun run ci:lint        # lint + typecheck
bun run ci:build       # build + pack dry-run
bun run ci:premerge    # full gate — must be green before PR

Contributing

See CONTRIBUTING.md for local setup, commit conventions, and pull request process.

License

Apache-2.0 — see LICENSE.