Collaboration and workspace

Bots, groups, schedules, files, Git, worktrees, media and application-owned extensions. Keep the owning profile and resource identity with each operation.

Choose your client · Reliability · All public exports

AsyncHermesExtensions

AsyncHermesExtensions(
    connection: ExtensionTransport, *, profile: str
)

Capabilities must be checked on the running product extension deployment.

capabilities async

capabilities() -> dict[str, Any]

skill_inventory async

skill_inventory() -> list[SkillInventoryEntry]

Stable file identity, including disabled skills; separate from invocation IDs.

toggle_skill async

toggle_skill(
    identity: str, *, revision: str, enabled: bool
) -> SkillInventoryEntry

Per-skill CAS, preserving secrets and unrelated native configuration.

reset_reasoning async

reset_reasoning(session_id: str) -> ReasoningDefaultResult

Clear a session pin through the native profile resolver; no global write.

skill_action async

skill_action(
    kind: Literal["install", "uninstall", "update"],
    resource: str,
    *,
    request_id: str,
) -> SkillActionReceipt

Start one owned native skill action; a running receipt is not success.

skill_operation async

skill_operation(request_id: str) -> SkillActionReceipt

Reconcile a durable profile-owned receipt without replaying its mutation.

skill_content async

skill_content(identity: str) -> SkillDocument

Read the owning native document with a content revision and metadata.

save_skill async

save_skill(
    identity: str, *, revision: str, content: str
) -> SkillDocument

CAS wrapper around Hermes's existing foreground skill editor.

mcp_revisions async

mcp_revisions() -> dict[str, str]

update_mcp async

update_mcp(
    name: str,
    *,
    revision: str,
    patch: McpPatch,
    request_id: str,
) -> dict[str, Any]

One per-server CAS update. Never replace a redacted inventory map.

mcp_operation async

mcp_operation(request_id: str) -> dict[str, Any]

cron_trigger async

cron_trigger(
    job_id: str, *, request_id: str
) -> CronTriggerReceipt

Dispatch through native cron's claim with a durable receipt. Never retry.

cron_operation async

cron_operation(request_id: str) -> CronTriggerReceipt

Read the owning backend receipt after a lost reply or app restart.

prepare_blueprint async

prepare_blueprint(
    blueprint: str, values: dict[str, str]
) -> PreparedBlueprint

Validate a native blueprint into a draft without creating or executing a job.

group_activity async

group_activity(room_id: str) -> list[RoomToolFact]

Read native hosted-member tool facts; independent of room orchestration.

git_inspect async

git_inspect(path: str) -> GitInspection | None

Host metadata for native Git review; capability-gated versioned extension.

git_objects async

git_objects(
    path: str,
    requests: list[GitObjectRequest],
    *,
    limit: int = 4194304,
) -> list[dict[str, Any]]

Bounded, read-only blob or workspace reads for native diff expansion.

git_apply async

git_apply(
    path: str,
    diff: str,
    *,
    target: Literal[
        "staged", "unstaged", "staged-and-unstaged"
    ],
    reverse: bool = False,
) -> dict[str, Any]

Atomically apply a checked native review patch. No mutation retry.

git_diff async

git_diff(
    path: str,
    file: str,
    *,
    source: Literal[
        "uncommitted", "staged", "unstaged"
    ] = "uncommitted",
) -> str

Byte-faithful text patch where native REST normalizes CRLF.

worktree_state async

worktree_state(repository: str, path: str) -> WorktreeState

Inspect a linked checkout, including ignored files and checkout identity.

remove_worktree async

remove_worktree(
    repository: str, path: str, *, revision: str
) -> dict[str, Any]

Checked native removal; never force deletion or retry an unknown outcome.

create_worktree async

create_worktree(
    repository: str,
    name: str,
    base: str,
    branch: str,
    *,
    request_id: str,
) -> WorktreeReceipt

Durable native creation receipt; never infer ownership from a branch name.

worktree_operation async

worktree_operation(request_id: str) -> WorktreeReceipt

AsyncGitMutations

AsyncGitMutations(
    transport: ExtensionTransport, *, profile: str
)

transport instance-attribute

transport = transport

profile instance-attribute

profile = profile

mutate async

