Public surface

This page is generated from the public protobuf contract. Do not edit it by hand.

This reference includes the supported gRPC services and RPCs derived from the protobuf contract.

• Public services in scope: 15
• Public RPCs in scope: 90
• gRPC-only public RPCs: 6
• Additional supported RPCs outside the main service list: 0

Service index

• aetherfs.v1.AnalyticsService
• aetherfs.v1.AnnotationService
• aetherfs.v1.CollaborationService
• aetherfs.v1.FileSystemService
• aetherfs.v1.HealthService
• aetherfs.v1.KnowledgeCacheService
• aetherfs.v1.MessageBusService
• aetherfs.v1.ObservabilityService
• aetherfs.v1.OversightService
• aetherfs.v1.PersistenceService
• aetherfs.v1.SecretsService
• aetherfs.v1.SessionService
• aetherfs.v1.ToolingService
• aetherfs.v1.UnderlaySourceService
• aetherfs.v1.UsageService

aetherfs.v1.AnalyticsService

AnalyticsService provides RPCs for retrieving performance metrics and key operational data about agent sessions. This is the core of the Agent Performance Observatory.

This entire service is part of the supported public gRPC surface.

RPC	Shape	HTTP
GetSessionAnalytics	Unary	GET /v1/sessions/{session_id}/analytics

GetSessionAnalytics

Retrieves a detailed analytics report for a single session.

• Signature: GetSessionAnalytics(GetSessionAnalyticsRequest) returns (SessionAnalytics)
• RPC shape: Unary
• HTTP binding: GET /v1/sessions/{session_id}/analytics

aetherfs.v1.AnnotationService

The AnnotationService provides the ability for humans and agents to leave line-level feedback on files within a session.

This entire service is part of the supported public gRPC surface.

RPC	Shape	HTTP
AddAnnotation	Unary	POST /v1/sessions/{session_id}/annotations
GetAnnotations	Unary	GET /v1/sessions/{session_id}/annotations
UpdateAnnotationStatus	Unary	PATCH /v1/sessions/{session_id}/annotations/{annotation_id}

AddAnnotation

Adds a new annotation to a file.

• Signature: AddAnnotation(AddAnnotationRequest) returns (AddAnnotationResponse)
• RPC shape: Unary
• HTTP binding: POST /v1/sessions/{session_id}/annotations

GetAnnotations

Retrieves all annotations for a specific file or the entire session.

• Signature: GetAnnotations(GetAnnotationsRequest) returns (GetAnnotationsResponse)
• RPC shape: Unary
• HTTP binding: GET /v1/sessions/{session_id}/annotations

UpdateAnnotationStatus

Updates the status of an existing annotation (e.g., to resolved).

• Signature: UpdateAnnotationStatus(UpdateAnnotationStatusRequest) returns (UpdateAnnotationStatusResponse)
• RPC shape: Unary
• HTTP binding: PATCH /v1/sessions/{session_id}/annotations/{annotation_id}

aetherfs.v1.CollaborationService

The CollaborationService provides features for agents to coordinate their work within and between sessions, such as resource locking.

This entire service is part of the supported public gRPC surface.

RPC	Shape	HTTP
LockFile	Unary	POST /v1/sessions/{session_id}/files:lock POST /v1/sessions/{session_id}/files/lock
UnlockFile	Unary	POST /v1/sessions/{session_id}/files:unlock POST /v1/sessions/{session_id}/files/unlock
RenewLock	Unary	POST /v1/sessions/{session_id}/files:renewLock POST /v1/sessions/{session_id}/files/renew-lock
ListLocks	Unary	POST /v1/sessions/{session_id}/files:listLocks POST /v1/sessions/{session_id}/files/list-locks
ForceUnlockFile	Unary	POST /v1/sessions/{session_id}/files:forceUnlock POST /v1/sessions/{session_id}/files/force-unlock

LockFile

Acquires an exclusive, temporary lock on a file, preventing other clients from modifying it. This is a pessimistic concurrency control mechanism.

• Signature: LockFile(LockFileRequest) returns (LockFileResponse)
• RPC shape: Unary
• HTTP binding: POST /v1/sessions/{session_id}/files:lock
• HTTP binding: POST /v1/sessions/{session_id}/files/lock

UnlockFile

Releases a previously acquired lock on a file.

• Signature: UnlockFile(UnlockFileRequest) returns (UnlockFileResponse)
• RPC shape: Unary
• HTTP binding: POST /v1/sessions/{session_id}/files:unlock
• HTTP binding: POST /v1/sessions/{session_id}/files/unlock

RenewLock

Refreshes the TTL for an existing lock.

• Signature: RenewLock(RenewLockRequest) returns (RenewLockResponse)
• RPC shape: Unary
• HTTP binding: POST /v1/sessions/{session_id}/files:renewLock
• HTTP binding: POST /v1/sessions/{session_id}/files/renew-lock

ListLocks

Lists active locks for a session.

• Signature: ListLocks(ListLocksRequest) returns (ListLocksResponse)
• RPC shape: Unary
• HTTP binding: POST /v1/sessions/{session_id}/files:listLocks
• HTTP binding: POST /v1/sessions/{session_id}/files/list-locks

