You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 2900b06
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: README.md
+1Lines changed: 1 addition & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -321,6 +321,7 @@ stream completion.
321
321
| File transfer API (transport capability-gated) |`FileInterface`|[Files](https://ai-openshell.github.io/sdk-go/api/files.html)|
| Gateway info and current user identity |`HealthInterface`|[Health](https://ai-openshell.github.io/sdk-go/api/health.html)|
Copy file name to clipboardExpand all lines: docs/src/api/sandboxes.md
+77Lines changed: 77 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -264,6 +264,83 @@ for event := range watcher.ResultChan() {
264
264
// Channel closes after Ready or Error
265
265
```
266
266
267
+
## WatchLogs
268
+
269
+
Streams a sandbox's log lines and platform events with loss-aware resume. Returns a `WatchInterface[*WatchLogEvent]`.
270
+
271
+
`WatchLogs` lives on the optional `SandboxLogsWatchInterface`, reached through `client.SandboxLogsWatch()`, so `SandboxInterface` stays unchanged for existing mocks and wrappers.
272
+
273
+
Each delivered item carries an opaque `Cursor`. The watcher tracks the highest cursor it has seen, reconnects transparently when the stream drops, and asks the gateway to replay only what follows that cursor, so a reconnect neither loses nor duplicates events. The gateway delivers live log and platform events in cursor order across both sources, which is what makes the highest cursor a safe resume point.
274
+
275
+
Only gRPC `Unavailable` (a dropped connection or gateway restart) is retried, with exponential backoff from 100ms capped at 2s, and it is retried indefinitely. Nothing is emitted while the watcher reconnects, so a gateway that stays down looks the same as a quiet sandbox. Bound the watch with a context deadline, or call `Stop`, when that matters. This differs from `Watch`, which reports `Unavailable` as an `EventError` immediately. Every other error ends the stream with an `EventError`.
276
+
277
+
Every `Event[*WatchLogEvent]` has `Type``EventAdded`, except a terminal failure, which arrives as `EventError` with `Err` set and no `Object`. The `Object.Kind` field selects the populated payload:
278
+
279
+
| Kind | Payload | Meaning |
280
+
|------|---------|---------|
281
+
|`WatchLogKindLog`|`Log *LogLine`| A log line |
282
+
|`WatchLogKindEvent`|`Event *PlatformEvent`| A runtime event from the compute backend |
283
+
|`WatchLogKindWarning`|`Warning string`| Recoverable loss — the server skipped ahead after a lag and the stream continues |
284
+
285
+
**Available options** (`WatchLogsOptions`):
286
+
287
+
| Field | Description |
288
+
|-------|-------------|
289
+
|`FollowLogs bool`| Stream log lines. Defaults to true when neither follow flag is set |
Loss is never silent. A recoverable gap arrives as a `WatchLogKindWarning` item and the stream continues. An unrecoverable gap ends the stream with an `EventError` carrying `ErrorOutOfRange`: the resume point is gone, so the events after it cannot be replayed. The SDK does not retry that error, because restarting from the tail would hide the loss. To continue anyway, start a new watch with an empty `ResumeAfterCursor`; retrying the same cursor fails identically.
332
+
333
+
Persist the highest cursor to resume across process restarts:
Cursors are opaque. Do not parse or construct one. The only supported operation is comparing two cursors observed on the same stream and keeping the greater one.
343
+
267
344
## GetLogs
268
345
269
346
Retrieves log entries from a sandbox. The sandbox is looked up by name (the SDK resolves the name to an internal ID automatically). Use functional options to filter results.
|`v1.IsDeadlineExceeded`|`ErrorDeadlineExceeded`| Operation timed out |
44
44
|`v1.IsCancelled`|`ErrorCancelled`| Operation was cancelled (context cancellation) |
45
+
|`v1.IsOutOfRange`|`ErrorOutOfRange`| Operation attempted past a valid range (gRPC `OUT_OF_RANGE`). On `WatchLogs`, the resume cursor is gone and the events after it are unrecoverable |
46
+
47
+
gRPC `OUT_OF_RANGE` maps to `ErrorOutOfRange` on every RPC. Earlier releases mapped it to `ErrorInvalidArgument`, so code that matched `IsInvalidArgument` for an out-of-range result should match `IsOutOfRange` instead.
45
48
46
49
For `ErrorInternal` (server-side errors), no convenience predicate exists. Match it directly via the `Code` field:
0 commit comments