brain_kernel 0.2.2

brain_kernel: ^0.2.2 copied to clipboard

Added #

• AccountKbRecordStore and KbAccountRecords — a bundle's kb records in account storage (app/<appId>, platform spec 20 §2) with this device's copy underneath. Writes are conditioned on the account version last seen; while the account is unreachable they wait on the device and go up in order when it answers, and one whose base moved meanwhile is kept for conflicts() instead of being forced. A refusal from the account (KB_QUOTA_EXCEEDED, KB_VALUE_TOO_LARGE, a key or scope it does not accept) reaches the bundle rather than waiting, and one met in the queue does not hold back the writes behind it. Keys are stored as kb/<key> with every UTF-8 byte outside A-Z a-z 0-9 . _ / - written as : and two hex digits (platform spec 20 §2.1.2) — accountKeyOf / kbKeyOf — and a key whose stored form is longer than accountKeyLimit is refused with KB_INVALID_KEY before it is read, written or queued. clearDeviceCopy drops this device's copy and queue, never the account's records.
• BundleKbStore — a bundle's host.kb state as one implementation every host forwards to. get · list(prefix) (ascending, string prefix) · put · delete · conflicts · query. Each key is a versioned record: a write is made on the version the store last saw, and when the record moved since, nothing is written and {ok: false, conflict: {value}} returns the current value for the bundle to merge; force overwrites deliberately. Keys are refused (KB_INVALID_KEY) when empty, starting with /, containing \ or NUL, or holding an empty, . or .. segment; values JSON cannot carry are refused (KB_INVALID_VALUE); query without a knowledge engine is refused (KB_QUERY_UNAVAILABLE). KbError.unavailable (KB_UNAVAILABLE) names a store that will not take the app's state. State is keyed by app identity (listing:<id> / bundle:<manifest.id>).
• KbRecordStore and KvKbRecordStore — records in the kernel KvStoragePort under app/<appId>/kb/<key>, each segment percent-encoded so any app id or key is a valid file name on every platform. A delete keeps a tombstone so versions keep counting up.
• importDomainStorageNamespace — moves a host's former DomainStorage state into kb once, never overwriting and never deleting the source.

Fixed #

• KvStoragePortAdapter refuses a key with a . or .. segment. A key is a path under the root, so a/../../x wrote outside it and a/x/../b gave one file a second name.
• KvStoragePortAdapter.keys(prefix) walks only the directory the prefix's last / names instead of the whole store. The keys returned are the same.

Deprecated #

• DomainStorage and JsonFileDomainStorage — a second store beside the kernel's, with no versions. Use BundleKbStore.

Changed #

• Internal dependencies raised to the latest published: mcp_bundle ^0.4.10, mcp_server ^2.2.3, flowbrain_core ^0.1.8.

Added #

• The kernel runs where there is no filesystem. Storage is behind two ports: CanonicalStoragePort for the canonical bundle and SidecarStore for prefs, undo, history and chat. Neither port names a platform library, so a host can implement one without being handed dart:io.
• OpfsSidecarStore — a browser store over the origin-private file system, exported from brain_kernel_web.dart. It is not on the main barrel: dart:js_interop has no implementation off the web compilers, so a VM build that reached it would not compile. forAccount(accountKey) is the only constructor — OPFS is keyed by origin, not by person, so two people sharing a browser would otherwise share their records.

Changed #

• The sidecars take an optional store (Prefs.load(path, store: …), ChatLog.attach(path, store: …), and the same for HistoryLog / UndoLog). Omitting it keeps the previous behaviour — the filesystem, where there is one. Where there is none, the call refuses with a StateError naming the missing decision rather than failing later inside a read. Canonical.openAt behaves the same way with its storage.
• ManifestOnlyCanonicalStorage moved to its own library so that naming the port does not import the filesystem implementation. It is still exported from the barrel.
• Floor: mcp_client ^2.2.1. New dependency web ^1.1.0, reached only through the web branch of a conditional import.

Fixed #

