Assets

What an asset is, how assets reach the desk, how git versions are numbered and move at sync, how a launch card suggests assets, and what plugging as reference, target or instructions does

An asset is a folder, a repo, a link or a note that the library tracks and a run can read or write. This page says what the code does; file:line citations are in parentheses.

01what an asset is#

An asset is a record in the library. Its fields are id (a- and 16 hex digits), name, kind, about, working_dir, engine, picked_version, remote and branch (git assets), url and notes (link and notes assets), tags, created_at and created_by.

There are three engines:

• snapshot keeps versions as manifests over a blob store.
• git reads a repo: its versions are commits (see git versions).
• none is for link and notes assets. They have no folder and no versions.

picked_version is read by AtGo, which returns what a run would read if go were pressed now:

• A snapshot asset: if the folder has no working changes, AtGo reads the version in picked_version. If the folder has working changes, AtGo reads the folder itself, numbers it as the next version, and stores nothing.
• A git asset: AtGo ignores picked_version and reads the branch tip. Adopting a repo never sets it, so it stays 0.
• Engine none: AtGo refuses with "has no files to read".

02how assets get on the desk#

The asset_import tool takes project and one of asset (add a library asset by id, as a reference and never a copy), dir (adopt a folder; the top of a git repo becomes a git asset) or new (a name for a new empty asset). main also makes it the project's main asset.

Adopting a repo (AdoptRepo) makes a git asset whose created_by is adopted. Adopting the same checkout and remote again returns the record already there. The branch is origin/HEAD's branch, else main, else master, else the checked-out branch.

When the desk boots, registerRepoAssets runs:

• It adopts only the repo of each saved project that has a path. A repo with no project is not adopted.
• A new record gets created_by of desk boot: project <name>'s repo.
• It logs asset imported: <id> <name> <dir> (<by>) once per new record.
• It adds the asset to the project's assets, and makes it main_asset when the project has none. See projects.

03snapshot assets#

Four facts about a new snapshot asset. Line numbers were read at the commit this page was written from.

• v1 is empty. asset_import with new calls Library.NewBy, which makes an empty working folder and at once cuts version 1 with the note "created" and no files. In a new asset the first snapshot is v2, because the number is the last existing version plus 1. v1 is a real, empty version that is never rewritten. Nothing hides it.
• The folder. A new asset's working folder is <core data dir>/assets/folders/<id> unless dir was given (; FoldersDir is set at). A given dir must not exist or must be empty. The chat's scratch folder is a different root, under the shell data dir. The two roots are separate on purpose. See where smith keeps its files.
• File viewer roots. The viewer accepts the project roots, the core data dir, and the shell's attachments and scratch folders. A snapshot asset's working folder is read at its picked version, and only for files that version's manifest names. A report_issue screenshot does not use that resolver: shotPath (internal/desk/report_issue.go) takes png or jpg files under the shell data dir or under the asset folders (Library.FoldersDir), and nothing else.
• made_by. A snapshot version's made_by is run, user, outside or conductor. A version cut by a desk tool call from any chat, side chats included, is conductor. user is the window's own press. The chat that cut it is not recorded.

04git versions#

Version n is the n-th commit of the asset's branch in git log --first-parent --reverse, oldest first. A version's files come from one ls-tree of its commit.

• made_at is the commit time (%cI).
• head_at and made_by come from the first observation of that commit as the checkout's head. made_by is run, sync or outside. A commit never observed keeps outside.
• never_head marks a commit between the first and last observed heads that was never observed itself.
• A sync records the head with made_by sync. Desk boot records it as outside. So versions are the branch's commits, and they gain new numbers when the branch moves at sync.

Numbers stay stable only while the first-parent history is not rewritten. Nothing in the code checks that.

The assets page shows the file count of the tip for a git asset and of picked_version for a snapshot asset (assetDetailOf).

05launch-card suggestions#

A launch card suggests assets for its ticket. Everything here is in internal/desk/launch_assets.go.

