Research and implementation inventory

Vendor-independent agents in Sidecat

Research recommendation · 27 September 2026 · not an implemented contract

Recommendation

Define the responsibility before selecting its performer. A reusable Sidecat agent definition should describe a job, its required knowledge, methods, boundaries and results. An organization can bind that definition to a durable named agent and assign it work while no process exists. When work becomes ready, orchestration selects an eligible implementation and execution launches it with task-scoped authority. The model and harness belong to that activation, not to the business identity.

Keep the responsibility addressable independently of its current holder. For collective work, assign a Plan occurrence to the responsibility, such as messaging-maintainer, and resolve an eligible current holder when it is claimed. A deliberate assignment to a particular agent is also possible. Replacing an agent must not strand the work, erase previous attribution or cause a second execution of an uncertain effect.

This does not require a new object and service for every noun. A reusable responsibility/agent definition can be a package resource. An organization binding can use its existing membership, scoped-assignment and reference mechanisms. Runs, queues, policies and messages retain their respective owners. A one-off subagent does not need a permanent registration; the durable named agent is useful when there is ongoing assignment, communication or accountability.

What the research established

The study used current primary documentation, schemas and source, plus three independent reviews. These are source findings, not claims of runtime qualification.

The important qualification is that portable syntax does not prove equivalent behavior. Harnesses load context differently, support different tools and apply permissions at different layers. An adapter must expose unsupported requirements before performing an effect; it must not silently omit them.

The Sidecat model

These are ownership distinctions, not five compulsory new record families. In the smallest useful version, a responsibility and its named agent binding may be presented together. Reusable definitions are factored out when reused. Existing Sidecat actors can represent agents; adding a new organization-member kind merely because an agent is not human is not justified by this study.

An illustrative definition could contain:

name: component-maintainer
purpose: Maintain one component against its accepted product contract.
scope_input: component
knowledge:
  - accepted product requirements relevant to this component
  - its public contract and the contracts of actual consumers
methods:
  - component-design-and-review
  - implementation-and-focused-tests
  - candidate-handoff
required_capabilities:
  - inspect and modify the component repository
  - reason about its language and concurrency model
  - invoke the declared build and test tools
results:
  - change with behavior evidence and updated documentation
escalation:
  - proposed change to an accepted shared contract
  - unowned requirement or suspected authority problem

This is an explanatory example, not a frozen wire schema. Requirements, methods and knowledge should be typed references to versioned Sidecat records or package resources, not duplicated text. The organization supplies the component, accountable owner, resource limits, applicable policies and permitted implementations. Current policy is checked when admitting work and at the relevant effect boundary; an old definition cannot retain revoked authority just by pinning an old document.

Registration and activation

Registration should be a normal application operation available through the common bus, CLI, MCP and Lisp. It validates the definition and organizational binding, records a stable address, and makes that assignee discoverable under its access scope. It need not contact a model. Publishing a reusable definition into a marketplace neither registers it for a company nor grants it credentials.

product requirements / policies / knowledge / reusable routines
                             |
                   responsibility definition
                             |
          organization binding and durable assignment address
                             |
                  Plan occurrence becomes ready
                             |
         orchestration claims work and requests activation
                             |
       eligible implementation + resources + effective authority
                             |
               executor launches a bounded session
                             |
             results / review / continuation in Sidecat

The ready-work record is durable; a bus notification wakes the dispatcher but is not the only copy of the obligation. A missed notification is recoverable through bounded reconciliation. Claim/lease and concurrency limits prevent accidental duplicate pickup. A pending unknown effect remains attached to its original request identity and is reconciled before a replacement worker repeats it.

A provider change creates a new execution binding or activation. It preserves the responsibility, assignment and prior observations. Cross-provider continuation means resuming from Sidecat's retained task/results and an explicit context packet; it does not promise migration of a provider's opaque conversation or hidden state.

An agent may hold multiple responsibilities. Initially, each activation should select one responsibility and assignment scope. Holding several duties does not automatically union their permissions. Later composite roles can be supported through an explicit authorization decision when there is a real need.

Model suitability without vendor identity

Separate three decisions:

1. Hard eligibility: required tools/protocols/environment are supported; the necessary resources and permissions can actually be granted; limits fit.
2. Observed suitability: evidence for this class of task using this model/harness/tool configuration. Retain evaluation version, conditions and unknowns. A self-description or a general benchmark score is not enough.
3. Selection preference: availability, expected quality, latency and cost among eligible choices, under the selected policy and budget.

