The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
"""Projects (``projects.*`` — per-profile multi-folder workspaces, repo discovery, sidebar tree)
and the pet mascot surface (``pet.*`` — gallery, sprite payloads, adopt/remove/rename).
Every method here is profile-scoped: the desktop's ``projectParams`` / ``petRpc`` wrappers add
``profile`` so app-global remote mode reads the focused profile's ``projects.db`` / ``config.yaml``.
The pet wire predates the snake_case rule and travels camelCase (``displayName``,
``spritesheetBase64``); the field names below are those wire keys verbatim.
"""
from __future__ import annotations
from pydantic import Field
from .base import JsonValue, Params, Result
from .common import OkResult, OpenModel, ProfileParams, StoredSessionRow
from .registry import method
# ── projects: stored rows ─────────────────────────────────────────────────────────────────────
class ProjectFolder(Result):
"""``hermes_cli/projects_db.py::ProjectFolder.to_dict``."""
path: str
label: str | None = None
is_primary: bool = False
added_at: int | None = None
class ProjectInfo(Result):
"""``hermes_cli/projects_db.py::Project.to_dict`` — one stored project with its folders."""
id: str
slug: str
name: str
description: str | None = None
icon: str | None = None
color: str | None = None
board_slug: str | None = None
primary_path: str | None = None
archived: bool = False
created_at: int
folders: list[ProjectFolder] = Field(default_factory=list)
class ProjectsPayload(Result):
"""``methods_projects._projects_payload``: every project (archived included) + the active id."""
projects: list[ProjectInfo]
active_id: str | None = None
class ProjectResult(Result):
project: ProjectInfo
class OptionalProjectResult(Result):
project: ProjectInfo | None = None
class ProjectIdParams(ProfileParams):
"""Any method addressed at one stored project (``5062`` when the id resolves to nothing)."""
id: str
method("projects.list", params=ProfileParams, result=ProjectsPayload,
doc="Every project of the profile (archived included) plus which one is active.")
method("projects.get", params=ProjectIdParams, result=ProjectResult,
doc="One stored project with its folders.")
class ProjectsCreateParams(ProfileParams):
"""``use`` also activates the new project."""
name: str
folders: list[str] | None = None
slug: str | None = None
primary_path: str | None = None
description: str | None = None
icon: str | None = None
color: str | None = None
board_slug: str | None = None
use: bool = False
method("projects.create", params=ProjectsCreateParams, result=OptionalProjectResult,
doc="Create a project from a name + folders; duplicate primary paths are refused (5063).")
class ProjectsUpdateParams(ProjectIdParams):
"""Absent keys are left untouched; ``''`` clears ``color`` / ``icon``."""
name: str | None = None
description: str | None = None
icon: str | None = None
color: str | None = None
board_slug: str | None = None
method("projects.update", params=ProjectsUpdateParams, result=ProjectResult,
doc="Patch a project's display fields; answers the refreshed project.")
class ProjectsAddFolderParams(ProjectIdParams):
path: str
label: str | None = None
is_primary: bool = False
method("projects.add_folder", params=ProjectsAddFolderParams, result=ProjectResult,
doc="Attach a folder to a project (optionally as its primary path).")
class ProjectFolderParams(ProjectIdParams):
path: str
method("projects.remove_folder", params=ProjectFolderParams, result=ProjectResult,
doc="Detach a folder from a project.")
method("projects.set_primary", params=ProjectFolderParams, result=ProjectResult,
doc="Make one attached folder the project's primary path.")
class ProjectsArchiveParams(ProjectIdParams):
restore: bool = False
method("projects.archive", params=ProjectsArchiveParams, result=ProjectsPayload,
doc="Archive (or with ``restore`` un-archive) a project; answers the full listing.")
method("projects.delete", params=ProjectIdParams, result=ProjectsPayload,
doc="Delete a project and its folders; answers the full listing.")
class ProjectsSetActiveParams(ProfileParams):
"""No ``id`` (or null) clears the active project."""
id: str | None = None
class ActiveIdResult(Result):
active_id: str | None = None
method("projects.set_active", params=ProjectsSetActiveParams, result=ActiveIdResult,
doc="Switch (or clear) the active project for the profile.")
class ProjectsForCwdParams(ProfileParams):
"""Absent ``cwd`` resolves the gateway's default completion cwd."""
cwd: str | None = None
class ProjectsForCwdResult(Result):
project: ProjectInfo | None = None
cwd: str
branch: str = ""
method("projects.for_cwd", params=ProjectsForCwdParams, result=ProjectsForCwdResult,
doc="Which project (if any) owns a directory, plus the resolved cwd and its git branch.")
# ── projects: repo discovery ──────────────────────────────────────────────────────────────────
class RepoDiscoveryPolicy(Result):
"""``methods_projects._repo_discovery_policy`` — the effective ``desktop.repo_scan_*`` config."""
enabled: bool
roots: list[str]
exclude_paths: list[str]
class RepoDiscoveryPolicyParams(Params):
"""The policy the desktop scanned under (short or ``repo_scan_*`` long keys both accepted)."""
enabled: bool | None = None
roots: list[str] | None = None
exclude_paths: list[str] | None = None
repo_scan_enabled: bool | None = None
repo_scan_roots: list[str] | None = None
repo_scan_exclude_paths: list[str] | None = None
class DiscoveredRepo(Result):
"""``methods_projects._discover_repos_payload`` row: a git root with session totals."""
root: str
label: str = ""
sessions: int = 0
last_active: float = 0.0
class ProjectsDiscoverReposParams(ProfileParams):
"""``scan`` asks the host to walk the policy roots itself (remote-gateway desktop)."""
scan: bool = False
class ProjectsDiscoverReposResult(Result):
repos: list[DiscoveredRepo]
discovery_policy: RepoDiscoveryPolicy | None = None
method("projects.discover_repos", params=ProjectsDiscoverReposParams, result=ProjectsDiscoverReposResult,
doc="Repos for the desktop overview: scanned-from-disk (cached) ∪ session-derived.")
class RecordRepoItem(Params):
root: str
label: str | None = None
class ProjectsRecordReposParams(ProfileParams):
"""Repos as ``{root, label}`` objects or bare root strings; entries without a root are skipped."""
repos: list[RecordRepoItem | str] | None = None
discovery_policy: RepoDiscoveryPolicyParams | None = None
class ProjectsRecordReposResult(ProjectsDiscoverReposResult):
accepted: bool
method("projects.record_repos", params=ProjectsRecordReposParams, result=ProjectsRecordReposResult,
doc="Persist repo roots found by the client's (desktop-side) scan; return the merged list.")
# ── projects: sidebar tree ────────────────────────────────────────────────────────────────────
class ProjectTreeSession(StoredSessionRow):
"""``methods_projects._project_tree_row`` + ``project_tree.stamp_profile``: the minimal row the
sidebar renders, stamped with the profile it belongs to."""
profile: str | None = None
class ProjectTreeLane(Result):
"""One branch / worktree / kanban lane inside a repo; ``sessions`` is empty unless hydrated."""
id: str
label: str
path: str | None = None
isMain: bool = False
isKanban: bool = False
# True only when the placement saw git (probe or persisted repo root). The
# path-only heuristic lane for a non-git folder is isMain but isGit=False,
# so the renderer never offers `git switch` on it (#61362).
isGit: bool = True
sessions: list[ProjectTreeSession] = Field(default_factory=list)
class ProjectTreeRepo(Result):
id: str
label: str
path: str | None = None
groups: list[ProjectTreeLane] = Field(default_factory=list)
sessionCount: int = 0
class ProjectTreeNode(Result):
"""``project_tree._project_node`` — explicit, auto (git root) or the synthetic Home bucket."""
id: str
label: str
path: str | None = None
color: str | None = None
icon: str | None = None
isAuto: bool = False
isNoProject: bool = False
sessionCount: int = 0
lastActive: float = 0.0
totalTokens: int = 0
totalCostUsd: float = 0.0
repos: list[ProjectTreeRepo] = Field(default_factory=list)
previewSessions: list[ProjectTreeSession] = Field(default_factory=list)
sessionIds: list[str] = Field(default_factory=list)
class ProjectsTreeParams(ProfileParams):
preview_limit: int | None = None
session_limit: int | None = None
class ProjectsTreeResult(Result):
projects: list[ProjectTreeNode]
active_id: str | None = None
scoped_session_ids: list[str] = Field(default_factory=list)
method("projects.tree", params=ProjectsTreeParams, result=ProjectsTreeResult,
doc="Project → repo → lane overview with counts and a few preview sessions per project.")
class ProjectsProjectSessionsParams(ProfileParams):
project_id: str
session_limit: int | None = None
class ProjectsProjectSessionsResult(Result):
project: ProjectTreeNode | None = None
method("projects.project_sessions", params=ProjectsProjectSessionsParams, result=ProjectsProjectSessionsResult,
doc="Fully hydrated lanes for one project, from the same grouping as projects.tree.")
# ── pet: active mascot ────────────────────────────────────────────────────────────────────────
class PetInfoParams(ProfileParams):
"""``knownRevision``: the spritesheet revision the caller already holds (send-once bytes)."""
knownRevision: str | None = None
class PetInfoResult(OpenModel):
"""``server._pet_sprite_payload`` behind ``enabled``; every sprite field is absent when the pet
display is off, ``spritesheetBase64`` is elided when ``spritesheetUnchanged``."""
enabled: bool
slug: str | None = None
displayName: str | None = None
mime: str | None = None
spritesheetBase64: str | None = None
spritesheetRevision: str | None = None
spritesheetUnchanged: bool | None = None
frameW: int | None = None
frameH: int | None = None
framesPerState: int | None = None
framesByState: dict[str, int] | None = None
framesByRow: dict[str, int] | None = None
loopMs: int | None = None
scale: float | None = None
stateRows: list[str] | None = None
method("pet.info", params=PetInfoParams, result=PetInfoResult,
doc="Active pet for sprite renderers: spritesheet (base64) + frame geometry + state-row taxonomy.")
class PetInfoMetaResult(Result):
enabled: bool
slug: str | None = None
displayName: str | None = None
scale: float | None = None
spritesheetRevision: str | None = None
method("pet.info.meta", params=ProfileParams, result=PetInfoMetaResult,
doc="Cheap active-pet metadata used to avoid full payload refreshes.")
class PetCellsParams(ProfileParams):
"""``graphics`` opts into the kitty payload when the TTY speaks it; ``cols`` overrides the width."""
state: str | None = None
cols: int | None = None
graphics: bool = False
class PetCellsResult(Result):
"""Unicode: ``frames`` is frame → row → cell ``[tr,tg,tb,ta, br,bg,bb,ba]``; kitty (``graphics``
set): ``frames`` are transmit escapes and ``placeholder`` the text grid."""
enabled: bool
slug: str | None = None
displayName: str | None = None
state: str | None = None
cols: int | None = None
frameMs: float | None = None
frames: list[list[list[list[int]]]] | list[str] | None = None
scale: float | None = None
graphics: str | None = None
imageId: int | None = None
color: str | None = None
rows: int | None = None
placeholder: list[str] | None = None
method("pet.cells", params=PetCellsParams, result=PetCellsResult,
doc="Half-block cell frames (or a kitty placement) for one pet state.")
# ── pet: gallery / picker ─────────────────────────────────────────────────────────────────────
class PetGalleryParams(ProfileParams):
localOnly: bool = False
class PetGalleryEntry(Result):
slug: str
displayName: str
installed: bool
spritesheetUrl: str = ""
curated: bool | None = None
generated: bool = False
class PetGalleryResult(Result):
enabled: bool
active: str = ""
pets: list[PetGalleryEntry] = Field(default_factory=list)
method("pet.gallery", params=PetGalleryParams, result=PetGalleryResult,
doc="Petdex gallery + local install state (installed-only offline); localOnly skips the remote manifest.")
class PetSlugParams(ProfileParams):
slug: str
class PetSlugResult(Result):
ok: bool
slug: str
displayName: str | None = None
method("pet.select", params=PetSlugParams, result=PetSlugResult,
doc="Adopt a pet: install (if needed) + activate; writes display.pet.* to config.")
method("pet.remove", params=PetSlugParams, result=PetSlugResult,
doc="Uninstall a pet (delete its directory); if it was active, turn the display off.")
class PetRenameParams(PetSlugParams):
name: str
method("pet.rename", params=PetRenameParams, result=PetSlugResult,
doc="Rename a pet's display name + realign its slug/dir; follows the active slug in config.")
class PetExportResult(Result):
ok: bool
filename: str
zipBase64: str
method("pet.export", params=PetSlugParams, result=PetExportResult,
doc="Export an installed pet as a re-importable .zip.")
class PetThumbParams(PetSlugParams):
"""``url``: spritesheet source for a not-yet-installed pet."""
url: str | None = None
class PetThumbResult(Result):
ok: bool
slug: str
dataUri: str | None = None
method("pet.thumb", params=PetThumbParams, result=PetThumbResult,
doc="Idle-frame PNG data URI for the picker (desktop CSP breaks CDN <img>).")
method("pet.disable", params=ProfileParams, result=OkResult,
doc="Turn the pet display off from the desktop picker.")
class PetScaleParams(ProfileParams):
scale: JsonValue = None # number or numeric string; a non-number answers 4004
class PetScaleResult(Result):
ok: bool
scale: float
method("pet.scale", params=PetScaleParams, result=PetScaleResult,
doc="Persist display.pet.scale (clamped to engine bounds) from the desktop slider.")