• McpClientKernelHost.connect is bounded (15 s default, options.connectTimeoutMs to change it) and reports a timeout as an error. Building a transport does not touch the endpoint, so an unreachable target first shows up in the handshake, and a caller that never gets an answer cannot report one.
• The barrel exports SidecarStore and defaultSidecarStore(). Every sidecar constructor requires a store, so without them the sidecars could not be called from outside this package at all.

Changed #

• Internal dependency floors moved to the current releases: mcp_client ^2.1.0, mcp_server ^2.1.1. The server floor matters beyond hygiene — 2.1.1 fixes in-flight requests being keyed by the bare JSON-RPC id, which let two sessions using the same id (the first id a client hands out is 2) overwrite each other's pending response. Leaving the floor at ^2.0.0 would resolve against a release that still loses responses under concurrent sessions.

Added #

• SharedResourceSubscriptions — reference-counted resources/subscribe over a client several consumers share. A device subscription belongs to the LINK: the server knows only "subscribed" or not. Once one connection per device is shared, a device's own screen and a composed tile naming the same device land on one subscription, and the first to release it stopped the other's stream — a tile that streamed until the device's own screen was visited and closed, then froze and moved one step per manual Subscribe. The wire call now happens on 0 → 1 and on the return to 0; a failed subscribe leaves no count behind.
• ExtensionTransportConnect.adoptClient({id, client}) — register a client the HOST already holds under an id, instead of dialling the device a second time. One device, one connection: many embedded boards serve a single peer, so a host that opened a device for its own screens and then named it as a composition origin got the second dial refused, and the user saw a device that "sometimes will not open". Even where a second link is allowed it splits subscriptions and health tracking across two links to the same device. An adopted connection does NOT own the client — closing it deregisters only, because ending a device connection is the user's explicit action, not a side effect of leaving a screen.
• mcp.subscribe_resource / mcp.unsubscribe_resource, and the KernelClientConnection.subscribeResource / unsubscribeResource / resourceUpdates they drive. The client surface could read a resource once but not track it, so a UI showing a live device value had no way to get one — it rendered the reading's label and never a number, which looks like a layout bug rather than a missing capability. First consumer: MCP UI DSL v1.4 composition, where one screen watches several devices at once.
• resourceUpdates is a broadcast stream. Several views may watch the same device, and a single-subscription stream would hand updates to whichever listened first and leave the rest empty.

Breaking #

• KernelClientConnection gains three abstract members. Implementors outside this package must add them; the reference implementation and the in-repo fakes are updated. Additive for callers.

Fixed #

• McpClientKernelHost streamableHttp/sse connect now sends options.accessToken as Authorization: Bearer (+ options.headers passthrough) — the token was dropped, failing authenticated service connects.

Added #

• ExtensionTransportConnect capability interface + connectExtension helper (package:brain_kernel/mcp_host.dart). Codifies the extension-transport injection seam standard. The seam connectWith({ id, transport }) — how a host opens an outbound MCP connection over a transport it built itself (serial / usb / ble / tcp / ws via mcp_bridge, or the hub relay ws via gateway_node's HubConsumerTransport) — previously lived only on the concrete McpClientKernelHost. The abstract KernelClientHost (the type KernelApp.clientHost exposes) surfaces only connect({ transport: KernelTransportKind }) for the kernel-buildable stdio / Streamable HTTP / SSE transports, so a host had to hold a concrete client-host reference to reach the seam. McpClientKernelHost now also implements ExtensionTransportConnect, and hosts reach the seam off the abstract client host via the canonical helper connectExtension(clientHost, { id, transport }) — it probes ExtensionTransportConnect, does the explicit cast (the interface is unrelated to KernelClientHost?, so is does not promote the variable — a footgun sealed in one place), injects, or throws a StateError. Both exported from the mcp_host.dart sub-barrel (they reference mcp_client's ClientTransport, so they stay out of the library-agnostic main barrel). KernelClientHost itself is unchanged (cascade 0). Test: client_tools_test.dart (probe off the abstract type; non-capable / null host throws). The host-facing surface (the mcp.connect_extension tool) lives in the recipes/extension_transport/ recipe, not the kernel (it carries an mcp_bridge FFI dependency). 227 PASS.