mutate(
    path: str,
    action: Literal[
        "commit",
        "push",
        "create-pr",
        "switch",
        "create-branch",
    ],
    *,
    request_id: str,
    message: str | None = None,
    branch: str | None = None,
    push: bool = False,
    include_unstaged: bool | None = None,
    force: bool = False,
    refspec: str | None = None,
    set_upstream: bool = False,
    fail_if_exists: bool = True,
    head_branch: str | None = None,
    base_branch: str | None = None,
    is_draft: bool = False,
    title: str | None = None,
    body: str | None = None,
) -> GitMutationReceipt

operation async

operation(request_id: str) -> GitMutationReceipt

provider async

provider(
    *,
    hostname: str = "github.com",
    path: str | None = None,
    branch: str | None = None,
) -> GitProviderState

GitProviderState

Bases: TypedDict

installed instance-attribute

installed: bool

authenticated instance-attribute

authenticated: bool

hostname instance-attribute

hostname: str

login instance-attribute

login: str | None

avatarUrl instance-attribute

avatarUrl: str | None

pullRequest instance-attribute

pullRequest: dict[str, Any] | None

AsyncScheduleMutations

AsyncScheduleMutations(
    connection: ExtensionTransport, *, profile: str
)

create async

create(
    options: CronCreate, *, request_id: str
) -> ScheduleCreationReceipt

Dispatch once. A lost reply is reconciled using operation.

operation async

operation(request_id: str) -> ScheduleCreationReceipt

snapshot async

snapshot() -> list[ScheduleSnapshot]

Read full native jobs and their revisions in one storage lock.

edit async

edit(
    job_id: str,
    *,
    revision: str,
    updates: ScheduleChanges,
    request_id: str,
) -> ScheduleEditReceipt

Compare and save once using the native cron editor. Replays never write.

edit_operation async

edit_operation(request_id: str) -> ScheduleEditReceipt

ScheduleChanges

Bases: TypedDict

name instance-attribute

name: str

prompt instance-attribute

prompt: str

schedule instance-attribute

schedule: str

enabled instance-attribute

enabled: bool

deliver instance-attribute

deliver: str

ScheduleEditReceipt

Bases: TypedDict

requestId instance-attribute

requestId: str

profileId instance-attribute

profileId: str

jobId instance-attribute

jobId: str

revision instance-attribute

revision: str

status instance-attribute

status: Literal[
    "pending",
    "applied",
    "uncertain",
    "rejected",
    "conflict",
]

ScheduleSnapshot

Bases: TypedDict

job instance-attribute

job: CronJob

revision instance-attribute

revision: str

AsyncGroupAttachments

AsyncGroupAttachments(connection: ExtensionTransport)

connection instance-attribute

connection = connection

stage async

stage(
    room_id: str,
    *,
    attachment_id: str,
    name: str,
    content_base64: str,
) -> GroupAttachment

send async

send(
    room_id: str,
    *,
    event_id: str,
    payload: dict[str, Any],
    attachment_ids: list[str],
) -> dict[str, Any]

metadata async

metadata(
    room_id: str, *, event_ids: list[str]
) -> dict[str, list[GroupAttachment]]

content async

content(
    room_id: str, *, attachment_id: str
) -> dict[str, Any]

GroupAttachment

Bases: TypedDict

id instance-attribute

id: str

name instance-attribute

name: str

mimeType instance-attribute

mimeType: str

kind instance-attribute

kind: str

size instance-attribute

size: int

digest instance-attribute

digest: str

AsyncGroupDialogue

AsyncGroupDialogue(connection: ExtensionTransport)

connection instance-attribute

connection = connection

pending async

pending(room_id: str) -> list[GroupQuestion]

answer async

answer(
    room_id: str,
    *,
    task_id: str,
    execution_generation: int,
    request_id: str,
    answers: dict[str, str | list[str] | None] | None,
) -> dict[str, Any]

GroupQuestion

Bases: TypedDict

sessionId instance-attribute

sessionId: str

roomId instance-attribute

roomId: str

memberId instance-attribute

memberId: str

taskId instance-attribute

taskId: str

generation instance-attribute

generation: int

request instance-attribute

request: dict[str, Any]

AsyncWorktreeArchives

AsyncWorktreeArchives(
    connection: ExtensionTransport, *, profile: str
)

inspect async

