Skip to main content

Common workflows

Build an agent or session runner​

Typical gRPC flow:

  1. Call SessionService.CreateSession.
  2. Call FileSystemService.GetFileManifest to discover structure.
  3. Stream or range-read the files you actually need with ReadFile or StreamFileRange.
  4. Apply mutations with WriteFile, PatchSegments, ExecuteBatch, and related filesystem RPCs.
  5. Report health with HealthService.ReportTestResults.
  6. Publish runtime events with MessageBusService.Publish if your system emits session-scoped status.
  7. Request human approval with OversightService.RequestApproval when your workflow needs a decision gate.
  8. Persist the result with PersistenceService.CommitSession.

This is the strongest fit for gRPC because it combines typed control RPCs with streaming file access.

Build a reviewer or oversight surface​

Typical gRPC flow:

  1. Read session state with SessionService.GetSession.
  2. Load structure with FileSystemService.GetFileManifest.
  3. Read annotations with AnnotationService.GetAnnotations.
  4. Read health with HealthService.GetSessionHealth.
  5. Read immutable history with ObservabilityService.GetEventLog.
  6. Grant or deny approvals with OversightService.GrantApproval and OversightService.DenyApproval.

This is a mixed case. Many teams may choose HTTP here, but gRPC is still reasonable if your reviewer product is a server-side integration rather than a browser-only app.

Build a low-latency file integration​

Typical gRPC flow:

  1. Discover files with GetFileManifest.
  2. Use ReadFile or StreamFileRange for reads.
  3. Use WriteFile for full-content replacement writes.
  4. Use PatchSegments or GetCasExtents when you need sparse or CAS-aware flows.
  5. Use GetXattr, SetXattr, lock RPCs, symlink RPCs, or batch mutations when the integration needs filesystem semantics beyond plain read and write.

This is where gRPC is materially better than a JSON gateway.

Manage reusable sources and imports​

Typical gRPC flow:

  1. Create a source with UnderlaySourceService.CreateSource.
  2. Start import with StartSourceImport or stream archive data with UploadSourceArchive.
  3. Poll job state with GetSourceImportJob.
  4. Refresh an existing source with RefreshSource.
  5. Promote a prepared session into a managed source with PromoteSessionToSource.

This is about source import, refresh, and promotion workflows, not generic source control. The archive-upload path is especially gRPC-friendly because it is client-streaming.

Build usage or analytics reporting​

Typical gRPC flow:

  1. Read tenant usage with UsageService.GetUsage.
  2. Read per-session analytics with AnalyticsService.GetSessionAnalytics.
  3. Correlate with session state, health, and event-log reads when needed.

When to pick HTTP instead​

Pick the HTTP surface instead if:

  • you need browser-first JSON calls
  • you want the OpenAPI explorer as the main reference
  • your integration does not benefit from streams
  • you are primarily wiring control-plane forms and dashboards

Pick gRPC when the integration is service-to-service, typed, or stream-heavy.