There is no universal scalar called model strength. A role can require an assessed capability such as Go concurrency review; the registry can compare candidates on that assessment. Qualification can be stricter for release or authority decisions than for a first draft. Optional routing tools such as Jev may help rank eligible choices; they do not create permission or determine an effect's success.

A new model needs a way to acquire evidence. Policy can permit a bounded trial under review with a restricted task/resource scope. Its observed result becomes qualification evidence. Unknown suitability must neither silently count as proven nor permanently exclude every new implementation. Required technical support and actual authority remain prerequisites even for a trial.

An adapter records effective settings, not merely the requested ones. A model name reported by a child, a launcher-observed configuration and a provider receipt have different evidentiary strength. Sidecat already anticipated this distinction in its runtime-allocation design. Exact retention is selected by the applicable policy; ordinary use need not retain every prompt or provider response.

Existing Sidecat: reuse the ideas, verify the code

At integration source 5f451c0b, internal/sideloop/state.go combines a runner's name, command, directory, prompt, environment and inbox in Profile. maintain/worker_setup.go:117 constructs a concrete Codex command with a model. docs/first-worker.md explains that the worker uses the prepared Sidecat identity and its name identifies a runner. This supports a prepared worker, but does not establish the provider-independent responsibility model above.

The accepted runtime allocation design already separates requested capability from effective provider facts and rejects a universal strength scale. Harness principals separate actor, enrollment, harness and session. The target-oriented messaging specification separates a durable participant from per-message actor/session provenance. These are good conceptual inputs, not proof that every declared feature is implemented. A live catalog search for allocation returned no matching operation in this study.

Adapt those distinctions. Avoid copying the entire central schema or creating a second identity system. Admission of a named agent should reference the existing principal mechanism; authorization remains its own owner's job. Inspect and test the actual credential-delegation path before claiming that launching a worker gives it independent scoped authority.

First proof before relying on this design

Use one component-review responsibility, one named organizational assignee and two real harness adapters. This should be part of the resumed plan, not an extra agent framework built while the product plan remains under review.

1. Register the responsibility/assignee with both providers unavailable. Assign a review and inspect the pending work without launching anything.
2. Start one eligible adapter and observe a single claim, a bounded context and the real output contract. Confirm effective tool and permission settings.
3. Ask for a write under a read-only grant. The actual resource/operation boundary must refuse it, regardless of the prompt's wording.
4. Interrupt the worker, change the available model/harness, and resume from shared task state. Preserve identity, assignment, previous findings and unresolved effects; do not invent transcript continuity.
5. Replace the responsibility holder while work is pending. The new holder finds it; the old instance cannot complete a claim it no longer owns. History records who actually performed each attempt.
6. Change the definition or implementation while an activation is running. Existing work keeps its selected revision unless explicitly amended; new work can select the successor. Current revoked authority still applies.
7. Repeat with a fresh reviewer whose context does not contain the author's preferred conclusion. Detect a known requirement violation and preserve that finding even if the lead disagrees.

No live adapter trials, paid provider calls or production changes were performed for this research. The recommendation is grounded enough to specify and test; it is not a claim that those seven checks already pass.

Sidecat Version 1: product and architecture baseline

27 September 2026 · fixed review copy · proposed, not yet operator-accepted

This is the plan to compare every planning cycle against. Future evidence can change an implementation choice, but a change to the Version 1 target gets a dated successor and a visible change list; this copy stays fixed. Current assignments, progress and release decisions live in Sidecat. The ratified VISION.md, last changed in commit c1d17953 on 18 August, remains the north star. This document applies it to the re-architecture; it does not assert that every proposed mechanism below is already approved or implemented.

The prior Sidecat System 0.1.0 technical draft and Gen 5/domain coverage map are detailed research inputs. They are not silently adopted contracts. Their base author profile has known version-negotiation, reconciliation, time and subscription gaps to close before independent app authors can rely on it.

Purpose and actual use

Sidecat is a programmable environment in which people and AI agents can do useful work for an organization. A fresh agent should find the organization's direction, authority, methods, commitments and next action without asking one lead agent to reconstruct chat history. The organization should be able to see what was requested and why, who could act, what actually happened and what is still uncertain. Software delivery is our first proving ground, not the limit of the product.

Organizational authority is central. A company may allocate model spend, provider quotas, cloud capacity, machines and credentials, then delegate some administration to departments. An agent states the mission for a consequential action. Sidecat can check it against applicable authority, explain a mismatch, request a conditional approval, or refuse the effect. AAuth and aauth-go are part of that design. Deeper evidence custody and review gates are optional enhancements; ordinary starting, talking, reading and working must remain useful without maximum ceremony.