inspect(repository: str, path: str) -> WorktreeState

mutate async

mutate(
    repository: str,
    path: str,
    *,
    revision: str,
    request_id: str,
    kind: Literal["archive", "restore"],
    archive_id: str | None = None,
) -> ArchiveReceipt

operation async

operation(
    repository: str, request_id: str
) -> ArchiveReceipt

ArchiveReceipt

Bases: TypedDict

requestId instance-attribute

requestId: str

profileId instance-attribute

profileId: str

archiveId instance-attribute

archiveId: str

kind instance-attribute

kind: Literal['archive', 'restore']

status instance-attribute

status: Literal['pending', 'applied', 'uncertain']

originalPath instance-attribute

originalPath: str

archivePath instance-attribute

archivePath: str

AsyncWorktreeHandoffs

AsyncWorktreeHandoffs(
    connection: ExtensionTransport, *, profile: str
)

inspect async

inspect(repository: str, path: str) -> CheckoutState

mutate async

mutate(
    arguments: HandoffArguments, *, request_id: str
) -> HandoffReceipt

operation async

operation(
    repository: str, request_id: str
) -> HandoffReceipt

bind async

bind(
    repository: str, request_id: str, session_key: str
) -> HandoffBinding

CheckoutState

Bases: TypedDict

path instance-attribute

path: str

repository instance-attribute

repository: str

head instance-attribute

head: str

branch instance-attribute

branch: str | None

dirty instance-attribute

dirty: bool

revision instance-attribute

revision: str

HandoffArguments

Bases: TypedDict

repository instance-attribute

repository: str

source instance-attribute

source: str

target instance-attribute

target: str

source_revision instance-attribute

source_revision: str

target_revision instance-attribute

target_revision: str

source_branch instance-attribute

source_branch: str | None

target_branch instance-attribute

target_branch: str

preserve_target instance-attribute

preserve_target: bool

HandoffBinding

Bases: TypedDict

sessionKey instance-attribute

sessionKey: str

cwd instance-attribute

cwd: str

requestId instance-attribute

requestId: str

profileId instance-attribute

profileId: str

HandoffReceipt

Bases: TypedDict

requestId instance-attribute

requestId: str

profileId instance-attribute

profileId: str

repository instance-attribute

repository: str

source instance-attribute

source: str

target instance-attribute

target: str

status instance-attribute

status: Literal[
    "pending", "applied", "rejected", "uncertain"
]

step instance-attribute

step: str

recoveryRefs instance-attribute

recoveryRefs: dict[str, str]

error instance-attribute

error: str | None

AsyncLiveAudio

AsyncLiveAudio(desktop: AsyncHermesDesktop)

desktop instance-attribute

desktop = desktop

status async

status() -> LiveAudioStatus

negotiate async

negotiate(sdp: str) -> LiveAudioAnswer

LiveAudioAnswer

Bases: TypedDict

ok instance-attribute

ok: bool

session instance-attribute

session: LiveAudioSession

transport instance-attribute

transport: LiveAudioTransport

LiveAudioStatus

Bases: TypedDict

ok instance-attribute

ok: bool

mode instance-attribute

mode: Literal['chained', 'gpt-live']

available instance-attribute

available: bool

reason instance-attribute

reason: str | None

model instance-attribute

model: str

voice instance-attribute

voice: str

AsyncClientWake

AsyncClientWake(connection: NativeConnection)

connection instance-attribute

connection = connection

status async

status() -> dict[str, Any]

start async

start(*, persist: bool = False) -> dict[str, Any]

feed async

feed(pcm: bytes) -> dict[str, Any]

pause async

pause() -> dict[str, Any]

resume async

resume() -> dict[str, Any]

stop async

stop(*, persist: bool = False) -> dict[str, Any]

AsyncRoomPeers

AsyncRoomPeers(
    connection: ExtensionTransport, *, profile: str
)

capabilities async

capabilities() -> dict[str, Any]

invite async

invite(
    *,
    request_id: str,
    capability_digest: str,
    invitation: PeerInvitation,
) -> PeerReceipt

A lost reply must use operation(), never a new invitation identity.

operation async

operation(request_id: str) -> PeerReceipt

route async

route(*, room_id: str, member_id: str) -> PeerRoute

register async