ForceUnlockFile

Force unlocks a path-level lock. Intended for admin recovery flows.

• Signature: ForceUnlockFile(ForceUnlockFileRequest) returns (ForceUnlockFileResponse)
• RPC shape: Unary
• HTTP binding: POST /v1/sessions/{session_id}/files:forceUnlock
• HTTP binding: POST /v1/sessions/{session_id}/files/force-unlock

aetherfs.v1.FileSystemService

The FileSystem service provides granular, high-performance APIs for interacting with the files and directories within an active session.

This entire service is part of the supported public gRPC surface.

RPC	Shape	HTTP
ReadFile	Server streaming	gRPC only
StreamFileRange	Server streaming	gRPC only
WriteFile	Client streaming	gRPC only
DeleteFile	Unary	DELETE /v1/sessions/{session_id}/files
CreateDir	Unary	POST /v1/sessions/{session_id}/dirs
RemoveDir	Unary	DELETE /v1/sessions/{session_id}/dirs
Rename	Unary	POST /v1/sessions/{session_id}:rename
GetFileManifest	Unary	GET /v1/sessions/{session_id}/manifest
GetEnvironmentSpec	Unary	GET /v1/sessions/{session_id}/environmentSpec
ExecuteBatch	Unary	POST /v1/sessions/{session_id}:batch POST /v1/sessions/{session_id}/batch
GenerateEnvironmentSpec	Unary	GET /v1/sessions/{session_id}:generateEnvironmentSpec
DownloadSessionAsTarball	Server streaming	gRPC only
SyncChangesFromTarball	Client streaming	gRPC only
ReadSymlink	Unary	GET /v1/sessions/{session_id}/readSymlink
ListSymlinks	Unary	GET /v1/sessions/{session_id}/symlinks
CreateSymlink	Unary	POST /v1/sessions/{session_id}/symlinks
Link	Unary	POST /v1/sessions/{session_id}:link
Unlink	Unary	POST /v1/sessions/{session_id}:unlink
Fallocate	Unary	POST /v1/sessions/{session_id}:fallocate POST /v1/sessions/{session_id}/fallocate
SeekHoleData	Unary	POST /v1/sessions/{session_id}:seekHoleData POST /v1/sessions/{session_id}/seekHoleData
GetCasExtents	Unary	POST /v1/sessions/{session_id}:getCasExtents
PatchSegments	Unary	POST /v1/sessions/{session_id}:patchSegments POST /v1/sessions/{session_id}/patchSegments
GetXattr	Unary	POST /v1/sessions/{session_id}:getXattr
ListXattrs	Unary	POST /v1/sessions/{session_id}:listXattrs
SetXattr	Unary	POST /v1/sessions/{session_id}:setXattr
RemoveXattr	Unary	POST /v1/sessions/{session_id}:removeXattr
GetPosixLock	Unary	POST /v1/sessions/{session_id}:getPosixLock
SetPosixLock	Unary	POST /v1/sessions/{session_id}:setPosixLock
SetPosixLockBlocking	Unary	POST /v1/sessions/{session_id}:setPosixLockBlocking
Flock	Unary	POST /v1/sessions/{session_id}:flock
Funlock	Unary	POST /v1/sessions/{session_id}:funlock

ReadFile

Reads the content of a file. Supports streaming for large files.

• Signature: ReadFile(ReadFileRequest) returns (stream ReadFileResponse)
• RPC shape: Server streaming
• HTTP binding: none; this RPC is gRPC-only.

StreamFileRange

Streams a specific byte range of a file, preferring backend streaming support where available.

• Signature: StreamFileRange(ReadFileRequest) returns (stream ReadFileResponse)
• RPC shape: Server streaming
• HTTP binding: none; this RPC is gRPC-only.

WriteFile

Writes the entire content of a file. Supports streaming for large files. This is a "put" operation that replaces the file if it exists. Implements optimistic concurrency control via expected_hash.

• Signature: WriteFile(stream WriteFileRequest) returns (WriteFileResponse)
• RPC shape: Client streaming
• HTTP binding: none; this RPC is gRPC-only.

DeleteFile

Deletes a file. Implements optimistic concurrency control via expected_hash.

• Signature: DeleteFile(DeleteFileRequest) returns (DeleteFileResponse)
• RPC shape: Unary
• HTTP binding: DELETE /v1/sessions/{session_id}/files

CreateDir

Creates a directory.

• Signature: CreateDir(CreateDirRequest) returns (CreateDirResponse)
• RPC shape: Unary
• HTTP binding: POST /v1/sessions/{session_id}/dirs

RemoveDir

Removes an empty directory.

• Signature: RemoveDir(RemoveDirRequest) returns (RemoveDirResponse)
• RPC shape: Unary
• HTTP binding: DELETE /v1/sessions/{session_id}/dirs

Rename

Renames or moves a file or directory.

• Signature: Rename(RenameRequest) returns (RenameResponse)
• RPC shape: Unary
• HTTP binding: POST /v1/sessions/{session_id}:rename