Backward compatibility #

• Fully additive. KernelClientHost is unchanged — existing implementers are untouched (no new abstract member to satisfy). The new capability is a separate interface a client host opts into. Floors unchanged.

Added #

• bk.agent.update standard tool (48 tools). In-place mutation of a persistent agent — agentId plus any of displayName / role / model / systemPrompt / tags. Closes the CRUD asymmetry in the bk.agent.* surface (create/delete existed, update did not), so changing an agent's orchestration role or model through the kernel tool surface no longer requires delete→recreate — which destroys the individual's owned axis forks and history, contradicting the persistent-roster principle. An unknown role value is rejected (not silently defaulted). Requires flowbrain_core ^0.1.7 (the role-accepting update seam) — floor bumped. Test: standard_tools_test.dart (in-place promote persists · untouched fields kept · unknown role rejected). 223 PASS.
• bk.philosophy.put / bk.philosophy.activate enforce a provenance lifecycle. An ethos payload may now carry an optional provenance block — payload['provenance'] = { 'kind': 'anchor'|'derived'|'workaround', 'serves': <principle id>, 'validWhile': <condition> }. A derived or workaround ethos is a transient judgment, not an original principle: it must declare the principle it serves, and it is forced inactive on put — it becomes the active principle only through an explicit activate (the confirm step), mirroring the fact candidate→confirm lifecycle. This keeps a derived judgment from silently being stored or activated as if it were a defining principle. Rides the existing EthosStorePort contract (payload preserved as-is) — no core type change in mcp_bundle. Tests: philosophy_authoring_test.dart (anchor unconstrained · derived-without-serves rejected · derived forced inactive + provenance round-trip · workaround confirmed via activate). 222 PASS.

Backward compatibility #

• Fully additive. kind defaults to anchor when absent, so pre-existing ethos records and the stock seed (which carry no provenance) are unconstrained and behave exactly as before. Floors unchanged.

Fixed #

• KvStoragePortAdapter.keys(prefix:) violated the string-prefix contract. It treated prefix as a directory path (<rootDir>/<prefix>/), so flat colon-namespaced keys (e.g. philosophy.ethos:<id>, stored as a single <key>.json file) were never listed: keys(prefix: 'philosophy.ethos:') returned [] even though get/set worked and keys() (no prefix) listed them. This surfaced as bk.philosophy.list returning an empty array while put/get succeeded. The method now walks the full store, reconstructs each key, and filters by key.startsWith(prefix) — matching the in-memory reference KvStoragePort. Hierarchical slash-namespaced prefixes (e.g. ws/A/) still match (keys use / separators) and partial-segment prefixes now match correctly too. Regression tests added (kv_storage_port_adapter_test.dart). 218 PASS.

Added #

• BundleActivation optional callTool closure — an alternative to a full KernelServerHost boot for wiring flow / behavior tool-action dispatch. A host whose endpoint is a registry (e.g. a BuiltinToolRegistry that exposes callTool without ever surfacing a raw KernelServerHost) can now inject just the dispatch closure: BundleActivation(system: ..., bundleId: ..., callTool: server.callTool). registerBehavior / registerFlow route tool steps through callTool ?? boot?.callTool. Mirrors the skill-executor callTool binding pattern already used across hosts. Tests: bundle_activation_behavior_test.dart (closure dispatch with boot == null · unwired-throws). 214 PASS.

Fixed #

• Registry-host topologies could not dispatch tool-action behavior / flow steps. When a host endpoint is a BuiltinToolRegistry (not a raw KernelServerHost), boot is necessarily null and there was no other way to supply dispatch, so every kind: tool behavior / flow step threw tool dispatch not wired (<ref>) at run time (the live-registered philosophy-gate path was latently affected too). The callTool seam closes that gap; the same diagnostic now fires only when neither callTool nor boot is provided.

Backward compatibility #

• Fully additive. The boot path and the tool dispatch not wired diagnostic are unchanged. BundleActivation callers that don't pass callTool see no behavior change.