• Assets the ticket names come first, with the reason "named in the ticket" (plus " at vN" if it gave a version). A name is an id like a- and 16 hex digits with an optional " vN", or an absolute path at or under an asset's folder. The cap of 3 does not apply to them.
• Word matches follow, from the project's member assets only.
  • The project's main asset is never offered by words. Retired assets and assets already plugged are left out.
  • Text inside backticks or code fences is dropped from the ticket.
  • Ticket words are lowercase, at least minSuggestWord = 4 runes long, and not stop words. The stop words are common English words and generic ticket words.
  • Each asset is matched on its name, its about and its text files at the version go would freeze. The caps are suggestFileCap 64 KiB per file, suggestAssetCap 256 KiB per asset and suggestFilesPerAst 40 files.
  • A skill is matched on its name and its SKILL.md description, never its body, and is offered as instructions.
  • Ranking uses the same lexindex tokenizer and BM25 as asset_search (comment at line 543), weighted over the project's members. asset_search itself searches the whole library.
  • With 2 or more members, a word found in every member is skipped.
  • An asset is listed only if its summed weight is at least minSuggestScore = 0.2.
  • The reason reads matches “a”, “b”, “c”: up to 3 of the highest-weight terms. The score is rounded to 2 decimal places.
  • Ties sort by name. At most maxSuggested = 3 word matches are listed.
• Nothing is plugged until the operator keeps a suggestion. launchKeep then makes a new card that plugs it as a reference, or as instructions for a skill.

06plugging#

A plug has a role. Any other role is refused.

• reference: the files are handed over as data, never as instructions.
• target: the asset the run writes. Its next version is what the gate approves and land makes.
• instructions: a skill asset loaded as a skill, on claude nodes only. See skills.

The rules:

• A card has at most one target, and it must be a snapshot or git asset.
• A git target must be the project's own repo, and then the run is the ordinary git run.
• files and copy apply to a reference only.
• Instructions need kind skill and a valid SKILL.md.

When a plug names no nodes it reaches harness.ReadingNodes: plan then work, those the template has as runtime nodes.

At go, each plug is frozen at the AtGo version shown on the card (LaunchAsset).

The plug itself is AssetPlug with the fields id, role, nodes, files and copy (; the card tool's copy).

• nodes names the nodes the plug reaches. Empty means the reading nodes above.
• files are paths or globs of a reference to inline in full.
• copy is reference only: an asset file path mapped to a repo path, copied byte for byte into the run's worktree at go.

07kind#

kind is a free label on the record with two that the code treats specially:

• skill: an asset whose folder has a valid SKILL.md. The kind is set when such an asset is added. Only a skill can be plugged as instructions. See skills.
• code: set on a git asset when a repo is adopted. Other special meaning of code: not checked.

08tags, about and derived_from#

• tags are lowercase labels like key or key:value (letters, digits, hyphens). At most 16 per asset. A bad tag is refused. The asset_tags tool sets them.
• about is the asset's one-line description. asset_describe sets it. about_model_written marks an about a model wrote and auto-accept applied.
• derived_from and derived_from_version record the source asset and its picked version when a link was made. The asset_link tool adds a link asset; that is a url asset and is not the same thing as derived_from.

09asset checks#

checks are the command checks a run that writes this asset is held to. Each has an id, executable, args, cwd and timeout. See checks.

10retired#

retired takes an asset out of the lists and out of suggestions without deleting it. A card proposes it with propose_asset_retire. Launch records and the "used in" list keep naming a retired asset at the version they froze.

11immutable versions#

A snapshot version is a manifest over a content-addressed blob store. A version is never rewritten: asset_snapshot and asset_version cut a new one and earlier versions stay. asset_version writes files into a snapshot asset's working folder first, and refuses a path outside the folder or an asset with no folder smith may write to (git, link or notes).

A run reads a version from a mount: Mount lays version n of the asset out once at <library>/mounts/<id>/<n>, built in a sibling temp folder and renamed into place so a half-written mount is never seen.

12target runs#

A run whose target is a snapshot asset works in a folder of its own that is not a git checkout. The folder carries a marker, .smith/target.json, naming the version it began as and its files. The run's changes are the files that differ from the marker's, and the gate approves them as the asset's next version (; the write is in internal/service/harness_assets.go and patch_target.go; the steps of that write: not checked).

Reviewers get target_diff: the text diff of the folder the run edited against the version it began as, with binary files listed by size (;).

13used in#

An asset's "used in" list reads the launch records that plugged it, with the role and the frozen version. Retiring the asset later changes neither.

14a run sees only what is plugged#

A run reads no asset it is not plugged with. A reference is handed over as data, an instructions plug is loaded as a skill, and a target is the folder it writes. Nothing else in the library is visible to the run. How the run's sandbox enforces this beyond what the plugs hand over: not checked.