GetFileManifest

Retrieves a hierarchical manifest of all files and directories in a session. This is the primary mechanism for an agent to discover the filesystem structure.

• Signature: GetFileManifest(GetFileManifestRequest) returns (GetFileManifestResponse)
• RPC shape: Unary
• HTTP binding: GET /v1/sessions/{session_id}/manifest

GetEnvironmentSpec

Retrieves the parsed .agent-env.yml specification for the session. This provides the agent with crucial context about the project's runtime, tasks, and conventions.

• Signature: GetEnvironmentSpec(GetEnvironmentSpecRequest) returns (GetEnvironmentSpecResponse)
• RPC shape: Unary
• HTTP binding: GET /v1/sessions/{session_id}/environmentSpec

ExecuteBatch

Executes a batch of filesystem operations atomically. The entire batch will succeed or fail as a single transaction. This is essential for complex refactoring tasks. Corresponds to "Transactional Operations".

• Signature: ExecuteBatch(ExecuteBatchRequest) returns (ExecuteBatchResponse)
• RPC shape: Unary
• HTTP binding: POST /v1/sessions/{session_id}:batch
• HTTP binding: POST /v1/sessions/{session_id}/batch

GenerateEnvironmentSpec

Analyzes the session's content and suggests a .agent-env.yml specification. This is a convenience method to help bootstrap project configuration.

• Signature: GenerateEnvironmentSpec(GenerateEnvironmentSpecRequest) returns (GenerateEnvironmentSpecResponse)
• RPC shape: Unary
• HTTP binding: GET /v1/sessions/{session_id}:generateEnvironmentSpec

DownloadSessionAsTarball

Downloads a complete, compressed snapshot of the session's merged filesystem view as a gzipped tarball.

• Signature: DownloadSessionAsTarball(DownloadSessionAsTarballRequest) returns (stream DownloadSessionAsTarballResponse)
• RPC shape: Server streaming
• HTTP binding: none; this RPC is gRPC-only.

SyncChangesFromTarball

Applies changes from a gzipped tarball to the session's overlay. This is an atomic operation that uses an epoch for concurrency control.

• Signature: SyncChangesFromTarball(stream SyncChangesFromTarballRequest) returns (SyncChangesFromTarballResponse)
• RPC shape: Client streaming
• HTTP binding: none; this RPC is gRPC-only.

ReadSymlink

Reads the target of a symbolic link.

• Signature: ReadSymlink(ReadSymlinkRequest) returns (ReadSymlinkResponse)
• RPC shape: Unary
• HTTP binding: GET /v1/sessions/{session_id}/readSymlink

ListSymlinks

Lists symlinks under a path prefix, returning their targets.

• Signature: ListSymlinks(ListSymlinksRequest) returns (ListSymlinksResponse)
• RPC shape: Unary
• HTTP binding: GET /v1/sessions/{session_id}/symlinks

CreateSymlink

Creates a symbolic link.

• Signature: CreateSymlink(CreateSymlinkRequest) returns (CreateSymlinkResponse)
• RPC shape: Unary
• HTTP binding: POST /v1/sessions/{session_id}/symlinks

Link

Creates a hard link pointing from dst_path to src_path.

• Signature: Link(LinkRequest) returns (LinkResponse)
• RPC shape: Unary
• HTTP binding: POST /v1/sessions/{session_id}:link

Unlink

Removes a hard link at path. Optionally validates the current hash.

• Signature: Unlink(UnlinkRequest) returns (UnlinkResponse)
• RPC shape: Unary
• HTTP binding: POST /v1/sessions/{session_id}:unlink

Fallocate

Performs sparse allocation or hole punching on a file.

• Signature: Fallocate(FallocateRequest) returns (FallocateResponse)
• RPC shape: Unary
• HTTP binding: POST /v1/sessions/{session_id}:fallocate
• HTTP binding: POST /v1/sessions/{session_id}/fallocate

SeekHoleData

Locates the next hole or data region relative to offset.

• Signature: SeekHoleData(SeekHoleDataRequest) returns (SeekHoleDataResponse)
• RPC shape: Unary
• HTTP binding: POST /v1/sessions/{session_id}:seekHoleData
• HTTP binding: POST /v1/sessions/{session_id}/seekHoleData

GetCasExtents

Retrieves CAS-backed extents for a file so clients can borrow existing segments.

• Signature: GetCasExtents(GetCasExtentsRequest) returns (GetCasExtentsResponse)
• RPC shape: Unary
• HTTP binding: POST /v1/sessions/{session_id}:getCasExtents

PatchSegments

Applies incremental sparse updates using existing CAS segments or inline deltas.

• Signature: PatchSegments(PatchSegmentsRequest) returns (PatchSegmentsResponse)
• RPC shape: Unary
• HTTP binding: POST /v1/sessions/{session_id}:patchSegments
• HTTP binding: POST /v1/sessions/{session_id}/patchSegments

GetXattr

Retrieves the value of an extended attribute for a file.

• Signature: GetXattr(GetXattrRequest) returns (GetXattrResponse)
• RPC shape: Unary
• HTTP binding: POST /v1/sessions/{session_id}:getXattr

