@topolo/cli 0.12.33 → 0.13.0

package/README.md

@@ -362,3 +362,48 @@ If refresh fails (network, rotated/revoked refresh token), the CLI proceeds
 with the stale credential and the request returns `auth_error` — run
 `topolo auth login` to re-authenticate. The stored config is not cleared on
 transient refresh failures.
+
+## Topolo Agent Packs
+
+`topolo agent-packs` is the public entry point for portable business agent packs.
+The CLI bundles the Codex adapter; Python 3.11+ and the supported Codex desktop
+installation are required for native local switching. No separate pack CLI
+installation is needed. Claude and Cursor adapters are planned and currently
+refused before any mutation. MCP setup for those apps is separate from pack
+switching and does not establish pack adapter support.
+
+```sh
+topolo agent-packs add founder --harness codex
+topolo agent-packs add founder --group specialists
+topolo agent-packs add founder --agent strategy
+topolo agent-packs switch founder
+topolo agent-packs status
+```
+
+A first add builds the bundled template into a fresh installed instance. Later
+adds and switches resume that instance. `--group` selects the template's set;
+`--agent` selects an unambiguous logical agent. Use `list` to inspect installed
+names. Pack templates retain operating rules, rather than earlier work history.
+The underlying `topolo-agent-pack` adapter contains native switching and recovery.
+
+Cloud continuity uses explicit environment and authenticated context pins:
+
+```sh
+topolo --env production agent-packs connect founder \
+  --environment production --context-key org:customer \
+  --agent-workspace DISCOVERED_AGENT_WORKSPACE \
+  --bytes-workspace DISCOVERED_BYTES_WORKSPACE \
+  --ownership user --bytes-scope private --roles roles.json --confirm
+```
+
+`roles.json` maps every `set/agent` to an existing, exactly published
+`agentId` and `agentVersionId`. The hosted Agent and Bytes contracts must be
+released in the selected environment first. The CLI does not create grants,
+choose another customer, invoke model work or silently publish agent versions.
+See the bundled adapter README for memory, artifact and recovery commands.
+
+The source quality gate covers the CLI dispatcher and the Python continuity
+adapter separately. `pnpm coverage` creates a local test environment under
+`node_modules/.cache`, installs the pinned test-only coverage tool and requires
+100% line and branch coverage for the cloud connection/recovery adapter.
+These tests use scoped fixtures and do not invoke models or mutate cloud data.

package/agent-packs/README.md