Agents and executors may live on different machines. Five agents on five nodes may share work; a sixth, prepared node may execute without a model login. An agent may disappear for days. Another must be able to find its work, messages, methods and results through Sidecat and continue without a private briefing. There is no permanent lead-agent context or global database that every app must share.

 company authority and resource allocation
                  |
       departments and teams
                  |
 agent + node <--> agent + node <--> agent + node ...
       \             |             /
       shared work, messages, methods, references
                         |
              prepared executor node
               (no agent login needed)

Capabilities required to ship Version 1

These are product capabilities, not a prescribed count of binaries or apps. Each needs a documented, installed user journey before we claim it works.

Proposed record model: answer to the Work/Note question

Recommendation for review: a Work item is its own object with an identity and work-specific meaning. Its description is an exact reference to text, often a Note revision. It does not need to copy that text into a second body field. A Work item can also cite its originating Message and a permitted conversation range. This is a proposal to test, not an operator-approved schema.

The high-volume messaging path should not require a second cross-database write merely to store every short chat body as a Note. Both Message and Note can expose an exact typed content reference that Work can cite. If the message's access scope permits it, a new Work can initially display the original body by reference. If a private conversation must yield a public request, someone creates an authorized new Note/summary and links the restricted source; a reference does not grant disclosure. Refinement creates a new Work revision pointing to revised text while leaving the original message intact. Concurrent revisions use owner-local compare tokens. A cross-owner creation that partly succeeds is reconciled by its stable request key; it is not falsely presented as a multi-database transaction.

This model should be tested by an actual journey: an agent in a room asks for a change, another agent requests clarification and sees the permitted source range, a Work definition is admitted, two plans use it in different contexts, one plan finishes, and the source channel receives a linked update. The other plan and the reusable definition must not be silently closed.

Two simpler-looking alternatives deserve explicit scrutiny. Making every Work and Plan merely a facet of a Note makes assignment, schedule and completion into classification on shared content, recreating a global status problem. Making Work the required evidence spine of every message, model call and effect recreates the current Continuation model's coupling and puts custody on ordinary conversation. Facets remain useful for context-owned boards and classification; selected Plan and Workflow runs can carry optional typed evidence references without making Work own the entire system's history.

Contract for a modular part

Small apps are chiefly a development boundary: one coding agent should be able to understand, change and test a part with a small common contract rather than loading the whole system or needing continuous human steering. A focused app may have thousands of simple lines. Two apps may later combine. Many logical apps may share a resident Go runtime; one app does not imply one process.

Application, package and host are different things. An application owns named behavior and an interface. A package is an exact admitted distribution unit that can contain one or several apps, Lisp methods, workflow definitions, schemas and guidance. A host runs executable contributions. This preserves the ratified rule that packages extend Sidecat itself while allowing a Go app to be a built-in or a long-lived supervised worker behind the same contract. Third-party Go distribution need not depend on Go's platform- and toolchain-constrained runtime plugin ABI or start one process per call. Which generic host/worker profile ships first must be proven by an independent app author; compiling every domain service into sidecatd would fail the package requirement.

In the ratified vision, “kernel” means the shared operating semantics and runtime that make this one system. It need not mean that one Go package or sidecatd owns every business record. sidecatd can host the registry, local routing, federation and bounded continuation while admitted apps own their own meanings and data.

The proposed owner map below is the starting shape to review. A row names one responsibility and its data; it is not a promise of one OS process or an unchangeable app count. A separate app can share a resident host while still owning its interface and store. The first five rows also explain the proposed five-program installation.

Every app must declare:

1. Ownership: its objects, local invariants, authoritative store and effects. Other apps use typed references and public operations, never its private SQL or Go internals.
2. Registration: authenticated owner/instance, exact interface version, operation schemas, effect class, limits and events. Discovery is not a permission grant.
3. Calls: one typed meaning across CLI, MCP, Lisp and service calls; trusted caller scope, mission, correlation and stable request identity where an effect needs deduplication. Accepted/unknown effects have a status or reconciliation operation.
4. Events: distinguish a transient wake from a promised durable event. Subscriptions declare filter, stream/cursor, delivery, acknowledgement, replay/retention and gap behavior. Bindings can turn events into calls without hidden cross-store writes or unlimited fan-out.
5. Authority and placement: a component cannot treat an ID in prose or its machine location as authority. It can run in the resident host or a separate service. An executor-only node needs no CLI or model login.
6. Development proof: an author builds/tests against the published contract and fake neighbors, then passes an installed journey with a real neighbor. Review includes call-surface clarity, failure behavior, maintainability and removal of superseded paths.