ListXattrs

Lists the extended attribute names for a file.

• Signature: ListXattrs(ListXattrsRequest) returns (ListXattrsResponse)
• RPC shape: Unary
• HTTP binding: POST /v1/sessions/{session_id}:listXattrs

SetXattr

Sets or replaces an extended attribute for a file.

• Signature: SetXattr(SetXattrRequest) returns (SetXattrResponse)
• RPC shape: Unary
• HTTP binding: POST /v1/sessions/{session_id}:setXattr

RemoveXattr

Removes an extended attribute from a file.

• Signature: RemoveXattr(RemoveXattrRequest) returns (RemoveXattrResponse)
• RPC shape: Unary
• HTTP binding: POST /v1/sessions/{session_id}:removeXattr

GetPosixLock

POSIX lock inspection (F_GETLK). Returns details about a conflicting lock if one exists.

• Signature: GetPosixLock(GetPosixLockRequest) returns (GetPosixLockResponse)
• RPC shape: Unary
• HTTP binding: POST /v1/sessions/{session_id}:getPosixLock

SetPosixLock

POSIX F_SETLK (non-blocking).

• Signature: SetPosixLock(SetPosixLockRequest) returns (SetPosixLockResponse)
• RPC shape: Unary
• HTTP binding: POST /v1/sessions/{session_id}:setPosixLock

SetPosixLockBlocking

POSIX F_SETLKW (blocking until the lock can be granted).

• Signature: SetPosixLockBlocking(SetPosixLockBlockingRequest) returns (SetPosixLockBlockingResponse)
• RPC shape: Unary
• HTTP binding: POST /v1/sessions/{session_id}:setPosixLockBlocking

Flock

POSIX flock covering the entire file.

• Signature: Flock(FlockRequest) returns (FlockResponse)
• RPC shape: Unary
• HTTP binding: POST /v1/sessions/{session_id}:flock

Funlock

POSIX unlock covering the provided range or entire file.

• Signature: Funlock(FunlockRequest) returns (FunlockResponse)
• RPC shape: Unary
• HTTP binding: POST /v1/sessions/{session_id}:funlock

aetherfs.v1.HealthService

Service for reporting and querying the health status of a session, primarily based on test results. This is part of Category 5.

This entire service is part of the supported public gRPC surface.

RPC	Shape	HTTP
GetSessionHealth	Unary	GET /v1/sessions/{session_id}/health
ReportTestResults	Unary	POST /v1/sessions/{session_id}/health:testResults POST /v1/sessions/{session_id}/health/report

GetSessionHealth

Returns the currently stored health snapshot for a session.

• Signature: GetSessionHealth(GetSessionHealthRequest) returns (GetSessionHealthResponse)
• RPC shape: Unary
• HTTP binding: GET /v1/sessions/{session_id}/health

ReportTestResults

Allows an agent to report the results of a test run from its local execution environment. The platform parses this report, updates the session's health status, and broadcasts the change on the message bus.

• Signature: ReportTestResults(ReportTestResultsRequest) returns (ReportTestResultsResponse)
• RPC shape: Unary
• HTTP binding: POST /v1/sessions/{session_id}/health:testResults
• HTTP binding: POST /v1/sessions/{session_id}/health/report

aetherfs.v1.KnowledgeCacheService

The KnowledgeCacheService provides a simple, ephemeral key-value store scoped to each session, acting as an agent's short-term memory.

This entire service is part of the supported public gRPC surface.

RPC	Shape	HTTP
GetCacheEntry	Unary	GET /v1/sessions/{session_id}/cache/{key}
ExistsCacheEntry	Unary	GET /v1/sessions/{session_id}/cache/{key}:exists GET /v1/sessions/{session_id}/cache/{key}/exists
GetCacheEntryMetadata	Unary	GET /v1/sessions/{session_id}/cache/{key}:metadata GET /v1/sessions/{session_id}/cache/{key}/metadata
SetCacheEntry	Unary	PUT /v1/sessions/{session_id}/cache/{key}
BatchGetCacheEntries	Unary	POST /v1/sessions/{session_id}/cache:batchGet POST /v1/sessions/{session_id}/cache/batch-get
ListCacheKeys	Unary	GET /v1/sessions/{session_id}/cache:keys GET /v1/sessions/{session_id}/cache/keys
BatchSetCacheEntries	Unary	POST /v1/sessions/{session_id}/cache:batchSet POST /v1/sessions/{session_id}/cache/batch-set
CompareAndSetCacheEntry	Unary	POST /v1/sessions/{session_id}/cache/{key}:compareAndSet POST /v1/sessions/{session_id}/cache/{key}/compare-and-set
DeleteCacheEntry	Unary	DELETE /v1/sessions/{session_id}/cache/{key}
BatchDeleteCacheEntries	Unary	POST /v1/sessions/{session_id}/cache:batchDelete POST /v1/sessions/{session_id}/cache/batch-delete
DeleteCacheEntriesByPrefix	Unary	POST /v1/sessions/{session_id}/cache:deleteByPrefix POST /v1/sessions/{session_id}/cache/delete-by-prefix
GetCacheStats	Unary	GET /v1/sessions/{session_id}/cache:stats GET /v1/sessions/{session_id}/cache/stats