Added #

• Orchestration tools — bk.agent.route + bk.agent.review standard tools (agent_tools: 11 → 13) — expose the AgentFacade's manager-routing + reviewer-verdict as MCP tools so workflows / agents can drive rule-based agent→agent handoff. route{managerId, request, candidateAgentIds?} → {targetAgentId, confidence, reason}; review{reviewerId, targetAgentId, content} → {verdict, severity, comments}. standardTools map: 45 → 47.
• Destructive-action gate — HostToolRegistry: registerExposed(destructive: true) + optional confirmDestructive host callback (ctor). Destructive tools (git push / mail / settlement / external publish) are gated through the callback before running — blocked when the human declines or no callback is wired (deny-by-default). destructive defaults false → existing tools unaffected. The confirm UI is host-supplied (core has no UI). 209 PASS.

Fixed #

• bk.philosophy.put accepts a raw Ethos and never silently drops the body. Previously put called EthosRecord.fromJson(input) directly, so an author / LLM passing a raw Ethos (no payload envelope key) stored payload: {} — the body was lost and every later getEthos / intervene / checkProhibitions operated on an empty ethos (or crashed in Ethos.fromJson). put now detects the shape: an envelope (payload present) is stored as before; a raw Ethos is wrapped into an EthosRecord with payload: <ethos>, id/name/version derived from the ethos (version from metadata.version). The body is validated via Ethos.fromJson before storage, returning a clear invalid ethos: <field-named message> (mcp_bundle 0.4.4) instead of storing garbage. Integration test: test/system/philosophy_authoring_test.dart (raw round-trip preserves body · envelope back-compat · malformed → clear error) over a real KvEthosStoreAdapter. 212 PASS.

Changed (dependency floor) #

• flowbrain_core ^0.1.4 → ^0.1.5 — track the latest published cascade release (flowbrain_core 0.1.5 wires the orchestration cascade). The kernel's route/review tools wrap the existing AgentFacade.route/review (present since 0.1.x), so this is an internal-latest constraint bump, not a symbol requirement.
• mcp_bundle ^0.4.1 → ^0.4.4 — the bk.philosophy.put fix above relies on the Ethos graph fromJson throwing field-named FormatExceptions (mcp_bundle 0.4.4) for the clear-error guarantee; floored to guarantee it.

Backward compatibility #

• Fully additive. No existing HostToolRegistry, BundleActivation, standardTools, or host-abstract surface changed. Tools registered without destructive: true and hosts that don't pass confirmDestructive see no behavior change.

Added #

• McpClientKernelHost.connectWith({id, transport}) — new public method on the reference KernelClientHost implementation. Accepts a host-supplied mcp_client.ClientTransport (e.g. TcpClientTransport or WebSocketClientTransport from mcp_bridge) and opens a KernelClientConnection over it. The kernel itself carries no FFI or platform dependency for the transport — the calling host owns those by design (injection seam). The abstract KernelClientHost is unchanged.
• clientTools function exported from the main barrel (lib/brain_kernel.dart). Returns the bk.mcp.* in-process tool map so hosts (e.g. appplayer_core) can register it alongside standardTools without reaching into src/.

Backward compatibility #

• Fully additive. No existing KernelApp, BundleActivation, standardTools, or host-abstract surface changed. Hosts that do not use extension transports see no behavior change.

Added #