Owner-local SQLite databases are the current storage proposal where local transactions matter. A stateful app normally owns a separate database; a stateless app needs none, and a justified atomic owner can combine related records. This is neither one universal database nor one database per command. Cross-owner work needs explicit requests, references and sourced observations, not an imagined multi-database transaction. Files/blobs may use a content store or Git where versioned distribution helps; Git is not presumed to be every record's synchronous writer. Exact bus and storage wire contracts still require focused design and measured trials.

Daemon readiness opens its local stores, checks schema identity and store ID, then listens. Whole-history integrity verification is an explicit operator action, never a prerequisite for an ordinary start, message, call or effect.

Candidate public call surface

The existing command-surface design sets a useful rule: a small visible set of nouns, shared verbs (find, show, create, update, give, use, remove) with one meaning, and one operation definition projected into argv, MCP and Lisp. Replies give outcome, used scope, a short typed reference and a useful next step. Only organization and project are visible defaults; reading or creating does not silently change them. Packages can add nouns without minting a second meaning for a shared verb. The current design lists eleven core nouns and is only partly converted. The proposed groups below extend that rule; spellings and the Work/Plan conflict still need resolution.

The first screen for an agent should offer its prepared task and relevant calls, not the entire catalog. Exact generic operation calls remain available to app authors and advanced callers, but need not occupy the ordinary default MCP set. The organization's two-call goal counts discovery, help, retries and the consequence call; when an ordinary task takes more, treat that as product friction to investigate rather than hide calls in a helper.

Existing Gen 5 operation names are inventory, not compatibility requirements. An independent read of exact installed .13 found 297 native operations; its MCP endpoint advertises 293 of them. Its CLI source has 106 leaf commands; the integration branch's path fixture lists 126 leaves and group paths. These are different inventories, not interchangeable counts. The public review page includes the 293 advertised MCP names/descriptions and the 126 source paths. The table below bins all 297 native operations by the task they now serve. Its disposition column is a proposal, not an order to delete a needed capability.

Today work.capture, work.create, work.plan and project.backlog-update expose different models; command and execution expose different layers of one run. The table is a complete purpose map, not a claim that all those operations should survive Version 1. The exact compact catalog below permits review of individual names without forcing all 297 descriptions into an agent's default context.

Concurrency, federation and delegated authority

The operator's retained 19 September scale example was 200+ active agents per person and roughly 25,000 concurrent agents across a large organization, with thousands within departments. This is a design target, not a claim that one node or one SQLite writer serves them all. Agents usually concentrate in related application groups. Qualify in stated rungs: first 500 concurrent callers across several nodes, then department-scale thousands, then the multi-node organization target. Each rung includes independent Work updates, one hot room, a hot record writer, slow subscribers, provider latency, restart and a multi-day absent agent. Report throughput, p50/p95/p99 latency, write waits, queue depth, memory, event lag, database growth and context delivered per agent. These benchmark profiles need measured hardware and workload definitions before a pass threshold is claimed.

