nosie-agent-core

NosieAgentCore

中文 · English ← you are here

An embeddable AI agent kernel. Drop it into an existing app and that app gains a tool-using, file-reading, memory-carrying assistant — with your UI, your provider endpoint, and your permission policy.

It is a library first. nosie the CLI exists so you can run the kernel standalone and copy its behaviour, but the primary product is the Agent object you construct in-process.

your app  ──in-process──▶  NosieAgentCore  ──HTTP──▶  any OpenAI-compatible endpoint
                              │
                              └──▶ tools · files · skills · memory · MCP

• Images and files are first-class inputs. attach() turns paths into content blocks (png/jpeg/gif/webp as base64, text as an inline resource or a path-only reference), and read_file returns a picture as a picture instead of refusing binary. A picture costs a flat visual estimate rather than its base64 length, and a model that takes no pixels gets a text placeholder plus an image_dropped warning rather than silence. Requests and responses are plain Chat Completions (/chat/completions, SSE streaming, tool_calls). Works against OpenAI, Azure OpenAI, DeepSeek, Qwen, Kimi, Ollama, vLLM, LM Studio — anything that speaks the format.
• Real agent loop. Multi-step tool use, parallel tool execution, steering mid-run, follow-up queues, stop conditions, automatic context compaction.
• Host-controlled safety. Every non-read-only action goes through a permission pipeline. No handler configured means deny, not allow. Path sandboxing is enforced separately from approval.
• Prompts that cannot be lost. injectedPrompts live outside the transcript and are spliced into the request after the host's hooks run — so compaction, trimming and transformContext cannot drop them. This is the one channel where a rule the host stated is guaranteed to be in front of the model every step.
• Failure stays visible. A stream that dies mid-answer is re-issued and the host is told to discard what it painted (text_reset) rather than seeing the answer twice. Bad skills, dead MCP servers and failed compactions surface as events, not silence.
• Guardrails for the whole tree. budget caps tokens, steps and wall clock across a run and every subagent it delegates to — one shared ledger, so delegating cannot escape the ceiling — with one tool-free wrap-up call left so a capped run still answers instead of returning nothing.
• Auditable after the fact. audit records one line per permission decision (auto-approvals included) with arguments stored as an order-independent digest; redact masks secrets at the persistence boundary while the live transcript keeps what the model actually sent.
• Standard agent facilities. Skills (agentskills.io), file-based memory, MCP client, persistent JSONL sessions, and subagents the model delegates self-contained subtasks to.
• Many conversations, several models. One sidecar holds any number of sessions running at the same time; a session's model id can be switched mid-conversation, and a host can bind a session to its own endpoint when you opt that in.
• Nothing is quietly ignored. createAgent() throws on a config key it does not read — naming the closest real one and what skipping it would cost — because permission.onRequestHandler (the real key is onRequest) used to start fine and then deny every non-read-only tool, sending the integrator to debug the permission engine instead of the typo. And agent.selfCheck() proves the claims rather than listing them: the image check does not read capabilities.imageInput, it runs the request builder and looks for the bytes. nosie doctor prints that report and exits 1 when it fails; nosie/self_check puts it on the protocol for non-JS hosts.
• Zero runtime dependencies. Optional peer dependency on @modelcontextprotocol/sdk only if you use MCP.
• Language-neutral embedding. A JSON-RPC / ACP-compatible sidecar protocol over stdio and HTTP+SSE lets Python, Go, Rust or JVM hosts drive the kernel.

Install

Not on npm yet — nosie-agent-core currently 404s on the registry, so install from source:

git clone https://github.com/baicaibucai1/nosie-agent-core.git
cd nosie-agent-core
npm install          # dev dependencies only; the runtime has none
npm run build        # tsup emits ESM + CJS + types

Requires Node.js 20 or newer. TypeScript types ship with the package. Once published this becomes npm install nosie-agent-core.

Five-minute quickstart

import { createAgent } from 'nosie-agent-core';

const agent = await createAgent({
  provider: {
    baseURL: 'https://api.openai.com/v1',   // or any compatible server
    apiKey: process.env.OPENAI_API_KEY!,
    model: 'gpt-4.1-mini',
  },
  workspaceRoot: process.cwd(),
  permission: {
    mode: 'default',
    async onRequest(request) {
      const ok = await myUi.askUser(request.title);   // you decide
      return ok ? { optionId: 'allow_once' } : { optionId: 'reject_once' };
    },
  },
});

// run() returns a handle: iterate it for events, or await .result for the end.
const result = await agent.run('Summarise what this project does.').result;
console.log(result.text);
await agent.dispose();