GetCacheEntry

Retrieves a value from the cache.

• Signature: GetCacheEntry(GetCacheEntryRequest) returns (GetCacheEntryResponse)
• RPC shape: Unary
• HTTP binding: GET /v1/sessions/{session_id}/cache/{key}

ExistsCacheEntry

Checks whether a key currently exists in the cache.

• Signature: ExistsCacheEntry(ExistsCacheEntryRequest) returns (ExistsCacheEntryResponse)
• RPC shape: Unary
• HTTP binding: GET /v1/sessions/{session_id}/cache/{key}:exists
• HTTP binding: GET /v1/sessions/{session_id}/cache/{key}/exists

GetCacheEntryMetadata

Returns metadata for a key, including version and expiry hints.

• Signature: GetCacheEntryMetadata(GetCacheEntryMetadataRequest) returns (GetCacheEntryMetadataResponse)
• RPC shape: Unary
• HTTP binding: GET /v1/sessions/{session_id}/cache/{key}:metadata
• HTTP binding: GET /v1/sessions/{session_id}/cache/{key}/metadata

SetCacheEntry

Sets a value in the cache, with an optional time-to-live.

• Signature: SetCacheEntry(SetCacheEntryRequest) returns (SetCacheEntryResponse)
• RPC shape: Unary
• HTTP binding: PUT /v1/sessions/{session_id}/cache/{key}

BatchGetCacheEntries

Retrieves many keys from the cache in one call.

• Signature: BatchGetCacheEntries(BatchGetCacheEntriesRequest) returns (BatchGetCacheEntriesResponse)
• RPC shape: Unary
• HTTP binding: POST /v1/sessions/{session_id}/cache:batchGet
• HTTP binding: POST /v1/sessions/{session_id}/cache/batch-get

ListCacheKeys

Lists cache keys with optional prefix filtering.

• Signature: ListCacheKeys(ListCacheKeysRequest) returns (ListCacheKeysResponse)
• RPC shape: Unary
• HTTP binding: GET /v1/sessions/{session_id}/cache:keys
• HTTP binding: GET /v1/sessions/{session_id}/cache/keys

BatchSetCacheEntries

Sets many keys in the cache in one call.

• Signature: BatchSetCacheEntries(BatchSetCacheEntriesRequest) returns (BatchSetCacheEntriesResponse)
• RPC shape: Unary
• HTTP binding: POST /v1/sessions/{session_id}/cache:batchSet
• HTTP binding: POST /v1/sessions/{session_id}/cache/batch-set

CompareAndSetCacheEntry

Conditionally updates a key when the expected revision matches.

• Signature: CompareAndSetCacheEntry(CompareAndSetCacheEntryRequest) returns (CompareAndSetCacheEntryResponse)
• RPC shape: Unary
• HTTP binding: POST /v1/sessions/{session_id}/cache/{key}:compareAndSet
• HTTP binding: POST /v1/sessions/{session_id}/cache/{key}/compare-and-set

DeleteCacheEntry

Deletes a value from the cache.

• Signature: DeleteCacheEntry(DeleteCacheEntryRequest) returns (DeleteCacheEntryResponse)
• RPC shape: Unary
• HTTP binding: DELETE /v1/sessions/{session_id}/cache/{key}

BatchDeleteCacheEntries

Deletes many keys from the cache in one call.

• Signature: BatchDeleteCacheEntries(BatchDeleteCacheEntriesRequest) returns (BatchDeleteCacheEntriesResponse)
• RPC shape: Unary
• HTTP binding: POST /v1/sessions/{session_id}/cache:batchDelete
• HTTP binding: POST /v1/sessions/{session_id}/cache/batch-delete

DeleteCacheEntriesByPrefix

Deletes all keys starting with the provided prefix.

• Signature: DeleteCacheEntriesByPrefix(DeleteCacheEntriesByPrefixRequest) returns (DeleteCacheEntriesByPrefixResponse)
• RPC shape: Unary
• HTTP binding: POST /v1/sessions/{session_id}/cache:deleteByPrefix
• HTTP binding: POST /v1/sessions/{session_id}/cache/delete-by-prefix

GetCacheStats

Returns cache-level statistics for a session.

• Signature: GetCacheStats(GetCacheStatsRequest) returns (GetCacheStatsResponse)
• RPC shape: Unary
• HTTP binding: GET /v1/sessions/{session_id}/cache:stats
• HTTP binding: GET /v1/sessions/{session_id}/cache/stats

aetherfs.v1.MessageBusService

The service definition for real-time, session-scoped agent communication. This is the core of Category 5: Agent Collaboration & Communication.

This entire service is part of the supported public gRPC surface.

RPC	Shape	HTTP
Publish	Unary	POST /v1/sessions/{session_id}/bus:publish
Subscribe	Server streaming	GET /v1/sessions/{session_id}/bus

Publish

Publishes a message to a specific topic within a session. This is a fire-and-forget, one-to-many broadcast operation.