@@ -0,0 +1,341 @@
+# topolo-agent-pack
+
+A local CLI for real Codex thread packs. Each pack contains agent sets, native
+thread identities, conversation history, inherited history and portable
+instruction definitions. Storage lives outside Codex in `~/AgentPacks`.
+
+Version 0.4.0 supports authored templates and changing packs inside one managed macOS desktop window.
+The window and desktop process stay open. Its idle backend reconnects to the
+incoming native runtime, the sidebar catalog reconciles, and the view reloads.
+This changes the actual backend storage, not just thread visibility.
+
+## Build from an authored template
+
+Version 0.4.0 adds source-independent construction. A template is a regular
+directory containing `pack.json`, common `AGENTS.md`, individual
+`agents/<set>/<id>/AGENTS.md`, selected `shared/*.md`, and optional public
+`skills/<name>/SKILL.md` instructions. It has no native thread IDs or conversations.
+See the bundled `templates/` catalog for eight examples.
+
+```sh
+topolo-agent-pack build founder-acme --template /path/to/templates/founder
+topolo-agent-pack switch founder-acme
+topolo-agent-pack build creative-acme --template /path/to/templates/creative --set specialists
+topolo-agent-pack build venture-economics --template /path/to/templates/ventures --agent economics
+topolo-agent-pack add venture-economics --agent economics
+```
+
+Every build creates unique native thread IDs and file-backed workspaces. Existing
+instance names are refused, so build never resets working conversations. Normal
+switching resumes an instance. Build supports the same set and agent selection
+as fresh, add and replace. Template skills contain Markdown instructions only;
+credentials and account integrations must be configured locally. The digest
+covers the portable roster, role guides and references. The schema, role IDs,
+placements, size and symlink checks run before native construction.
+
+The initial catalog includes founder, creative, research, clients, career,
+personal, learning and ventures: six roles per pack. These are prepared Codex
+packs. Claude/Cursor adapters, independent customer outcome evaluation and
+clean-machine onboarding are separate product work. No model turns are run
+during construction or protocol verification.
+
+## Install and use
+
+Python 3.11+; no Python dependencies or API key for pack operations.
+
+```sh
+python3 install.py
+export PATH="$HOME/.local/bin:$PATH"
+topolo-agent-pack capture topolo --source-home "$HOME/.codex"
+topolo-agent-pack switch topolo
+topolo-agent-pack switch personal
+topolo-agent-pack switch topolo
+topolo-agent-pack status
+topolo-agent-pack recover
+```
+
+Capture `personal` from the intended profile before switching to it:
+
+```sh
+topolo-agent-pack capture personal --source-home /path/to/personal-codex-home --all
+```
+
+**One-time setup:** the first switch opens a manager-owned Codex window, using its
+own local desktop profile. Authenticate there if prompted. It can coexist with
+your current window. Subsequent switches replace packs inside that exact managed
+window; Codex does not need to close. The bridge cannot be attached to an
+already-running unmanaged window. The first launch is reported as requested,
+not as a verified frontend activation.
+
+`topolo-agent-pack open` reopens a selected managed pack after you have closed its
+window. `--no-open` stages and verifies storage without opening a window. If the
+managed window is already open, this flag still reconnects it so it cannot remain
+attached to stale storage.
+
+The CLI refuses switches while agents have active turns. It briefly waits for
+ordinary backend requests to settle. It never force-stops active agents or an
+unmanaged Codex profile. Recovery also checks for active work before reconnecting.
+
+## Compose sets and agents
+
+```sh
+topolo-agent-pack add topolo --set specialists
+topolo-agent-pack add topolo --set specialists --agent security
+topolo-agent-pack replace topolo --set operators
+topolo-agent-pack replace topolo --agent security
+topolo-agent-pack replace personal --agent planner --target topolo/intakes/engineering
+topolo-agent-pack plan add topolo --set operator-skills
+topolo-agent-pack list topolo
+```
+
+Selectors can repeat, and accept semantic IDs, unique aliases or
+`PACK/SET/AGENT`. Ambiguous aliases fail. `add` keeps existing agents and is
+idempotent for the same revision. Conflicting revisions require `replace`.
+`--target PACK[/SET[/AGENT]]` chooses an explicit outgoing scope. An unscoped
+replace replaces the whole composition.
+
+Whole-pack switches retain outgoing runtimes and return to each pack's latest
+saved workbench, including subsequent conversation and workspace edits. Use
+`switch NAME --fresh` to deliberately rebuild the captured source instead.
+Add/replace checkpoints the current composition before building a new runtime.
+Old snapshots and runtimes are retained; there is no automatic deletion.
+If you create additional independent threads in the managed window, partial
+composition refuses to omit them. Register them with `capture NAME --all`, then
+`switch NAME --fresh`, before another add/replace. Whole switches retain them.
+
+Publish an evolved composition with `capture my-workbench`, then export it.
+Captured source revisions and saved workbenches are distinct: a saved personal
+workbench can contain sets added from Topolo without changing the personal source
+manifest.
+
+## Fresh agents with reusable operating context
+
+```sh
+topolo-agent-pack context topolo ./topolo-context
+# Review/edit AGENTS.md, agents/<set>/<agent>/AGENTS.md and shared/*.md.
+topolo-agent-pack fresh topolo topolo-clean --context ./topolo-context
+topolo-agent-pack switch topolo-clean
+topolo-agent-pack fresh topolo sprint-one --context ./topolo-context --set specialists
+topolo-agent-pack fresh topolo design-next --context ./topolo-context --agent design-operator
+topolo-agent-pack add design-next
+topolo-agent-pack replace design-next --target topolo/operators/design-operator
+```
+
+`context` creates editable role scaffolds and extracts bounded conversation rule
+candidates (including inherited sources) into `review/`, with provenance. Review
+and distill those candidates and relevant existing role guides into operating
+instructions. Candidate extraction is keyword assisted, not an exhaustive semantic
+audit. Raw excerpts, review files and prior work records never enter a fresh pack.
+
+`fresh SOURCE NEW-NAME --context DIRECTORY` creates genuine new native thread IDs,
+one per selected role, with no fork ancestors, previous conversations, goals,
+attachments, active tasks or old memory store. Each agent gets common operating
+rules, its role guide, selected `shared/*.md` references and a generated TEAM.md
+containing the fresh team's IDs. Existing authored skills are retained. Optional
+`agents/<set>/<agent>/config.json` selects a reviewed model/reasoning preset:
+`{"model":"gpt-6.1-sol","reasoningEffort":"high"}`. Native permission defaults apply;
+machine-local integrations and credentials remain separately configured.
+
+The native backend creates threads and imports a short bootstrap instruction
+without starting model turns. An offline adapter writes the bootstrap user event
+in the stopped private seed so the desktop catalog can discover it. The native
+catalog and zero-turn state are checked before publication. Starting messages
+contain operating/setup context only. Native memory is disabled for seeded roles;
+file-backed instructions provide the reusable context. Creation leaves the current
+window alone. A destination name already in use is rejected to protect its work.
+
+Fresh packs use the ordinary export/install/add/replace/switch/recover paths.
+Exporting the fresh pack carries only its new starting context, not source work
+history. Editing a context directory changes future instances; already-created
+instances retain their own files and later conversations. To return to ongoing
+work, switch to its saved pack normally.
+
+**`switch NAME --fresh` is different:** it rebuilds NAME's captured snapshot,
+including any captured work history. Use the `fresh` command to create clean agents.
+
+## Live capture and portability
+
+Capture works while Codex stays open. Read-only SQLite snapshots and complete
+rollout prefixes retain projected history and fork/child dependencies. Work
+started after the snapshot remains in the source profile. The snapshot is not an
+ongoing replica. `--offline` instead requires an idle source and checks that its
+files do not change during capture.
+
+`capture topolo` selects Topolo Specialists, Topolo Operators, Topolo Operator
+Skills and Topolo-named pinned intakes. `--all` explicitly selects a whole profile.
+
+```sh
+topolo-agent-pack export topolo ./topolo.pack
+topolo-agent-pack install ./topolo.pack
+topolo-agent-pack install ./topolo.pack --set specialists --agent security
+topolo-agent-pack switch topolo --fresh --map /old/repository=/new/repository
+```
+
+Bundles contain SHA-256 checked manifests and objects, and install independently
+of the original Codex home. Copy the CLI source archive and pack bundles to a
+clean machine. macOS desktop switching is implemented; Linux supports storage
+and native verification with `--no-open`. Windows is not supported.
+
+Default capture copies ordinary workspace files and uncommitted changes.
+Generated directories, Git administration, symlinks, credential files and
+`.env` files are excluded and reported. Repository checkout/setup, worktree
+registration, external services and executable dependencies still need local
+provisioning. Map engineering agents to a local checked-out repository when that
+is their intended environment. Explicit mapping destinations are never overwritten.
+
+```sh
+topolo-agent-pack capture topolo --workspace-mode reference
+topolo-agent-pack capture topolo --include /path/to/workflow-assets
+```
+
+Reference captures store history and instructions while leaving workspaces as
+external paths. These paths must exist or be mapped on the destination machine.
+Authored skills, agent definitions and global AGENTS.md are portable. MCP/plugin
+requirements are declared; install and authorize those tools locally. Put a full
+machine-local configuration in `AgentPacks/local-config.toml` if needed.
+Authentication stays local to the managed profile and follows rebuilt runtimes;
+accounts, cookies and cloud artifacts are not exported.
+
+Conversation history can contain sensitive material. Filename exclusions do not
+scrub conversations. Bundles are private files and are not encrypted.
+
+## Desktop moving parts and recovery
+
+```
+objects/           immutable content addressed by SHA-256
+packs/             immutable captures and revision heads
+runtimes/          independent native homes and workspace checkpoints
+workbenches/       saved compositions and their latest runtimes
+desktop-home/      stable desktop IPC home; native files route to selected runtime
+desktop-data/      shared machine-local desktop account and preferences
+selected-runtime   atomic route to the selected runtime
+launchers/         owned native-backend proxy
+journals/          transaction and recovery receipts
+active.json        atomically committed composition
+```
+
+The desktop starts through an owned backend proxy. A private local control
+socket authenticates CLI requests. The manager pauses only its idle native
+child, builds/verifies the target, commits the active pointer, updates stable
+filesystem routes and frontend state, and requests the app's internal backend
+reconnect. Catalog reconciliation removes unavailable outgoing entries from the
+cache and refreshes incoming native identities. The renderer reloads inside the
+same native window. It reads back catalog counts and identities and checks that
+the managed window still renders the pack.
+
+Restored catalogs receive a target-local completed-backfill marker so native
+startup preserves captured thread timestamps, previews and creator metadata.
+Source backfill and migration watermarks are never imported.
+
+The library is locked during mutations. Native verification checks SQLite
+integrity, working directories and each agent's readable metadata/history through
+the installed Codex backend. Verification sends no model turns. Imported active
+goals are paused; scheduled automations are not imported.
+
+Before-pointer failures retain the previous composition. After-pointer failures
+retain the verified incoming runtime. `recover` reconnects the appropriate
+runtime in the same window, and refuses a concurrent pointer change. Pending
+journals block further mutations. No application bundle is patched.
+
+The bridge uses inspected, private desktop internals and local debugging enabled
+only for the managed profile. It is checked against Codex
+`0.162.0-alpha.17.2`, `state_5.sqlite` and `thread_history_1.sqlite`. A desktop
+upgrade can require an adapter update; incompatible layouts/protocols fail
+explicitly. Keep the store on a local filesystem for predictable runtime access;
+iCloud eviction caused source-file hydration delays during this build.
+
+## Verification and measured scope
+
+```sh
+python3 -m unittest discover -s tests -v
+topolo-agent-pack doctor topolo
+```
+
+See `LIVE_DESKTOP_PROOF.json` for a real macOS window pilot covering switches,
+set addition, individual replacement and recovery, with the same desktop PID and
+renderer target throughout. Small-pack switches measured approximately 3–7
+seconds. The full-pack pilot returned to all 70 Topolo agents in 7.76 seconds,
+with the same desktop process and renderer target. See `FULL_PACK_PROOF.json`.
+Initial materialization and partial composition rebuild history/workspaces and
+cost more than returning to a saved runtime. These are measured samples, not
+latency guarantees.
+
+A live capture of the user's current Topolo profile contains 70 visible agents
+and 75 history threads, including inherited history. It is a reference-workspace
+snapshot; the original profile was not stopped or switched. The earlier
+`REAL_BACKEND_PROOF.json` records a real fork/ancestor export and clean-store
+restore with all 25 stored items exactly retained. `VERIFICATION.json`
+records the final regression and installation checks. Version 0.4.0 passes 35 tests.
+`CATALOG_PROOF.json` records clean-store import and native role-loading checks
+for the 48 agents; older proof files retain evidence from their original versions.
+`FRESH_PACK_PROOF.json` records the complete 70-agent fresh pack, clean-store
+export/import and native resume for all 70 roles, zero model turns and inherited
+work history, and full same-window switching. Historical Topolo was restored in
+8.74 seconds; all 75 of its rollout files remain byte-identical. The fresh pack
+bundle is approximately 2.7 MB. The full-pack round trip
+read every history page before and after: all 94,565 items and 2,486 turns matched
+across 75 threads. All 455 instruction definitions and 97,150 captured table rows
+also matched. The test caught and fixed a legacy-backfill issue that reset thread
+metadata; version 0.2.1 preserves the authoritative captured metadata.
+
+The read-back protocol is documented in the
+[official Codex app-server reference](https://learn.chatgpt.com/docs/app-server).
+The pack format and desktop integration are our own implementation.
+
+## Shared Topolo Agent context and Bytes artifacts
+
+The public command is `topolo agent-packs`; `topolo-agent-pack` is the local
+adapter. Existing `codex-pack` captures are readable without rewriting their
+thread IDs, history or store. This release supports the tested Codex adapter.
+Claude and Cursor require separate native adapters and acceptance tests.
+
+Agent owns scoped memory and installed role identities. Bytes owns artifacts.
+The local runtime holds scratch files and credential-free connection pointers.
+Switching is local; a connected agent refreshes context when beginning work and
+retrieves referenced artifact content only when needed. Cloud calls use a
+separate connection lock so they do not block pack switching.
+
+```sh
+topolo-agent-pack connect founder --environment production --context-key org:customer \
+  --agent-workspace DISCOVERED_AGENT_WORKSPACE --bytes-workspace DISCOVERED_BYTES_WORKSPACE \
+  --ownership user --bytes-scope private --roles roles.json --confirm
+topolo-agent-pack remote-context founder --environment production --context-key org:customer --role specialists/strategy
+topolo-agent-pack remember founder --environment production --context-key org:customer --role specialists/strategy \
+  --content approved-decision.json --kind durable --provenance decision-123 --confirm
+topolo-agent-pack artifact founder --environment production --context-key org:customer --role specialists/strategy \
+  --file brief.pdf --content-type application/pdf --confirm
+topolo-agent-pack remote-recover founder --environment production --context-key org:customer
+```
+
+`roles.json` must map each logical `set/agent` to exactly `agentId` and
+`agentVersionId`. Provision, evaluate and publish those hosted Agent identities
+through their existing lifecycle first. Connections are immutable; changed
+published versions require explicit disconnect/reconnect. Organization packs
+require an organization administrator, organization-owned agents and `org`
+Bytes scope. User packs require user-owned agents; private artifacts live in
+the user's subtree of the verified Bytes workspace. Environments and accounts
+are never inferred or silently substituted. Never reuse another environment's
+workspace IDs. Connect each environment independently after the contracts ship.
+Hosted agents need an explicit Agent `knowledge:read` service grant.
+
+Fresh context includes relevant active instruction, knowledge and durable
+records, filtered by tenant, workspace, user, role and exact version. It excludes
+other users' private memory, expired records, episodes, task/run/thread records
+and previous assignments. Context is bounded to 50 records/64K characters and
+reports truncation. Memory is source material and cannot grant execution,
+approval, messaging or handover authority. Shared durable memory requires an
+explicit sharing policy. Credentials remain in protected Topolo CLI storage.
+
+Artifact upload uses the published SDK URL-session transport, then verifies
+stored bytes through authenticated bounded reads before registering a memory
+reference. Receipts store workspace, scope, key, size, ETag and SHA-256—not upload
+URLs or credentials. Downloads publish a destination only after every chunk and
+the complete digest match. Artifacts up to 100 MiB are supported.
+
+Local `recover` handles native switching transactions. `remote-recover` reads
+cloud receipts and reconciles memory by exact identity/provenance/content; it
+never replays an unknown memory create. Missing or ambiguous outcomes remain
+unresolved for explicit reconciliation. An uploaded but unregistered artifact
+remains stored in Bytes and is reported separately. An uncertain connection can
+be retried with the identical immutable connect request. Switching does not
+reset a remote binding or erase Agent memory or Bytes files.

package/agent-packs/pyproject.toml

@@ -0,0 +1,16 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "topolo-agent-pack"
+version = "0.5.0"
+description = "Portable Topolo Agent Packs with local adapters and shared hosted continuity"
+requires-python = ">=3.11"
+dependencies = []
+
+[project.scripts]
+topolo-agent-pack = "topolo_agent_pack.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

package/agent-packs/requirements-test.txt

@@ -0,0 +1 @@
+coverage==7.16.2

package/agent-packs/src/topolo_agent_pack/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.5.0"

package/agent-packs/src/topolo_agent_pack/blueprint.py

@@ -0,0 +1,57 @@
+"""Strict, source-independent pack templates. No histories or credentials imported."""
+import hashlib,json,pathlib,re
+from . import fresh
+from .storage import PackError,canonical,safe_id
+
+def identifier(value):
+    if not isinstance(value,str):raise PackError('Template identifiers must be strings')
+    return safe_id(value)
+
+def load(lib,directory):
+    root=pathlib.Path(directory).expanduser()
+    if root.is_symlink() or not root.is_dir():raise PackError('Template must be a regular directory')
+    root=root.resolve()
+    files=list(root.rglob('*'))
+    if any(p.is_symlink() for p in files):raise PackError('Template symlinks are not portable')
+    document=root/'pack.json'
+    if not document.is_file():raise PackError('Template requires pack.json')
+    size=sum(p.stat().st_size for p in files if p.is_file())
+    if size>16*1024*1024:raise PackError('Template exceeds 16 MiB')
+    value=json.loads(document.read_text())
+    allowed={'schemaVersion','id','version','name','purpose','agents','dependencies','provenance'}
+    if not isinstance(value,dict) or set(value)-allowed or value.get('schemaVersion')!=1:raise PackError('Invalid template schema or unknown fields')
+    identifier(value.get('id',''))
+    if not isinstance(value.get('version'),str) or not re.fullmatch(r'\d+\.\d+\.\d+',value['version']):raise PackError('Template requires semantic version')
+    if not isinstance(value.get('agents'),list) or not 1<=len(value['agents'])<=200:raise PackError('Template requires 1–200 roles')
+    roster=[];seen=set();titles=set()
+    for n,a in enumerate(value['agents']):
+        if not isinstance(a,dict) or set(a)-{'set','id','title','aliases','pinned','position','sectionName'}:raise PackError('Invalid role fields')
+        identifier(a.get('set',''));identifier(a.get('id',''))
+        key=(a['set'],a['id']);title=a.get('title')
+        if key in seen or not isinstance(title,str) or not title.strip() or len(title)>255 or title in titles:raise PackError('Duplicate or invalid role identity/title')
+        seen.add(key);titles.add(title)
+        if not isinstance(a.get('aliases',[]),list) or any(not isinstance(x,str) or not x for x in a.get('aliases',[])):raise PackError('Invalid role aliases')
+        if not isinstance(a.get('pinned',False),bool) or type(a.get('position',n)) is not int or a.get('position',n)<0:raise PackError('Invalid sidebar role placement')
+        section=a.get('sectionName',value['id'].title()+' Team')
+        if not isinstance(section,str) or not section.strip() or len(section)>100:raise PackError('Invalid section name')
+        roster.append({**a,'pack':value['id'],'pinned':a.get('pinned',False),'position':a.get('position',n),'sectionName':'Pinned' if a.get('pinned') else section})
+    dependencies=value.get('dependencies',{})
+    if not isinstance(dependencies,dict) or set(dependencies)-{'applications','capabilities','integrationNotes'}:raise PackError('Templates declare capabilities, not credentialed server configurations')
+    for k,v in dependencies.items():
+        if not isinstance(v,list) or any(not isinstance(x,str) for x in v):raise PackError('Dependencies must be string lists')
+    definitions=[]
+    for p in sorted((root/'skills').rglob('*')):
+        if not p.is_file():continue
+        if p.suffix!='.md' or p.stat().st_size>1024*1024:raise PackError('Template skills accept Markdown instructions only')
+        definitions.append({'relative':p.relative_to(root).as_posix(),'content':lib.put(p)})
+    # Digest all portable files, including guides and workflows, not machine paths.
+    digest=hashlib.sha256(canonical({p.relative_to(root).as_posix():hashlib.sha256(p.read_bytes()).hexdigest() for p in sorted(files) if p.is_file()})).hexdigest()
+    return {'packId':value['id'],'templateVersion':value['version'],'agents':roster,'definitions':definitions,'dependencies':dependencies,'config':{}},digest
+
+def build(lib,name,directory,binary,sets=None,agents=None):
+    safe_id(name)
+    if (lib.root/'packs'/name/'head.json').exists():raise PackError('Destination already exists; choose a new instance name')
+    if lib.pending():raise PackError('Recover the pending operation first')
+    manifest,digest=load(lib,directory)
+    result=fresh.create(lib,'template:'+manifest['packId'],name,directory,binary,sets,agents,authored=(manifest,digest))
+    return {**result,'templateId':manifest['packId'],'templateVersion':manifest['templateVersion'],'templateDigest':digest}