• bk.philosophy.check standard tool — wraps PhilosophyFacade.checkProhibitions, evaluating a proposed action / output against active ethos and returning {hasHardViolation, violations}. The read-side of bk.philosophy.* (the existing put/get/activate go to the ethos store); lets a behavior step gate on hasHardViolation.
• BundleActivation.registerBehavior(BehaviorDefinition) — maps a bundle's behavior.definitions[] entry to an OpsRuntime.behaviorRegistry factory. Called automatically inside the activate loop when bundle.behavior is present; result carries result.behaviors count and registeredBehaviors list. ownsBehavior(id) predicate and teardown unregistration included. The action dispatcher surfaces a step's tool/skill output into run state — a tool's JSON result (or a skill's Map result) is merged so a later step's when guard can read its keys (e.g. gate on hasHardViolation from bk.philosophy.check).
• bk.behavior.run, bk.behavior.resume, and bk.behavior.list standard tools registered in ops_tools.dart, under the bk.behavior.* namespace alongside bk.workflow.* / bk.pipeline.* / bk.runbook.*. Execution routes through the ops facade (app.system.ops.runBehavior / resumeBehavior / listBehaviors, added in mcp_knowledge 0.2.4) — the same layer the workflow/runbook tools use — so the kernel and tools layer hold no direct mcp_knowledge_ops dependency for behavior execution. bk.behavior.resume accepts an optional statePatch (e.g. {"approved": true}) merged into the run state before re-evaluation, so an approval unblocks a waiting guard.
• BundleActivation optional behaviorStore field (StateStore?) — injected durable store for suspend/resume across restarts; defaults to per-behavior EphemeralStateStore when absent.
• MCP serving (MCP Serving 1.0) — KernelEndpoint.activate exposes the activated bundle as the well-known bundle://manifest.json resource (the bundle document: manifest metadata + sections) so a remote AppPlayer-class client can resources/read it, reconstruct the McpBundle, and run it identically to a local bundle. KernelServerHost gains a resourceUris introspection getter (parity with toolDefinitions / promptDefinitions), implemented by InProcessKernelServerHost and ServerBootstrap.
• New regression tests included in the system test suite.

Changed (dependency floors) #

The kernel uses symbols introduced in this round's lower releases, so the constraint floors are raised to guarantee them, not merely resolve to them (the prior ^0.2.1-style floors were satisfiable by versions lacking the symbols):

• mcp_bundle ^0.4.0 → ^0.4.1 — BehaviorSection / BehaviorDefinition (bundle.behavior) consumed by BundleActivation.
• mcp_knowledge_ops ^0.2.1 → ^0.2.2 — BehaviorEngine / BehaviorRunnable / StateStore / OpsRuntime.behaviorRegistry constructed by BundleActivation.
• flowbrain_core ^0.1.2 → ^0.1.3 — its re-exported OpsFacade must carry runBehavior / resumeBehavior / listBehaviors (flowbrain_core 0.1.3 raises its own mcp_knowledge floor to ^0.2.4).

Backward compatibility #

• Fully additive. No existing BundleActivation, KernelApp, or tool API changed. Hosts that do not set bundle.behavior see no behavior change.

First public release of brain_kernel. Headless system kernel that wraps mcp_bundle and flowbrain_core with the project / canonical / patch / validate / build / MCP / chat / RAG pieces every host needs, and exposes the BundleActivation standard API that hosts (AppPlayer Core, vibe_studio, future hosts) use to manage per-bundle catalog lifecycle.

Added #

• Core layer — project, canonical store, patch pipeline, asset validator, undo/redo stack, prefs / chat-log / history-log / undo-log sidecars.
• Feature layer — BM25 index, gold-question runner, asset extractor
  • reviewer queue, asset-touch observer.
• Infra layer — bundle reader / knowledge writer / mcpb packager, embedding runner, BM25 query engine + bundle registry, domain storage, FlowBrain wiring (KvStoragePort adapter, runtime probe, LLM port adapter, FlowDefinitionWorkflow), MCP server bootstrap (tool scope + transport picker + server bootstrap), agent LLM sessions, agent chat controller + system-prompt composer.
• System layer — BundleActivation + BundleActivationRegistry: the canonical asset-registration standard. Per-bundle catalog via <bundleId>.<asset.id> prefixing; idempotent registration; one registry handles N concurrent activations.
• Re-exports — flowbrain_core, mcp_bundle, mcp_server, and a selected slice of mcp_client are re-exported so products can stay on the kernel as the single MCP surface (FR-CMP-002).

Dependencies #

• mcp_bundle: ^0.4.0
• flowbrain_core: ^0.1.2
• mcp_llm: ^2.1.1
• mcp_knowledge_ops: ^0.2.1
• mcp_server: ^2.0.0, mcp_client: ^2.0.0