Published 2026-06-26 05:34 UTC / 2026-06-25 23:34 MDT

Gen 4 starts with the operation catalog

Gen 4 starts with a smaller center for Sidecat: the operation catalog. Each capability gets a stable operation ID, a typed contract, an authority profile, a place where it can run, and an evidence shape for what should remain after it runs.

The Gen 3 package and AAuth work made that center visible. Starlark showed that a package can describe what a tool can do while Sidecat owns validation, argument binding, execution, parsing, contracts, authority, and evidence. AAuth showed that authority has to be native to a capability definition, not layered on after the fact.

That gives every surrounding surface the same source of record. The CLI, daemon, packages, SDKs, web surfaces, and future workbench language can all build from operations instead of each growing its own shadow model.

This is a design-journal note from an early R&D project. The next version of the system is going to make operations the stable unit of the product model.

The cost of finding the shape

The three generations of Sidecat were not cosmetic rewrites. They were different attempts to find the right center. Gen 1 proved the first split: a Sidecat runner, a hardline boundary, an orchestrator, and an MCP bridge. Gen 2 made those ideas useful enough to live with every day. Gen 3 rebuilt the core in Go, pushed package authoring much further, and made AAuth and operator approval concrete.

It also showed the next problem. Even with better primitives, every new capability wanted to become a new command family. Every command family needed help text, dispatch, tests, fixtures, and explanation. The command language started to grow faster than the product model.

The numbers make that history visible. They are not product metrics, and they are not a claim that more code means more value. They show the amount of motion each generation absorbed while we were looking for the right organizing idea. The first table is the current tree snapshot: cloc over tracked files at the revisions listed below.

Revisions counted: Gen 1 sidecat@6a67ec8, hardline.py@376606b, orch.py@c88607c, sidecat-mcp@f420817; Gen 2 sidecat-node@8dc6df7; Gen 3 sidecat@ac1d99b. "Code lines" uses cloc's definition, so recognized configuration and document-like formats may count when cloc treats their content as code. "Test code" is estimated from common test, fixture, and sample-data paths and filenames.

The second table is the history view: commit and line-change totals from Git. Current size says what is present now; churn shows how much motion each generation absorbed while searching for the right shape.

History totals use git rev-list --count HEAD for branch commits and git log --numstat for insertions and deletions. Repository commits include all reachable commits in the measured repositories; branch commits follow the active branch.

Together, the tables say something uncomfortable but useful. Gen 1 proved the first split: a Sidecat runner, a hardline boundary, an orchestrator, and an MCP bridge. Gen 2 made those ideas durable enough to use every day. That is why it matters: sidecat-node is still useful infrastructure for building Gen 4. It gave us work records, coordination, messages, receipts, and governed effects in daily use.

It also showed the complexity ceiling. The surface grew into a large local runtime with too many command families. Gen 3 reduced the file count and found better primitives, but it still took hundreds of commits and hundreds of thousands of changed lines to discover that the center was missing. Gen 4 is the attempt to break through that ceiling by making operations, not command branches, the source of truth.

What the package line proved

The Starlark package work got past a toy demo. A package can be a declaration instead of a little application hidden inside a scripting language. That mattered. The declaration says what a tool can do. Sidecat owns the rest: validation, typed argument binding, execution, output parsing, dry-run behavior, contract checks, and the records that follow from running the operation.

It also taught us where Starlark fits. It is not the best surface for a live command language or exploratory REPL. It is too deliberate for the back-and-forth workbench loop where an agent wants to capture a prompt, queue research, inspect a result, branch a session, and save a useful recipe. But it is still useful deeper in the package stack: a constrained declaration layer where package authors can expose tool capabilities, parsers, redaction rules, and contract fixtures without turning every package into a little application.

Git made the proof concrete. The older git-workbench package had grown into hundreds of lines and many fixtures. The declarative Git package made the same kind of command coverage small enough to inspect, generated contract cases from the declaration, and ran real Git end to end through the package runtime. A non-Git Docker package then showed that the substrate was not secretly shaped like Git. The rule coming out of that work is short: packages declare operations; Sidecat runs them.

AAuth made authority harder to hand-wave

The AAuth work deserves its own place in the Gen 3 record because it was not just another integration. It forced Sidecat's authority model to meet a protocol other implementers can read: agent identity, signed requests, missions, resource-side verification, operator approval, and evidence after the fact.

On June 17, 2026, Sidecat appeared in the public document history for draft-hardt-oauth-aauth-protocol-06, an Internet-Draft with Intended Status: Standards Track. The point was not that Sidecat had launched. The point was better: implementation and interoperability clarifications were tied to feedback from Joshua Gay and Sidecat. The system had produced useful protocol pressure.

That pressure came from working code, not a whiteboard. Gen 3 exercised signed agent tokens, mission references, HTTP Message Signatures, resource-side requirement handling, JWKS discovery, and the beginnings of R3-shaped operation vocabulary. Enough of the protocol was alive to find sharp edges instead of only imagining them.

It also made the human loop concrete. We ran an operator-console Sidecat Person Server at aauth.sidecat.org, signed in with GitLab, admitted bounded credentials, reviewed pending interactions, approved and denied requests as the authenticated operator, suspended grants, and published the static aauth-demo.sidecat.org walkthrough. That server is not the final hosted product, but it proved the shape: a human signs in, sees what the agent is asking to do, and stamps a bounded decision that Sidecat can keep with the work.