• Signature: Publish(PublishRequest) returns (PublishResponse)
• RPC shape: Unary
• HTTP binding: POST /v1/sessions/{session_id}/bus:publish

Subscribe

Subscribes to one or more topics to receive a real-time stream of messages. This is a long-lived, server-streaming RPC. The client must maintain the connection to receive messages.

• Signature: Subscribe(SubscribeRequest) returns (stream Message)
• RPC shape: Server streaming
• HTTP binding: GET /v1/sessions/{session_id}/bus

aetherfs.v1.ObservabilityService

ObservabilityService exposes the immutable event log for sessions, enabling high-fidelity auditing and replay.

This entire service is part of the supported public gRPC surface.

RPC	Shape	HTTP
GetEventLog	Unary	GET /v1/sessions/{session_id}/events
GetCasStats	Unary	GET /v1/metrics/cas
GetCasRefcounts	Unary	GET /v1/metrics/cas/refcounts

GetEventLog

Retrieves the immutable event log for a session. This provides a reproducible audit trail of every state change.

• Signature: GetEventLog(GetEventLogRequest) returns (GetEventLogResponse)
• RPC shape: Unary
• HTTP binding: GET /v1/sessions/{session_id}/events

GetCasStats

Returns runtime statistics for the Content-Addressable Store (CAS). This is useful for monitoring cache health and sizing.

• Signature: GetCasStats(GetCasStatsRequest) returns (GetCasStatsResponse)
• RPC shape: Unary
• HTTP binding: GET /v1/metrics/cas

GetCasRefcounts

Returns per-key refcounts for the CAS. Intended for diagnostics.

• Signature: GetCasRefcounts(GetCasRefcountsRequest) returns (GetCasRefcountsResponse)
• RPC shape: Unary
• HTTP binding: GET /v1/metrics/cas/refcounts

aetherfs.v1.OversightService

The OversightService provides mechanisms for agents to request human intervention and for operators to grant or deny those requests. This is the core of Category 6: Human Interaction & Oversight.

This entire service is part of the supported public gRPC surface.

RPC	Shape	HTTP
RequestApproval	Unary	POST /v1/sessions/{session_id}:requestApproval POST /v1/sessions/{session_id}/request-approval
GrantApproval	Unary	POST /v1/sessions/{session_id}/approvals/{approval_id}:grant POST /v1/sessions/{session_id}/approvals/{approval_id}/grant
DenyApproval	Unary	POST /v1/sessions/{session_id}/approvals/{approval_id}:deny POST /v1/sessions/{session_id}/approvals/{approval_id}/deny

RequestApproval

An agent calls this to voluntarily pause its execution and request explicit permission before proceeding with a critical action. This atomically transitions the session state to PENDING_APPROVAL.

• Signature: RequestApproval(RequestApprovalRequest) returns (RequestApprovalResponse)
• RPC shape: Unary
• HTTP binding: POST /v1/sessions/{session_id}:requestApproval
• HTTP binding: POST /v1/sessions/{session_id}/request-approval

GrantApproval

Grants a pending approval request, transitioning the session back to ACTIVE.

• Signature: GrantApproval(GrantApprovalRequest) returns (GrantApprovalResponse)
• RPC shape: Unary
• HTTP binding: POST /v1/sessions/{session_id}/approvals/{approval_id}:grant
• HTTP binding: POST /v1/sessions/{session_id}/approvals/{approval_id}/grant

DenyApproval

Denies a pending approval request, transitioning the session back to ACTIVE and providing feedback to the agent.

• Signature: DenyApproval(DenyApprovalRequest) returns (DenyApprovalResponse)
• RPC shape: Unary
• HTTP binding: POST /v1/sessions/{session_id}/approvals/{approval_id}:deny
• HTTP binding: POST /v1/sessions/{session_id}/approvals/{approval_id}/deny

aetherfs.v1.PersistenceService

The PersistenceService provides methods for making an ephemeral session's state durable. It abstracts the specific storage destinations (e.g., Git, S3) behind a unified API.

This entire service is part of the supported public gRPC surface.

RPC	Shape	HTTP
CommitSession	Unary	POST /v1/sessions/{session_id}:commit POST /v1/sessions/{session_id}/commit
GenerateCommitSummary	Unary	GET /v1/sessions/{session_id}:generateCommitSummary GET /v1/sessions/{session_id}/generateCommitSummary

CommitSession

Commits the current state of a session's overlay to a durable storage target. This is the primary mechanism for saving an agent's work.

• Signature: CommitSession(CommitSessionRequest) returns (CommitSessionResponse)
• RPC shape: Unary
• HTTP binding: POST /v1/sessions/{session_id}:commit
• HTTP binding: POST /v1/sessions/{session_id}/commit

GenerateCommitSummary

Analyzes the changes in a session and generates a suggested commit message following the Conventional Commits specification.

• Signature: GenerateCommitSummary(GenerateCommitSummaryRequest) returns (GenerateCommitSummaryResponse)
• RPC shape: Unary
• HTTP binding: GET /v1/sessions/{session_id}:generateCommitSummary
• HTTP binding: GET /v1/sessions/{session_id}/generateCommitSummary

