@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.