The longer writeups are AAuth feedback from a working system and AAuth and the shape of agent authority.

The pressure lines converged

The last stretch of Gen 3 was not one feature. Several lines of work were pushing on the system at the same time.

• The early Gen 3 line established the smaller workbench shape: durable records, Sidebird replay, Sidebar review, sidecatd federation contracts, and package-library workflows.
• The package-authoring reset moved from "packages as arbitrary code" toward manifests, local registry paths, package validation, package tests, installation, and runtime execution.
• The Starlark package line made generic core packages real: sidecat.core, tool execution, parsing helpers, VCS helpers, a Go toolchain package, and the earlier git-workbench package.
• The Git pressure line forced real cases: status, diff, stage, restore, commit, push, path-tail validation, call traces, structured porcelain parsing, plan before stage, and verify after stage.
• The declarative package runtime inverted the authority model: package.star exports a declaration; Go-owned Sidecat code validates input, binds typed argv, executes, parses output, applies dry-run strategy, and generates contract checks.
• The end-to-end proof replaced a large set of fixtures with generated contract cases plus one real Git end-to-end check, then showed that the same substrate could describe Docker without becoming Git-shaped.
• The AAuth line made the human part visible: GitLab sign-in, a local Person Server, credential grants, pending interactions, authenticated operator decisions, grant suspension, and the public aauth-demo.sidecat.org walkthrough.
• The Sidecat Lisp and Sidechat work exposed the next workbench need: backgrounded effects, prompt intake, advisory runs, evidence values, expandable templates, layered debug artifacts, and a three-way local operator-agent chat loop.

What the operation catalog changes

The operation catalog is not just a list of commands. It is where Sidecat says what exists. An operation has:

• a stable operation ID, such as work.event.append or git.push;
• a typed input and output contract;
• an effect and authority description;
• a place where the operation can run;
• the evidence and receipts it can produce.

Once that exists, the surrounding surfaces get simpler. The web UI can render forms from the same metadata. Packages can declare operations rather than smuggle runtimes. Agents can discover capability by reading the catalog. A future Lisp workbench can compose operations without becoming the authority model itself. The daemon can route an operation to the node that has the workspace, package, credential, or runtime needed to perform it.

Protobuf, gRPC, and Sidecat Lisp

The Gen 4 architecture separates names, data contracts, transport, and composition. Operation IDs are the semantic layer. They are the names humans and agents use for capabilities. Protobuf defines the payloads: request messages, response messages, resource names, receipts, and structured errors. gRPC is one runtime binding for invoking those operations between sidecat, sidecatd, and eventually federated Sidecat nodes.

In other words:

• Operation ID: the semantic thing agents and humans use.
• Protobuf: the typed contract for the payload and result.
• gRPC: one runtime binding for invoking it.
• Sidecat Lisp: a small workbench language for composing operations.

The CLI should shrink around that catalog. Commands like describe, template, validate, call, repl, and run can do more work than a long list of noun-grouped subcommands, because they operate on the catalog instead of competing with it.

sidecatd as a node

Gen 4 also keeps sidecatd as the node runtime. A local daemon should know the local workspace, local work records, available packages, local credentials, and which operations it can perform. It can also route calls to another node when the resource, credential, or runtime environment lives elsewhere.

That makes a personal tailnet a natural early deployment model: a laptop node, a server node, maybe a workstation node, and a Person Server for authenticated operator decisions. Tailscale can help nodes reach each other privately, but network reachability is not the same thing as authority. Sidecat still decides what should run, where it should run, whose credential may be spent, and what evidence proves the result.

Sideinfra

There is a second side to this. If sidecat is the programmable API for operating governed work, Sideinfra is the intelligence client that helps agents understand which source-side work can be trusted and which claims still need proof.

That is not another helper script pile. It is the source-side mirror of the same discipline: component ownership, operation location, allowed dependencies, change plans, verification selection, architecture checks, and change receipts. Agents should not have to rediscover where behavior belongs by reading half the repository. The repository, plus sidecatd authority, should be able to tell them.

The line we are drawing

Calling this Gen 4 is not a rejection of the last work. Gen 3 proved real ideas: declarative package authoring, sidecatd custody, AAuth interaction, credential admission, operation-shaped payloads, and the need for a smaller command surface. Gen 4 carries those forward with a stronger skeleton.

The public project stays open-source-first. The Sidecat Dev work remains the place where the core runtime, packages, operation catalog, sidecatd, Sidecat Lisp, Sideinfra, and developer documentation mature in the open. Hosted organizational surfaces can grow separately where they belong.

The public site should make that history easier to inspect. After the repository reorganization, the site can keep Gen 1, Gen 2, and Gen 3 sections as historical evidence: Gen 1 for the sidecat/hardline.py/orch.py script split, Gen 2 for sidecat-node, and Gen 3 for the Go Sidecat rebuild and package-runtime proofs. Active Gen 4 work should sit at the front: sidecat, sideinfra, sidebird, sidebar, and sidechat.

The roadmap now has a more concrete shape: move the first core capabilities into the operation catalog, decide which sidecatd services become typed gRPC APIs first, build the smallest Lisp REPL that proves operation composition, and use Sideinfra to keep the codebase from drifting while the system changes.

- The Sidecat Dev project