aetherfs.v1.SecretsService

SecretsService provides secure retrieval of secrets without ever persisting them in the session's filesystem overlay.

This entire service is part of the supported public gRPC surface.

RPC	Shape	HTTP
GetSecret	Unary	GET /v1/sessions/{session_id}/secrets/{secret_name}
SetSecret	Unary	PUT /v1/sessions/{session_id}/secrets/{secret_name}
DeleteSecret	Unary	DELETE /v1/sessions/{session_id}/secrets/{secret_name}
ListSecrets	Unary	GET /v1/sessions/{session_id}/secrets

GetSecret

Retrieves a secret by name. The value is held only in memory and should never be written to the session's overlay filesystem.

• Signature: GetSecret(GetSecretRequest) returns (GetSecretResponse)
• RPC shape: Unary
• HTTP binding: GET /v1/sessions/{session_id}/secrets/{secret_name}

SetSecret

Creates or updates a secret in the selected scope.

• Signature: SetSecret(SetSecretRequest) returns (SetSecretResponse)
• RPC shape: Unary
• HTTP binding: PUT /v1/sessions/{session_id}/secrets/{secret_name}

DeleteSecret

Deletes a secret in the selected scope.

• Signature: DeleteSecret(DeleteSecretRequest) returns (DeleteSecretResponse)
• RPC shape: Unary
• HTTP binding: DELETE /v1/sessions/{session_id}/secrets/{secret_name}

ListSecrets

Lists secret names visible from the current tenant/session context.

• Signature: ListSecrets(ListSecretsRequest) returns (ListSecretsResponse)
• RPC shape: Unary
• HTTP binding: GET /v1/sessions/{session_id}/secrets

aetherfs.v1.SessionService

The core Session Management service. This is the primary entry point for agents to create and manage their workspaces.

This entire service is part of the supported public gRPC surface.

RPC	Shape	HTTP
CreateSession	Unary	POST /v1/sessions
GetSession	Unary	GET /v1/sessions/{session_id}
DeleteSession	Unary	DELETE /v1/sessions/{session_id}
CreateCheckpoint	Unary	POST /v1/sessions/{session_id}/checkpoints
RestoreCheckpoint	Unary	POST /v1/sessions/{session_id}:restore POST /v1/sessions/{session_id}/restore
ForkSession	Unary	POST /v1/sessions/{source_session_id}:fork POST /v1/sessions/{source_session_id}/fork
MergeChildSession	Unary	POST /v1/sessions/{parent_session_id}:merge
MergeSession	Unary	POST /v1/sessions/{target_session_id}:mergeFrom
TagSession	Unary	PATCH /v1/sessions/{session_id}/tags
ListSessions	Unary	GET /v1/sessions

CreateSession

Creates a new, isolated session for an agent to work in. This is the main provisioning step, defining the session's source, boundaries, and metadata. Corresponds to "Rich Session Creation".

• Signature: CreateSession(CreateSessionRequest) returns (Session)
• RPC shape: Unary
• HTTP binding: POST /v1/sessions

GetSession

Retrieves the current state and metadata of a session.

• Signature: GetSession(GetSessionRequest) returns (Session)
• RPC shape: Unary
• HTTP binding: GET /v1/sessions/{session_id}

DeleteSession

Deletes a session and releases all its resources. The in-memory overlay is immediately deallocated.

• Signature: DeleteSession(DeleteSessionRequest) returns (DeleteSessionResponse)
• RPC shape: Unary
• HTTP binding: DELETE /v1/sessions/{session_id}

CreateCheckpoint

Creates an immutable, named snapshot of the session's current state. Corresponds to "Session Checkpoints".

• Signature: CreateCheckpoint(CreateCheckpointRequest) returns (Checkpoint)
• RPC shape: Unary
• HTTP binding: POST /v1/sessions/{session_id}/checkpoints

RestoreCheckpoint

Reverts a session's overlay to a previously created checkpoint.

• Signature: RestoreCheckpoint(RestoreCheckpointRequest) returns (Session)
• RPC shape: Unary
• HTTP binding: POST /v1/sessions/{session_id}:restore
• HTTP binding: POST /v1/sessions/{session_id}/restore

ForkSession

Efficiently creates a new, independent session from an existing one. This is a low-cost, copy-on-write operation enabling parallel experimentation. Corresponds to "Session Forking".

• Signature: ForkSession(ForkSessionRequest) returns (Session)
• RPC shape: Unary
• HTTP binding: POST /v1/sessions/{source_session_id}:fork
• HTTP binding: POST /v1/sessions/{source_session_id}/fork

MergeChildSession

Merges the changes from a child session into its parent. This operation is transactional and will fail if there are any conflicts (i.e., if both the parent and child have modified the same file since the fork). Corresponds to "Hierarchical Session Merging".

• Signature: MergeChildSession(MergeChildSessionRequest) returns (Session)
• RPC shape: Unary
• HTTP binding: POST /v1/sessions/{parent_session_id}:merge

MergeSession

