tutti/packages/AGENTS.md

AGENTS.md

Scope

This file applies to packages/*.

packages/ is for real shared boundaries, not as a default home for reusable-looking code.

If you are editing packages/agent/gui/*, read docs/architecture/agent-gui-node.md first, then packages/agent/gui/AGENTS.md.

If you are editing Agent session, Turn, Goal, runtime-operation, or recovery lifecycle under packages/agent/*, read the root Agent Host Boundary and packages/agent/host/README.md first.

If you are editing Cassette projection, checkpoint readiness, or final-state replay compare under packages/agent/session-replay/*, read packages/agent/session-replay/AGENTS.md and packages/agent/session-replay/README.md first.

If the task mentions AgentGUI, AgentGuiNode, Agent GUI, the agent conversation module, agent composer, workspace agent timeline, agent approvals, or interactive agent prompts, read docs/architecture/agent-gui-node.md first, then packages/agent/gui/AGENTS.md, before planning or editing even when the target files are not known.

If you are editing packages/ui/*, also read packages/ui/AGENTS.md.

Connector work under packages/connector/*, or work that changes Connector contracts, daemon lifecycle, runtime execution, or shared React surfaces, must read packages/connector/AGENTS.md before planning or editing.

Package groups

• clients/*: shared domain-specific clients
• connector/*: Connector contracts, daemon core/application/adapters, runtime execution, and shared Renderer application/UI
• device-link: shared ICE/QUIC peer transport, product-neutral Relay stream mechanics, and gomobile boundary
• events/*: shared schema-first business event protocol contracts and generated transport metadata
• agent/*: Agent lifecycle Host, canonical store, frontend activity engine, replication contract, and GUI boundaries
• browser/*: reusable browser/workbench node mechanics for desktop hosts
• configs/*: shared TypeScript and formatting config
• desktop/*: product-neutral desktop lifecycle and host-integration contracts shared by desktop products
• ui/*: shared frontend-foundation packages
• workbench/*: shared Workbench host lifecycle, snapshot contract, and reusable surface packages for the open-source desktop and TSH
• workspace/*: narrow workspace-domain contracts and feature surfaces intended for reuse across the open-source desktop, TSH, and TACH

Package rules

• name packages by responsibility, not by audience
• avoid vague names such as shared, common, utils, or client-sdk
• keep clients/* focused on domain-specific access patterns
• keep connector/* focused on host-neutral connector semantics, contracts, state, canonical persistence, daemon lifecycle, and same-machine runtime mechanics shared by real hosts; remote endpoint authentication, credentials, host state-root selection, generated daemon clients, product command publication, and OS process integration stay in host adapters
• keep device-link transport-only: it may own candidate selection, authenticated peer streams, generation-fenced admission, product-neutral pooling/racing/probe mechanics, WebSocket/yamux Relay byte-stream mechanics, and platform build boundaries, but not account, pairing, rendezvous, path-specific authentication, Relay authorization or product policy, or Agent/Workspace DTOs
• keep events/* focused on repository-owned business event protocol contracts, topic catalogs, generated validators, and transport metadata rather than socket lifecycle or daemon business workflows
• keep browser/* focused on browser mechanics, workbench node integration, bridge shape, Electron webview guest management, and package-local i18n defaults; host product globals, backend-token access, preview proxy behavior, and business bridge methods stay in host adapters
• keep desktop/* focused on product-neutral desktop lifecycle, contracts, and adapters; product transport, release URLs, update feeds, assets, and business-window selection stay in host composition
• keep ui/* focused on shared frontend-foundation concerns such as tokens, icons, styles, primitives, and host-agnostic i18n runtime support
• keep workbench/* focused on product-neutral host lifecycle, snapshot compatibility, and Workbench interaction mechanics, not product-specific node UI or app workflows
• keep workspace/* focused on reusable workspace-domain semantics and state; concrete host adapters stay in the owning service, app, or integration
• a reusable frontend workspace-domain package may still own shared session orchestration, view-model derivation, and React-facing interaction state when those behaviors are intentionally shared across hosts
• a reusable frontend package that owns optional UI may also own narrow default i18n resources for that shared surface; keep those defaults in the owning package and let hosts override them through their app-level i18n or i18n runtime
• keep host-specific transport wiring, desktop preload calls, daemon client construction, host absolute paths, and product-specific integration details out of workspace/*
• keep host-specific transport wiring, product global names such as __tutti or __tsh, and product bridge methods out of browser/*
• do not move code into packages/ until there is a real multi-consumer boundary
• treat a public npm package as an explicit external contract, not as automatic proof that the package already has multiple in-repository consumers
• when a package is intended for public npm release before a second in-repository host exists, document that external contract in the npm release conventions and review the package as a deliberate published boundary rather than as speculative pre-extraction
• keep package root exports narrow; do not export internal helpers, test fixtures, demo data, or implementation-specific hooks just because they are convenient inside the package

Extraction guidance

Keep code local by default:

• TypeScript code used only by desktop stays in apps/desktop
• Go code used only by the daemon stays in services/tuttid

Move code into packages/ only when:

• it defines a cross-boundary contract
• it has more than one real consumer
• the extracted API can be named narrowly by responsibility

Exception:

An intentionally published public npm package may live in packages/ before it has two in-repository consumers, but only when the package has an explicit external contract and is included in the durable npm release conventions.

Testing defaults

Packages do not override the repository validation workflow. Follow Validation Selection and add only checks required by the closest package AGENTS.md.

Related docs

• docs/conventions/README.md