SQLite WAL permits concurrent readers with one writer per database (SQLite's WAL documentation); its WAL files do not become a network-shared database. Each state owner therefore needs bounded admission, short transactions, useful indexes and explicit contention behavior. Independent owners must not queue behind one giant central database writer. A hot owner may later partition its store by organization or stream if measurement supports it; the app contract must not expose its table layout. No model or network call occurs while an owner holds a write transaction.

A company-wide spending limit cannot be enforced by five disconnected nodes each consulting an eventually synchronized counter. The proposed resource owner reserves budget before a managed effect, delegates bounded sub-budgets or leases to departments/nodes, and settles observed use. An uncertain effect keeps its reservation until reconciled or explicitly released. During a partition, a node may use only its preallocated allowance; it cannot invent additional company authority. Ordinary local work can continue. This is a technical design requirement to test, not a claim that today's local auth service already does it.

The bus separates addressed calls, source-owned events and bindings. A durable event is committed with the owner's change, then delivered at least once; subscribers acknowledge after recording their own promised action. A cursor belongs to one owner stream and a gap is explicit. Local direct dispatch, Unix sockets and remote federation preserve one selected operation meaning, but do not imply a globally atomic call or one total order. Messaging has its own durable room/direct semantics and cannot be replaced by transient bus signals. Remote effect owners recheck the received authority at the effect boundary. Sidecat's authorization can govern only resources whose credentials or execution path are actually mediated; ambient shell/root access is not magically revoked by a Sidecat refusal.

Before freezing a shared protocol, independent authors must implement one small stateful app and a separate client from the public author kit. A routine app-local field change must not require manual edits to daemon routing, central SQL, or separate CLI/MCP/Lisp schemas. The provisional System 0.1.0 author profile still needs exact minor-version negotiation, an actionable unknown-outcome status call, a defined time model, immutable schema retrieval, consistent event identity, and complete subscription/ack/gap rules. These are freeze blockers, not justification for a new giant kernel.

The working component specification proposes concrete resolutions for review:

No cross-language conformance is claimed until a separate app author and client exercise these rules through an installed runtime. The detailed draft is a proposal, not evidence that today's daemon already implements it.

Delivery sequence and distinct finish lines

The detailed component specification and engineering plan are native Sidecat organization references modularization-spec-20260925 and modularization-plan-20260925. They propose an implementation sequence; this baseline states why and what the whole product must do. The selected sprint remains general workflows with auth integration until it is reviewed.

The October 15 public-release target and the later stable 1.0.0 target are planning dates, not evidence that the full Version 1 table will be ready on October 15. A preview must state its actual included capabilities and limits. This page does not move either date or silently reduce the Version 1 target.

Version 1 release assessment uses these end-to-end journeys. Component unit tests are supporting evidence, not substitutes for them:

The engineering order is public contracts and execution owner; independent auth and durable orchestration; record/store owners and bus; complete Lisp, messaging, federation, package and organization connections; whole-system qualification and controlled cutover. Each sprint includes design, code, build, independent QA, documentation and review. The sequence is not a claim that later capabilities are optional or that current component tests qualify a release.

Reuse or rebuild: the decision we have to make

Keeping a Gen 5 component because it exists is not a reason. For each part, compare the work needed to make it satisfy the Version 1 contract with a focused new implementation of the same user journey. Count shared files and decisions an independent author must understand, adapter code, test/build time, installed call friction, runtime limits and deletion of replaced paths. Do not compare only source line counts or a passing unit suite. There are no external users whose old stores or calls require compatibility today. Preserve our useful unfinished Work by export and checked repopulation on a fresh store; keep the old live store as an archive until a controlled cutover, not as a schema the new system must inherit.

From the pre-refactor product baseline fe645577 to the current integration head, 322 files changed with roughly 32,500 insertions and 4,000 deletions. New services and APIs account for about 15,200 inserted lines, while daemon, kernel and SQLite changed by about 6,200 inserted lines and the maintenance tree by about 7,500. The large source/QA effort produced real independent execution, local auth and orchestration experiments, but only 573 lines were added and 271 removed in internal/sqlite: the central database has not been cleaned up. Installed trials repeatedly found real setup, result, help and review-continuation defects, which required repair and retest. This explains where time went; it does not justify continuing the same approach without the author-contract and user-journey comparison above.

The imbalance matters: much new code and qualification machinery were added while little central SQL was removed. Extracting services before fixing the app-author and user-call contracts made every component pay an adapter and integration tax. Some of that work proved valuable behavior, especially the executor; some is self-inflicted project cost. Future increments must name which old owner/path they retire and demonstrate that an agent's normal task became simpler, rather than calling another isolated passing service a re-architecture milestone.

Before the next implementation sprint, inspect the existing call/store path for one Note → Message → Work → Plan journey, then build the smallest version of that journey through the proposed app-author contract and fresh stores. Do not build two complete systems merely to create a comparison. Compare the working installed result with the existing code and measured edit/test cost: concurrent use, files and decisions touched, independent testability, build time, call count and code that can be deleted. A fresh implementation wins only if it meets the same environment, authority and federation needs. This is a proposed qualification after the product plan is agreed, not an implementation assignment now.

Decisions this review must settle

What the last 1 day 19 hours 37 minutes built

Approximately 25 September 19:47 to 27 September 15:24 MDT. The integration branch contains 62 commits in that window at local head 5f451c0b; a commit is an engineering checkpoint, not a shipped feature.

No public Version 1 release, main-line promotion or shared-node cutover is claimed. The installed .13 source is 944ee79c; the later local source 5f451c0b was not that installed archive and has no full integration-head qualification record. At the operator's 27 September 15:24 MDT instruction, implementation, builds, tests and new agent research were stopped pending a clear plan.

Planning-cycle rule

At the start of each cycle, read this exact baseline and VISION.md, then the current Sidecat organization guidance, selected sprint, Work and release evidence. Say which capability the proposed outcome advances, how its app boundary helps independent development, what old complexity it removes, and what remains unproven. Record progress in Sidecat. To alter the Version 1 target, publish a dated successor with a before/after explanation; do not edit this baseline to make a past choice appear inevitable.