Stream it instead of waiting:

for await (const event of agent.run('Refactor the parser.')) {
  if (event.type === 'text_delta') process.stdout.write(event.delta);
  if (event.type === 'tool_call_ready') console.log('\n→', event.title);
}

That is the whole integration surface for a basic app: one factory, one run, one permission callback, one dispose.

Use it standalone

Until the package is published, run the CLI from a clone (the nosie bin maps to dist/cli/main.js after npm run build):

npx tsx src/cli/main.ts                       # interactive REPL in the current directory
npx tsx src/cli/main.ts -p "explain this repo" # one shot
npx tsx src/cli/main.ts doctor                # resolved config + a self-check; exits 1 on a FAIL
npx tsx src/cli/main.ts serve --http --port 8787  # sidecar for non-JS hosts

See docs/cli.md.

Embed it in a non-Java host

Spawn the kernel and speak JSON-RPC to it — the same protocol the CLI uses:

npm run build
node examples/python-host/mock_sidecar.mjs --stdio   # keyless stand-in for the kernel
python examples/python-host/stdio_client.py

examples/python-host/ has stdlib-only Python clients for both transports (stdio_client.py, http_client.py); the wire format, ACP mapping and every method are specified in docs/protocol.md.

Documentation

Read this	To
embedding.md	Integrate the kernel into a TypeScript/JavaScript app
events.md	Render a UI: the full event catalogue and ordering rules
tools.md	Built-in tools, custom tools, argument validation, concurrency
permissions.md	Modes, rule syntax, approval flow, deny-by-default
security.md	Trust boundaries, secret handling, the audit trail
skills.md	Author and load SKILL.md instruction packages
subagents.md	Let the model delegate subtasks to narrower child agents
memory.md	File memory stores and AGENTS.md instruction chains
mcp.md	Connect MCP servers as tools
protocol.md	Drive the kernel from another language (JSON-RPC / ACP)
cli.md	Every flag, config file and environment variable
DEVELOPMENT.md	Internal architecture, design decisions, testing
MANUAL.zh-CN.md	中文产品手册：能力地图、特性、边界与待决事项
INTEGRATION.zh-CN.md	中文接入指南：分步决策 + 会被编译的代码示例
REFERENCES.md	Open-source kernels this design was measured against

Five runnable programs — in-process host, custom tools, event-driven UI, agent server, Python clients — are in examples/. They run with no API key: with OPENAI_API_KEY unset they use the bundled scripted provider.

Want to see the kernel behave before reading any of it? npm run demo starts a scripted offline model, the HTTP sidecar and a browser console on http://127.0.0.1:8790/ — a page you can click through tool calls, approvals, cancellation, steering, concurrent conversations, a delegated subagent run and switching models mid-chat. It is only a sidecar client, so every frame it renders is one the kernel really sent (demo/README.md).

examples/ and demo/ live in the source repository, not in the npm tarball, because the TypeScript ones import ../src/index.js and run straight from tsx with no build step. Installed apps import the package instead — nosie-agent-core, nosie-agent-core/sidecar, nosie-agent-core/mcp — and the tarball ships dist/, docs/, README.md, README.zh-CN.md, LICENSE and CHANGELOG.md.

Repository layout

src/types      L1  data model: messages, events, tools, config, errors
src/provider   L2  OpenAI-compatible streaming client, retry, SSE, mock
src/tools      L2  built-in tools, registry, path sandbox
src/skills     L2  agentskills.io loader
src/memory     L2  file memory + instruction chain
src/session    L2  JSONL transcript store, context assembly
src/mcp        L2  MCP client bridge
src/runtime    L3  run loop, Agent facade, permissions, compaction, hooks
src/sidecar    L4  JSON-RPC framing, ACP mapping, stdio + HTTP transports
src/cli        L4  standalone CLI and REPL

Dependencies flow downward only. src/runtime never imports from src/cli or src/sidecar, so embedding the library never drags in terminal code.

Status

Version 0.2.0 — tagged in the changelog, not yet on the registry. The API is usable but not frozen; breaking changes come with a changelog entry before 1.0.0. 0.2.0 is the first version anyone will be able to npm install, and it carries a breaking sidecar-HTTP change (see CHANGELOG.md).

Not in v1 by design, and documented as out of scope: sub-agents / agent hand-off, ACP filesystem and terminal delegation, vector or embedding-based memory retrieval, A2A, MCP resources and prompts, and exact tokenisation (counts are estimated and calibrated from provider usage reports).

Licence

MIT.