register(
    *,
    room_id: str,
    member_id: str,
    target_url: str,
    target_profile: str,
    grant: str,
    catalog: dict[str, Any],
    cancellation_scope_id: str,
    trace_id: str,
) -> dict[str, Any]

revoke async

revoke(grant: str) -> dict[str, Any]

AsyncRoomPolicy

AsyncRoomPolicy(
    connection: ExtensionTransport, *, profile: str
)

authorize async

authorize(
    *,
    room_id: str,
    member_id: str,
    target_install_id: str,
    target_profile: str,
    catalog_digest: str,
) -> dict[str, Any]

PeerGrant

Bases: TypedDict

grant instance-attribute

grant: str

catalog instance-attribute

catalog: dict[str, Any]

endpoint instance-attribute

endpoint: dict[str, Any]

target_profile instance-attribute

target_profile: str

PeerInvitation

Bases: TypedDict

room_id instance-attribute

room_id: str

home_install_id instance-attribute

home_install_id: str

authority_gateway_id instance-attribute

authority_gateway_id: str

authority_epoch instance-attribute

authority_epoch: int

member_id instance-attribute

member_id: str

grant_id instance-attribute

grant_id: str

ttl_seconds instance-attribute

ttl_seconds: int

PeerReceipt

Bases: TypedDict

requestId instance-attribute

requestId: str

input instance-attribute

input: str

status instance-attribute

status: Literal[
    "applied", "rejected", "uncertain", "pending"
]

result instance-attribute

result: NotRequired[PeerGrant]

error instance-attribute

error: NotRequired[dict[str, Any]]

PeerRoute

Bases: TypedDict

roomId instance-attribute

roomId: str

memberId instance-attribute

memberId: str

targetUrl instance-attribute

targetUrl: str

targetProfile instance-attribute

targetProfile: str

targetInstallId instance-attribute

targetInstallId: str

catalogDigest instance-attribute

catalogDigest: str

grantSha256 instance-attribute

grantSha256: str

status instance-attribute

status: str

AsyncFiles

AsyncFiles(rpc: FileRPC, *, profile: str)

capabilities async

capabilities() -> FileCapabilities

read async

read(
    path: str, *, include_data: bool = True
) -> FileSnapshot

save async

save(
    path: str,
    *,
    workspace_root: str,
    revision: str,
    content: str,
    request_id: str,
) -> FileReceipt

operation async

operation(request_id: str) -> FileReceipt

tree async

tree(path: str, *, workspace_root: str) -> dict[str, Any]

Bounded native snapshot; rejected for unsupported SSH filesystems.

AsyncFileMutations

AsyncFileMutations(rpc: MutationRPC, *, profile: str)

inspect async

inspect(
    path: str, *, workspace_root: str
) -> dict[str, Any]

mutate async

mutate(
    action: Literal[
        "write", "create-directory", "copy", "remove"
    ],
    *,
    workspace_root: str,
    request_id: str,
    payload: dict[str, Any],
) -> dict[str, Any]

operation async

operation(request_id: str) -> dict[str, Any]

AsyncBrowserControl

AsyncBrowserControl(
    connection: ExtensionTransport, profile: str = "default"
)

settings async

settings() -> BrowserControlSettings

configure async

configure(
    *, enabled: bool, revision: str
) -> BrowserControlSettings

register async

register(
    *,
    session_id: str,
    lease_id: str,
    controller_id: str,
    browser_profile_id: str,
    capabilities: list[str],
) -> BrowserControlLease

heartbeat async

heartbeat(
    *, session_id: str, lease_id: str
) -> dict[str, Any]

result async

result(
    *,
    session_id: str,
    lease_id: str,
    command_id: str,
    ok: bool,
    result: Any = None,
    error: str | None = None,
) -> dict[str, Any]

detach async

detach(*, session_id: str, lease_id: str) -> dict[str, Any]

BrowserControlLease

Bases: TypedDict

id instance-attribute

id: str

scope instance-attribute

scope: dict[str, Any]

BrowserControlSettings

Bases: TypedDict

enabled instance-attribute

enabled: bool

revision instance-attribute

revision: str

capabilities instance-attribute

capabilities: list[str]

AsyncGroupMembership

AsyncGroupMembership(connection: ExtensionTransport)

connection instance-attribute

connection = connection