Merges the changes from a source session into the target session. This is a peer-to-peer merge, more general than MergeChildSession.

• Signature: MergeSession(MergeSessionRequest) returns (Session)
• RPC shape: Unary
• HTTP binding: POST /v1/sessions/{target_session_id}:mergeFrom

TagSession

Attaches or updates metadata tags for a session. Corresponds to "Session Tagging and Querying".

• Signature: TagSession(TagSessionRequest) returns (Session)
• RPC shape: Unary
• HTTP binding: PATCH /v1/sessions/{session_id}/tags

ListSessions

Lists and filters sessions using boolean expressions over metadata.

• Signature: ListSessions(ListSessionsRequest) returns (ListSessionsResponse)
• RPC shape: Unary
• HTTP binding: GET /v1/sessions

aetherfs.v1.ToolingService

The ToolingService exposes session-scoped developer tools against a session's merged filesystem view.

This entire service is part of the supported public gRPC surface.

RPC	Shape	HTTP
ListTools	Unary	GET /v1/sessions/{session_id}/tools
InvokeTool	Unary	POST /v1/sessions/{session_id}/tools:invoke

ListTools

Lists the tools available for a session.

• Signature: ListTools(ListToolsRequest) returns (ListToolsResponse)
• RPC shape: Unary
• HTTP binding: GET /v1/sessions/{session_id}/tools

InvokeTool

Invokes a tool against the session.

• Signature: InvokeTool(InvokeToolRequest) returns (InvokeToolResponse)
• RPC shape: Unary
• HTTP binding: POST /v1/sessions/{session_id}/tools:invoke

aetherfs.v1.UnderlaySourceService

UnderlaySourceService manages tenant-owned underlay source definitions and import job lifecycles.

This entire service is part of the supported public gRPC surface.

RPC	Shape	HTTP
CreateSource	Unary	POST /v1/sources
GetSource	Unary	GET /v1/sources/{source_id}
ListSources	Unary	GET /v1/sources
DeleteSource	Unary	DELETE /v1/sources/{source_id}
StartSourceImport	Unary	POST /v1/sources/{source_id}:startImport POST /v1/sources/{source_id}/startImport
GetSourceImportJob	Unary	GET /v1/sources/{source_id}/jobs/{job_id}
UploadSourceArchive	Client streaming	gRPC only
RefreshSource	Unary	POST /v1/sources/{source_id}:refresh POST /v1/sources/{source_id}/refresh
PromoteSessionToSource	Unary	POST /v1/sources/{source_id}:promoteSession POST /v1/sources/{source_id}/promoteSession

CreateSource

• Signature: CreateSource(CreateSourceRequest) returns (UnderlaySource)
• RPC shape: Unary
• HTTP binding: POST /v1/sources

GetSource

• Signature: GetSource(GetSourceRequest) returns (UnderlaySource)
• RPC shape: Unary
• HTTP binding: GET /v1/sources/{source_id}

ListSources

• Signature: ListSources(ListSourcesRequest) returns (ListSourcesResponse)
• RPC shape: Unary
• HTTP binding: GET /v1/sources

DeleteSource

• Signature: DeleteSource(DeleteSourceRequest) returns (DeleteSourceResponse)
• RPC shape: Unary
• HTTP binding: DELETE /v1/sources/{source_id}

StartSourceImport

• Signature: StartSourceImport(StartSourceImportRequest) returns (UnderlayImportJob)
• RPC shape: Unary
• HTTP binding: POST /v1/sources/{source_id}:startImport
• HTTP binding: POST /v1/sources/{source_id}/startImport

GetSourceImportJob

• Signature: GetSourceImportJob(GetSourceImportJobRequest) returns (UnderlayImportJob)
• RPC shape: Unary
• HTTP binding: GET /v1/sources/{source_id}/jobs/{job_id}

UploadSourceArchive

• Signature: UploadSourceArchive(stream UploadSourceArchiveRequest) returns (UploadSourceArchiveResponse)
• RPC shape: Client streaming
• HTTP binding: none; this RPC is gRPC-only.

RefreshSource

• Signature: RefreshSource(RefreshSourceRequest) returns (UnderlayImportJob)
• RPC shape: Unary
• HTTP binding: POST /v1/sources/{source_id}:refresh
• HTTP binding: POST /v1/sources/{source_id}/refresh

PromoteSessionToSource

• Signature: PromoteSessionToSource(PromoteSessionToSourceRequest) returns (UnderlayImportJob)
• RPC shape: Unary
• HTTP binding: POST /v1/sources/{source_id}:promoteSession
• HTTP binding: POST /v1/sources/{source_id}/promoteSession

aetherfs.v1.UsageService

UsageService exposes tenant-scoped usage aggregates for billing and visibility across both gRPC and HTTP transports.

This entire service is part of the supported public gRPC surface.

RPC	Shape	HTTP
GetUsage	Unary	GET /v1/usage

GetUsage

Returns usage aggregates for the authenticated tenant over a requested time window.

• Signature: GetUsage(GetUsageRequest) returns (GetUsageResponse)
• RPC shape: Unary
• HTTP binding: GET /v1/usage