Skip to content

feat: add stable Forward and Managed API operations #7

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
moonyue-w merged 1 commit into from
Oct 9, 2026
Merged

feat: add stable Forward and Managed API operations #7

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,12 @@ existing `0.1.0` release; earlier development prereleases are not listed.

## [Unreleased]

### Added

- Forward Vault Credential updates for secret rotation and metadata merge patches, with automatic retries disabled for write-only updates.
- Forward Usage aggregation by Identity and Template using hourly `start_at` / `end_at` windows in Asia/Shanghai, with fractional `active_seconds` and multi-ID filters. Legacy timestamp parameters are not exposed.
- Managed Session cancellation with the lightweight acknowledgement for both active and idle sessions, plus deployment-scoped Run listing and retrieval.

## [0.2.0] - 2026-09-24

### Changed
Expand Down
14 changes: 14 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,20 @@ go build ./examples/...

Never commit `.env.live`, tokens, credentials, generated logs, or test output. Live tests must register cleanup immediately after creating a resource.

`make test-live-all` includes Forward hourly Usage, Credential merge patches
and secret redaction, and Managed Session cancellation before and after sending
a turn. Managed deployment tests cover scoped Run listing/retrieval. Active
cancellation and scoped Run execution require the corresponding
`LIVE_ALLOW_WRITE=true` and `LIVE_ALLOW_EXECUTION=true` gates. Use a separate
`LIVE_ENV_FILE` with matching URL and PAT for CN and Global.

Usage queries the last 24 completed whole hours in Asia/Shanghai in both regions;
empty pages verify only the collection. A Session may finish before cancellation
and return HTTP 200 instead of 202; tests record which response occurred. Those
responses do not prove active cancellation occurred. Cleanup failures remain
failures; offline replay exercises assertions and cleanup without account
credentials.

## API and contract changes

When adding or changing an endpoint:
Expand Down
37 changes: 36 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,12 +8,13 @@ The SDK ships two clients that share authentication, transport, retries, error h

| Mode | Package | Resources |
| --- | --- | --- |
| Forward | `forward` | Identity, Template, Session, Schedule, Batch, Channel, Environment, File, Skill, Vault, MemoryStore, Model |
| Forward | `forward` | Identity, Template, Session, Schedule, Batch, Channel, Environment, File, Skill, Vault, MemoryStore, Model, Usage |
| Managed | `managed` | Agent, Session, Deployment, Dream, Environment, File, Skill, Vault, MemoryStore, Model |

- [Installation](#installation)
- [Requirements](#requirements)
- [Usage](#usage)
- [Usage and cancellation](#usage-and-cancellation)
- [Conversations](#conversations)
- [System prompts and tools](#system-prompts-and-tools)
- [Streaming](#streaming)
Expand Down Expand Up @@ -115,6 +116,40 @@ The remaining examples are function fragments meant to be dropped into an applic
| `option` | `github.com/QoderAI/qoder-cloud-agents-sdk-go/convention/option` |
| `param` | `github.com/QoderAI/qoder-cloud-agents-sdk-go/convention/param` |

## Usage and cancellation

Forward Usage requires PAT or Admin SAT.

```go
usage, err := client.Usage.ListIdentities(ctx, forward.UsageListParams{
StartAt: "2026-09-14T09:00:00",
EndAt: "2026-09-14T12:00:00",
IdentityIDs: []string{"idn_one", "idn_two"},
})
if err != nil {
return err
}
for _, item := range usage.Data {
fmt.Println(item.IdentityID, item.ActiveSeconds, item.Credits)
}
```

`Usage.ListTemplates` uses the same filters. Both bounds are whole hours in
Asia/Shanghai, including Global: the start is inclusive, the end exclusive, and
the maximum window is 744 hours. Use `ActiveSeconds` without truncating fractions.
Legacy `start_time`, `end_time`, and `duration_seconds` are not exposed.

Rotate Forward secrets with `client.Vaults.Credentials.Update`; only `auth` and
`metadata` are patched, and omitted fields are preserved. Use
`param.NullMap[map[string]any]()` to clear metadata, or a map value of `nil` to remove
a key. Updates never retry automatically; secret values are not returned by GET.

Managed adds `client.Sessions.Cancel(ctx, sessionID, managed.SessionCancelParams{})`,
which returns a lightweight `canceling` acknowledgement (HTTP 202 for active work,
200 for an idle no-op). It also exposes `client.Deployments.Runs.List` and `Get`,
with the deployment ID as a path argument; the existing global `DeploymentRuns`
resource remains available.

## Conversations

Forward creates a Session from an Identity and a Template. The fragments below assume both already exist, with a usable execution environment configured on the Template; [the Forward session example](examples/forward/session/main.go) shows how to create them.
Expand Down
Loading
Loading