retire_idle async

retire_idle(
    room_id: str, *, latest_seq: int
) -> GroupRetirement

Retire this exact idle revision without cancelling admitted work.

GroupRetirement

Bases: TypedDict

roomId instance-attribute

roomId: str

retired instance-attribute

retired: bool

AsyncArtifactHistory

AsyncArtifactHistory(desktop: AsyncHermesDesktop)

desktop instance-attribute

desktop = desktop

sessions async

sessions(
    *, limit: int = 50, offset: int = 0
) -> ArtifactSessionPage

messages async

messages(
    session_id: str, *, limit: int = 100, offset: int = 0
) -> ArtifactMessagePage

session async

session(session_id: str) -> ArtifactSession

file async

file(session_id: str, path: str) -> dict[str, Any]

AsyncCommandCenter

AsyncCommandCenter(desktop: AsyncHermesDesktop)

desktop instance-attribute

desktop = desktop

status async

status() -> NativeSystemStatus

usage async

usage(*, days: int = 30) -> NativeUsageAnalytics

logs async

logs(
    *,
    lines: int = 200,
    file: str | None = None,
    level: str | None = None,
    component: str | None = None,
    search: str | None = None,
) -> dict[str, Any]

AsyncCommandActions

AsyncCommandActions(
    connection: ExtensionTransport, *, profile: str
)

capabilities async

capabilities() -> dict[str, list[str]]

start async

start(
    *,
    request_id: str,
    action: Literal[
        "doctor",
        "security-audit",
        "gateway-start",
        "gateway-stop",
    ],
) -> CommandActionReceipt

operation async

operation(request_id: str) -> CommandActionReceipt

CommandActionReceipt

Bases: TypedDict

requestId instance-attribute

requestId: str

action instance-attribute

action: Literal[
    "doctor",
    "security-audit",
    "gateway-start",
    "gateway-stop",
]

profile instance-attribute

profile: str

status instance-attribute

status: Literal[
    "pending", "uncertain", "applied", "completed", "failed"
]

pid instance-attribute

pid: int

progress instance-attribute

progress: dict[str, Any]

AsyncKanban

AsyncKanban(desktop: AsyncHermesDesktop, *, board: str)

snapshot async

snapshot() -> KanbanBoard

boards async

boards() -> dict[str, Any]

workflow async

workflow() -> dict[str, Any]

task async

task(task_id: str) -> dict[str, Any]

orchestration async

orchestration() -> dict[str, Any]

AsyncKanbanManagement

AsyncKanbanManagement(rpc: ManagementRPC, *, profile: str)

capabilities async

capabilities() -> KanbanManagementCapabilities

board async

board(board: str) -> dict[str, Any]

task_action async

task_action(
    board: str,
    task_id: str,
    revision: str,
    *,
    action: TaskAction,
    request_id: str,
    payload: dict[str, Any],
) -> KanbanManagementReceipt

board_action async

board_action(
    board: str,
    *,
    action: BoardAction,
    request_id: str,
    revision: str | None,
    payload: dict[str, Any],
) -> KanbanManagementReceipt

operation async

operation(request_id: str) -> KanbanManagementReceipt

orchestration async

orchestration() -> dict[str, Any]

change_orchestration async

change_orchestration(
    revision: str,
    *,
    request_id: str,
    changes: KanbanOrchestration,
) -> KanbanManagementReceipt

attachment async

attachment(
    board: str, attachment_id: int
) -> dict[str, Any]

workers async

workers(board: str) -> dict[str, Any]

AsyncHermesAudio

AsyncHermesAudio(desktop: AsyncHermesDesktop)

desktop instance-attribute

desktop = desktop

transcribe async

transcribe(
    data_url: str, *, mime_type: str
) -> TranscriptionResult

speak async

speak(text: str) -> SpeechResult

live_status async

live_status() -> dict[str, object]

Provider readiness only; this never returns a permanent provider key.

SpeechResult

Bases: TypedDict

ok instance-attribute

ok: bool

data_url instance-attribute

data_url: str

mime_type instance-attribute

mime_type: str

provider instance-attribute

provider: str | None

TranscriptionResult

Bases: TypedDict

ok instance-attribute

ok: bool

transcript instance-attribute

transcript: str

provider instance-attribute

provider: str | None