@opengeni/runtime 4.3.0 → 4.4.0-canary.36927100590001
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/agent-instructions/base-behavior.d.ts +8 -0
- package/dist/agent-instructions/compose.d.ts +59 -0
- package/dist/agent-instructions/identity.d.ts +21 -0
- package/dist/agent-instructions/index.d.ts +6 -0
- package/dist/agent-instructions/modules/admin.d.ts +3 -0
- package/dist/agent-instructions/modules/artifacts.d.ts +7 -0
- package/dist/agent-instructions/modules/attachments.d.ts +3 -0
- package/dist/agent-instructions/modules/environment.d.ts +11 -0
- package/dist/agent-instructions/modules/goals.d.ts +3 -0
- package/dist/agent-instructions/modules/knowledge.d.ts +6 -0
- package/dist/agent-instructions/modules/machines.d.ts +3 -0
- package/dist/agent-instructions/modules/renderer-markdown.d.ts +6 -0
- package/dist/agent-instructions/modules/repositories.d.ts +7 -0
- package/dist/agent-instructions/modules/sandbox.d.ts +3 -0
- package/dist/agent-instructions/modules/skills.d.ts +3 -0
- package/dist/agent-instructions/modules/subagents.d.ts +3 -0
- package/dist/agent-instructions/runtime-mechanics.d.ts +7 -0
- package/dist/agent-instructions/types.d.ts +55 -0
- package/dist/assets/codemode-client.json +1 -1
- package/dist/{chunk-JUFVYQCY.js → chunk-VDXKKMMD.js} +457 -165
- package/dist/chunk-VDXKKMMD.js.map +1 -0
- package/dist/{chunk-22M75RJF.js → chunk-ZY655LYR.js} +1636 -709
- package/dist/chunk-ZY655LYR.js.map +1 -0
- package/dist/claude-subscription-usage.d.ts +3 -1
- package/dist/first-party-client.d.ts +1 -0
- package/dist/index.d.ts +37 -28
- package/dist/index.js +28 -2
- package/dist/input-wait-yield.d.ts +4 -0
- package/dist/interaction-tools.d.ts +1 -0
- package/dist/lazy-tool-transport.d.ts +6 -2
- package/dist/mcp-run-credentials.d.ts +3 -2
- package/dist/mcp-transport-logger.d.ts +10 -0
- package/dist/model-context-inspector.d.ts +17 -1
- package/dist/model-preparation-diagnostics.d.ts +9 -0
- package/dist/model-provider-routing.d.ts +4 -0
- package/dist/model-provider.d.ts +1 -0
- package/dist/model-request-capture.d.ts +9 -0
- package/dist/replayable-json-body.d.ts +2 -1
- package/dist/responses-terminal-error.d.ts +17 -0
- package/dist/sandbox/codemode-authority.d.ts +1 -0
- package/dist/sandbox/index.d.ts +3 -3
- package/dist/sandbox/index.js +5 -1
- package/dist/sandbox/provider-command-session.d.ts +6 -0
- package/dist/sandbox/providers/modal-command-control.d.ts +7 -0
- package/dist/sandbox/providers/modal-command-router-wire.d.ts +8 -0
- package/dist/sandbox/providers/modal-command-session.d.ts +2 -1
- package/dist/sandbox/providers/modal-command-start-errors.d.ts +9 -0
- package/dist/sandbox/providers/modal.d.ts +3 -0
- package/dist/sandbox/routing/routing-session.d.ts +5 -4
- package/dist/workspace-tool-gateway.js +2 -2
- package/package.json +12 -12
- package/src/agent-instructions/PROMPT_CHANGELOG.md +149 -0
- package/src/agent-instructions/base-behavior.ts +120 -0
- package/src/agent-instructions/compose.ts +153 -0
- package/src/agent-instructions/identity.ts +42 -0
- package/src/agent-instructions/index.ts +24 -0
- package/src/agent-instructions/modules/admin.ts +25 -0
- package/src/agent-instructions/modules/artifacts.ts +39 -0
- package/src/agent-instructions/modules/attachments.ts +12 -0
- package/src/agent-instructions/modules/environment.ts +60 -0
- package/src/agent-instructions/modules/goals.ts +15 -0
- package/src/agent-instructions/modules/knowledge.ts +21 -0
- package/src/agent-instructions/modules/machines.ts +17 -0
- package/src/agent-instructions/modules/renderer-markdown.ts +17 -0
- package/src/agent-instructions/modules/repositories.ts +28 -0
- package/src/agent-instructions/modules/sandbox.ts +63 -0
- package/src/agent-instructions/modules/skills.ts +19 -0
- package/src/agent-instructions/modules/subagents.ts +42 -0
- package/src/agent-instructions/runtime-mechanics.ts +55 -0
- package/src/agent-instructions/types.ts +83 -0
- package/src/bundled_default_skills/opengeni-client/SKILL.md +116 -37
- package/src/bundled_default_skills/opengeni-client/references/agent-recipes.md +18 -8
- package/src/bundled_default_skills/opengeni-client/references/api-workflows.md +24 -4
- package/src/bundled_default_skills/opengeni-client/references/chat-facade-fallback.md +23 -4
- package/src/bundled_default_skills/opengeni-client/references/compatibility-and-troubleshooting.md +34 -1
- package/src/bundled_default_skills/opengeni-client/references/configure-the-agent.md +248 -0
- package/src/bundled_default_skills/opengeni-client/references/customer-skill-template.md +2 -1
- package/src/bundled_default_skills/opengeni-client/references/data-tools-and-credentials.md +15 -4
- package/src/bundled_default_skills/opengeni-client/references/discovery-and-autonomy.md +2 -2
- package/src/bundled_default_skills/opengeni-client/references/isolation-and-authorization.md +5 -3
- package/src/bundled_default_skills/opengeni-client/references/product-integration-shapes.md +6 -5
- package/src/bundled_default_skills/opengeni-client/references/product-shapes-and-ui.md +36 -3
- package/src/bundled_default_skills/opengeni-client/references/proxy-from-any-backend.md +170 -0
- package/src/bundled_default_skills/opengeni-client/references/session-history-import.md +147 -0
- package/src/bundled_default_skills/opengeni-client/references/usage-allowances.md +189 -0
- package/src/bundled_default_skills/opengeni-help/SKILL.md +1 -1
- package/src/claude-subscription-usage.ts +23 -4
- package/src/first-party-client.ts +4 -0
- package/src/index.ts +260 -146
- package/src/input-wait-yield.ts +7 -0
- package/src/interaction-tools.ts +16 -2
- package/src/lazy-tool-transport.ts +46 -16
- package/src/mcp-run-credentials.ts +18 -3
- package/src/mcp-transport-logger.ts +46 -0
- package/src/model-context-inspector.ts +37 -3
- package/src/model-preparation-diagnostics.ts +48 -1
- package/src/model-provider-client.ts +5 -1
- package/src/model-provider-routing.ts +95 -1
- package/src/model-provider.ts +1 -0
- package/src/model-request-capture.ts +28 -1
- package/src/provider-history-adapter.ts +24 -3
- package/src/replayable-json-body.ts +19 -2
- package/src/responses-terminal-error.ts +136 -0
- package/src/sandbox/codemode-authority.ts +4 -0
- package/src/sandbox/codemode-client.ts +18 -16
- package/src/sandbox/index.ts +45 -9
- package/src/sandbox/provider-command-session.ts +12 -0
- package/src/sandbox/providers/modal-command-control.ts +118 -12
- package/src/sandbox/providers/modal-command-router-wire.ts +40 -4
- package/src/sandbox/providers/modal-command-session.ts +36 -1
- package/src/sandbox/providers/modal-command-start-errors.ts +27 -0
- package/src/sandbox/providers/modal-legacy-command-control.ts +60 -30
- package/src/sandbox/providers/modal.ts +43 -2
- package/src/sandbox/routing/routing-session.ts +61 -6
- package/src/sandbox/turn-tool-cancellation.ts +8 -1
- package/dist/chunk-22M75RJF.js.map +0 -1
- package/dist/chunk-JUFVYQCY.js.map +0 -1
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
# Archived session history import
|
|
2
|
+
|
|
3
|
+
Use this reference when a host moves historical sessions from embedded/in-process
|
|
4
|
+
OpenGeni to a standalone deployment. The public walkthrough is
|
|
5
|
+
`/integrate/session-history-import`; with source
|
|
6
|
+
access, `docs/product-integration.md` is the canonical product boundary. Verify
|
|
7
|
+
the target service and installed package types support the import contract.
|
|
8
|
+
|
|
9
|
+
## Plan the migration
|
|
10
|
+
|
|
11
|
+
- Grant `sessions:create` for creation and `sessions:control` for batch appends.
|
|
12
|
+
Appends require the same authenticated importer. With `asUser`, use the user's
|
|
13
|
+
permissions; never borrow the organization key's permissions.
|
|
14
|
+
- Keep the same external tenant source/ID and external user source/ID. Bootstrap
|
|
15
|
+
with `ensureWorkspace` and explicitly onboard admitted users with
|
|
16
|
+
`addExternalWorkspaceMember`; import routes never provision either.
|
|
17
|
+
- Preserve titles, original creation/event timestamps, creator and visibility.
|
|
18
|
+
Source timestamps support at most millisecond precision; explicitly normalize
|
|
19
|
+
finer dates and retain originals in the ledger. Negative-zero JSON is rejected.
|
|
20
|
+
Call the organization-key client through
|
|
21
|
+
`.asUser(originalExternalUserId, { source })` for the verified external
|
|
22
|
+
creator/owner. A bare organization key creates only shared, ownerless archives.
|
|
23
|
+
Private imports require a verified owning user and the existing organization
|
|
24
|
+
private-session enablement. Do not widen visibility to make a migration pass.
|
|
25
|
+
- Re-upload source files into the destination workspace with `uploadFile` or
|
|
26
|
+
begin/upload/complete. Persist old-to-new file IDs/references, then replace
|
|
27
|
+
payload references before freezing import requests. Old IDs, signed URLs,
|
|
28
|
+
storage paths and sandbox paths do not become destination references.
|
|
29
|
+
- Keep a host-owned ledger of source/destination session IDs, stable import IDs,
|
|
30
|
+
exact create/append bodies and receipts, file mappings and acknowledged offsets.
|
|
31
|
+
v1 carries title and creation time, not arbitrary metadata; preserve unsupported
|
|
32
|
+
source metadata in this ledger, not invented request fields.
|
|
33
|
+
|
|
34
|
+
## Use the focused server-only SDK subpath
|
|
35
|
+
|
|
36
|
+
```ts
|
|
37
|
+
import { OpenGeniClient } from "@opengeni/sdk";
|
|
38
|
+
import {
|
|
39
|
+
importArchivedSession,
|
|
40
|
+
appendArchivedSessionEvents,
|
|
41
|
+
type ArchivedSessionImportEvent,
|
|
42
|
+
type ImportArchivedSessionRequest,
|
|
43
|
+
type AppendArchivedSessionEventsRequest,
|
|
44
|
+
} from "@opengeni/sdk/session-history-import";
|
|
45
|
+
|
|
46
|
+
const og = new OpenGeniClient({
|
|
47
|
+
baseUrl: process.env.OPENGENI_API_BASE_URL!,
|
|
48
|
+
apiKey: process.env.OPENGENI_API_KEY!, // Organization key; backend only.
|
|
49
|
+
});
|
|
50
|
+
const actor = og.asUser(legacy.creatorExternalId, { source });
|
|
51
|
+
const createRequest = {
|
|
52
|
+
importId: `embedded:${legacy.id}`,
|
|
53
|
+
title: legacy.title,
|
|
54
|
+
createdAt: legacy.createdAt,
|
|
55
|
+
visibility: legacy.visibility, // "workspace_shared" | "user_private"
|
|
56
|
+
events: [],
|
|
57
|
+
} satisfies ImportArchivedSessionRequest;
|
|
58
|
+
await ledger.saveCreateRequest(createRequest);
|
|
59
|
+
const created = await importArchivedSession(actor, workspaceId, createRequest);
|
|
60
|
+
await ledger.saveCreateReceipt(created);
|
|
61
|
+
|
|
62
|
+
const events: ArchivedSessionImportEvent[] = [
|
|
63
|
+
{ type: "user.message", createdAt: legacy.messageCreatedAt, payload: { text: legacy.question } },
|
|
64
|
+
{
|
|
65
|
+
type: "agent.message.completed",
|
|
66
|
+
createdAt: legacy.answerCreatedAt,
|
|
67
|
+
payload: { text: legacy.answer, channel: "final" },
|
|
68
|
+
},
|
|
69
|
+
];
|
|
70
|
+
const appendRequest = {
|
|
71
|
+
batchId: `${createRequest.importId}:batch-0001`,
|
|
72
|
+
offset: created.nextOffset,
|
|
73
|
+
events,
|
|
74
|
+
} satisfies AppendArchivedSessionEventsRequest;
|
|
75
|
+
await ledger.saveAppendRequest(appendRequest);
|
|
76
|
+
const appended = await appendArchivedSessionEvents(
|
|
77
|
+
actor, workspaceId, createRequest.importId, appendRequest,
|
|
78
|
+
);
|
|
79
|
+
await ledger.saveAppendReceipt(appended);
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
The host owns `source`, `workspaceId`, `legacy` and `ledger` in this example;
|
|
83
|
+
resolve them from authorized migration records, not browser request bodies.
|
|
84
|
+
Bound deterministic IDs to 200 characters rather than blindly concatenating
|
|
85
|
+
unbounded legacy IDs. Each helper takes `client` first and delegates to its
|
|
86
|
+
`requestJson`, preserving `asUser` and ordinary `OpenGeniApiError` behavior.
|
|
87
|
+
There are no eager client methods or root helper exports.
|
|
88
|
+
|
|
89
|
+
External mapping equivalents are
|
|
90
|
+
`importExternalWorkspaceArchivedSession(client, source, externalId, request)` and
|
|
91
|
+
`appendExternalWorkspaceArchivedSessionEvents(client, source, externalId, importId, request)`.
|
|
92
|
+
They resolve an existing tenant mapping, not an external user identity.
|
|
93
|
+
|
|
94
|
+
The routes are `POST /v1/workspaces/:workspaceId/session-imports` and
|
|
95
|
+
`POST /v1/workspaces/:workspaceId/session-imports/:importId/events`. External
|
|
96
|
+
mapping forms use `/v1/workspaces/external/:source/:externalId/session-imports`
|
|
97
|
+
and the same `/:importId/events` suffix. Never expose these through the session
|
|
98
|
+
proxy or a generic organization-key passthrough.
|
|
99
|
+
|
|
100
|
+
## Bounds, replay and recovery
|
|
101
|
+
|
|
102
|
+
Import sends `{ importId, title, createdAt, visibility?, events? }`, with events
|
|
103
|
+
defaulting to `[]`. Append sends `{ batchId, offset, events }`; events must be
|
|
104
|
+
non-empty. IDs and title are at most 200 characters. Each request accepts at
|
|
105
|
+
most 100 events and 1 MiB serialized UTF-8 JSON, with 256 KiB per event. Split by
|
|
106
|
+
both event count and actual byte size, not just string length.
|
|
107
|
+
|
|
108
|
+
Each event is `{ type, createdAt, turnId?, payload }`: a finite supported
|
|
109
|
+
historical event type, original ISO timestamp, optional UUID/null presentation
|
|
110
|
+
correlation and a JSON-object payload. Read the installed contract rather than
|
|
111
|
+
assuming all `SessionEventType` values are importable. Preserve completed
|
|
112
|
+
messages and native tool-call/result/goal payload shapes where available; these
|
|
113
|
+
facts are optional. Import does not reconstruct missing runtime state.
|
|
114
|
+
|
|
115
|
+
Persist exact requests before sending them. `importId` is workspace-scoped;
|
|
116
|
+
repeating the same create replays the session (`created: false`). Append uses a
|
|
117
|
+
stable `batchId` and zero-based event-count `offset`, independent of timeline
|
|
118
|
+
sequence. The next new batch uses the acknowledged `nextOffset`; retrying an
|
|
119
|
+
uncertain batch must use the stored original offset, body, actor and mapping,
|
|
120
|
+
not a freshly calculated offset. Exact batch replay returns `replayed: true`
|
|
121
|
+
without duplicate events. The SDK never automatically retries mutations.
|
|
122
|
+
|
|
123
|
+
A changed request under the same import/batch ID or an out-of-order new offset
|
|
124
|
+
returns `409`. Reconcile the ledger and acknowledged offset; do not generate
|
|
125
|
+
new IDs, skip events or change visibility to bypass a conflict. Keep file
|
|
126
|
+
mappings stable across retries so event bodies remain identical.
|
|
127
|
+
|
|
128
|
+
## Keep the end-user conversation native and read-only
|
|
129
|
+
|
|
130
|
+
Render the returned session ID with the unchanged `SessionConversation` behind
|
|
131
|
+
the existing session proxy. `session.importedArchive` contains
|
|
132
|
+
`{ importId, importedAt, readOnly: true }`, distinct from personal archive/restore
|
|
133
|
+
preferences. Imported archives never offer Send or Steer; continuation is
|
|
134
|
+
unsupported in v1. If the user requests new work, create a separate new session
|
|
135
|
+
through the normal server-owned flow, without silently injecting the archive
|
|
136
|
+
as model context.
|
|
137
|
+
|
|
138
|
+
Only the human/audit timeline is imported: no `session_history_items`, model
|
|
139
|
+
memory, turn execution, workflow, active goal, pending decision, credential,
|
|
140
|
+
Connection, sandbox or schedule is restored. Tool calls/results and completed
|
|
141
|
+
goals are historical facts, not tool invocation or instruction authority. Keep
|
|
142
|
+
this integration Skill with the coding agent, not the customer-facing agent.
|
|
143
|
+
|
|
144
|
+
Verify mapping/owner/visibility, chronological rendering and destination file
|
|
145
|
+
references; then verify exact retries do not duplicate events, conflicts stay
|
|
146
|
+
conflicts, and the browser proxy refuses import routes. Confirm new ordinary
|
|
147
|
+
sessions still use the unchanged full conversation flow.
|
|
@@ -0,0 +1,189 @@
|
|
|
1
|
+
# Usage allowances in a product integration
|
|
2
|
+
|
|
3
|
+
Use when the product sells included usage, per-seat plans, team budgets,
|
|
4
|
+
administrator splits, or top-ups. With the repository available, read
|
|
5
|
+
`docs/usage-allowances.md` for complete recipes and
|
|
6
|
+
`docs/product-integration.md` for the organization-key/user boundary.
|
|
7
|
+
Verify installed SDK types and deployed routes before using these primitives.
|
|
8
|
+
|
|
9
|
+
`OPENGENI_USAGE_ALLOWANCES_ENABLED` defaults false for rolling admission.
|
|
10
|
+
Upgrade all API/control/turn consumers before enabling new config/grant/rule
|
|
11
|
+
writes. Reads and enforcement of persisted policies do not depend on this
|
|
12
|
+
producer flag; disabling it is not an allowance bypass or permission to run
|
|
13
|
+
old readers.
|
|
14
|
+
Disabled producers return 409 for config/grants/non-null member rules;
|
|
15
|
+
authorized versioned clear and `rule: null` recovery remain available.
|
|
16
|
+
|
|
17
|
+
## Choose the product policy
|
|
18
|
+
|
|
19
|
+
- Per-seat plan: the backend computes included USD micros from paid seats;
|
|
20
|
+
`memberDefault: "equal_share"` splits by eligible current OpenGeni members,
|
|
21
|
+
not the product's paid-seat count.
|
|
22
|
+
- Stable user caps: use `{ credits }`; roster changes and workspace grants do
|
|
23
|
+
not automatically expand a fixed member ceiling.
|
|
24
|
+
- Team budget: `"monthly"` with default `"none"` gives one workspace ceiling
|
|
25
|
+
and no separate member cap. `"none"` as the period is a nonrenewing budget.
|
|
26
|
+
- Administrator sliders: turn authenticated choices into `{ share }` rules
|
|
27
|
+
with exact member versions. Normalizing the sum is product policy; writes
|
|
28
|
+
are per-member, not an atomic roster-wide rebalance.
|
|
29
|
+
- Custom shares/top-ups: shares may exceed one or sum above one. They are
|
|
30
|
+
ceilings, never reserved allocations or guaranteed access to capacity.
|
|
31
|
+
|
|
32
|
+
Amounts are integer USD micros: 1 USD = 1,000,000. Do not use floating dollars,
|
|
33
|
+
tokens, or estimated provider expense as allowance amounts.
|
|
34
|
+
The configuration is `{ includedCredits, period: "monthly" | "none",
|
|
35
|
+
anchorDay?: 1..31, memberDefault?: "none" | "equal_share" | { share } | { credits },
|
|
36
|
+
thresholds?: { workspace?: number[], member?: number[] } }`.
|
|
37
|
+
Monthly boundaries are UTC, with anchors clamped to each month's last day;
|
|
38
|
+
omitted threshold lists default to `[0.8, 1]`.
|
|
39
|
+
Each threshold list accepts at most 16 positive fractions up to one.
|
|
40
|
+
Anchor edits retain active-window usage until its boundary. Switching to
|
|
41
|
+
nonrenewing preserves the accounting key/usage and removes the reset time;
|
|
42
|
+
switching back preserves usage and sets a monthly boundary. Use returned
|
|
43
|
+
windows rather than computing them from the new config.
|
|
44
|
+
Equal shares count canonical eligible humans, including active admitted
|
|
45
|
+
external identities and the Personal-workspace owner, never keys/services.
|
|
46
|
+
|
|
47
|
+
## SDK and authority
|
|
48
|
+
|
|
49
|
+
The root `OpenGeniClient` provides:
|
|
50
|
+
|
|
51
|
+
- `getWorkspaceAllowance(workspaceId)`
|
|
52
|
+
- `setWorkspaceAllowance(workspaceId, { ...config, expectedVersion })`
|
|
53
|
+
- `clearWorkspaceAllowance(workspaceId, { expectedVersion })`
|
|
54
|
+
- `getWorkspaceAllowanceState(workspaceId)` returns `{ version, config }`,
|
|
55
|
+
including a cleared lifecycle's version.
|
|
56
|
+
- `grantWorkspaceCredits(workspaceId, { operationId, credits, expiresAt? })`
|
|
57
|
+
- `setMemberAllowance(workspaceId, subjectId | { source, externalId },
|
|
58
|
+
{ rule: { share } | { credits } | null, expectedVersion })`
|
|
59
|
+
- `getUsage(workspaceId, { period?: "current" | "YYYY-MM", limit?, cursor? })`
|
|
60
|
+
- `getMyUsage(workspaceId, { period?: "current" | "YYYY-MM" })`
|
|
61
|
+
|
|
62
|
+
Workspace config/grants require a full-access organization key with literal
|
|
63
|
+
`api_keys:manage` or verified human `account:admin`; workspace administrators
|
|
64
|
+
cannot raise or clear the budget. Human organization budget administration
|
|
65
|
+
does not require membership in the target shared workspace, but grants no
|
|
66
|
+
operational access or full usage roster.
|
|
67
|
+
Member splits require verified human workspace administration or a full
|
|
68
|
+
organization key; account-admin-only, workspace-key, and service callers cannot
|
|
69
|
+
write them. **All reads and writes refuse agents.** Build authenticated backend/admin flows,
|
|
70
|
+
not agent tools that adjust the agent's own spending ceiling.
|
|
71
|
+
Membership must already exist; assigning a rule never grants access.
|
|
72
|
+
|
|
73
|
+
`expectedVersion: 0` means initial creation, exact versions thereafter.
|
|
74
|
+
Store returned versions; refresh/reconcile conflicts rather than guessing.
|
|
75
|
+
Member `null` restores the workspace default and is itself versioned.
|
|
76
|
+
Clear requires an exact positive version and returns `{ version }`. Supply an
|
|
77
|
+
`operationId` and reuse the exact request after a lost response. The replay
|
|
78
|
+
rechecks authority and conflicts after a later lifecycle change; read
|
|
79
|
+
`getWorkspaceAllowanceState` to reconcile without guessing a version.
|
|
80
|
+
The existing configuration read still returns null after clear.
|
|
81
|
+
Recreation requires that exact clear version; zero is rejected after any
|
|
82
|
+
configuration has existed, including after clear.
|
|
83
|
+
|
|
84
|
+
Allowance refusals identify `scope` and `resetsAt`. A workspace ceiling is
|
|
85
|
+
raised by an organization administrator/full organization key; a member
|
|
86
|
+
ceiling is adjusted by a workspace administrator/full organization key.
|
|
87
|
+
Buying organization credits or connecting a subscription does not by itself
|
|
88
|
+
raise an exhausted allowance. Web, MCP, and Slack retain this distinction.
|
|
89
|
+
Reuse the grant's operation ID and exact body after an uncertain result; a
|
|
90
|
+
new ID grants again and a changed body under the same ID conflicts.
|
|
91
|
+
Omitted/null expiry means no expiry. A grant increases allowance capacity,
|
|
92
|
+
not the organization's purchased-credit balance.
|
|
93
|
+
The grant receipt is `{ operationId, credits, remaining, expiresAt }`;
|
|
94
|
+
operation IDs are nonblank opaque text bounded to 256 UTF-8 bytes.
|
|
95
|
+
|
|
96
|
+
## Meter and browser boundary
|
|
97
|
+
|
|
98
|
+
Usage returns `{ period: { start, end }, workspace, members, nextCursor }`.
|
|
99
|
+
Workspace/member rows include `limit`, `used`, `remaining`, `fraction`,
|
|
100
|
+
`status: "ok" | "warning" | "exhausted"`, and `resetsAt`; workspace also has
|
|
101
|
+
`includedCredits`/`grantsRemaining`, members have subject/external identity,
|
|
102
|
+
override `rule`, and `version`. Use returned bounds and computed limits.
|
|
103
|
+
Nullable limits/fractions mean unbounded; remaining clamps to zero and
|
|
104
|
+
positive-limit fraction can exceed one after settlement. Zero limits report
|
|
105
|
+
fraction one and exhausted status even with no recorded usage.
|
|
106
|
+
GETs/admission checks are read-only; periodic API maintenance owns snapshots,
|
|
107
|
+
rollover, and notification evaluation.
|
|
108
|
+
|
|
109
|
+
For the normal browser conversation, use the packaged session proxy and
|
|
110
|
+
`client.getMyUsage(...)`. It exposes only `GET /usage/me`, only a `period`
|
|
111
|
+
query, and the resolved authenticated user's row through `asUser`. It refuses
|
|
112
|
+
full roster/config/grant/member routes and has no service-key fallback.
|
|
113
|
+
Render `fraction` instead of raw USD micros; clamp the bar, not the underlying
|
|
114
|
+
percentage. The response still contains raw amounts and workspace aggregates:
|
|
115
|
+
if those must never reach the browser, provide a same-origin authenticated
|
|
116
|
+
server projection returning only allowed fraction/status/reset fields.
|
|
117
|
+
Keep the organization key on the backend.
|
|
118
|
+
|
|
119
|
+
React hosts can use `@opengeni/react/usage` instead of hand-building this:
|
|
120
|
+
`useUsage`/`<UsageMeter>` read `/usage/me` (shares only unless the host passes
|
|
121
|
+
`formatAmount`), `<UsageLimitNotice>` is the composer's near/at-limit line
|
|
122
|
+
(`labels` and `action` let the host name its own remedy, such as "Upgrade"),
|
|
123
|
+
and `<UsageMemberList>` is an admin roster with a share slider whose
|
|
124
|
+
`onChangeRule` must call the host backend (never the proxy). The timeline's
|
|
125
|
+
"usage limit reached" row takes `allowanceExhaustedLabels` or
|
|
126
|
+
`renderAllowanceExhausted` on `SessionConversation`/`MessageTimeline`.
|
|
127
|
+
Browser code with only the narrow client uses `@opengeni/sdk/usage-allowances`
|
|
128
|
+
free functions over `requestJson`.
|
|
129
|
+
|
|
130
|
+
Share-based ceilings use included credits plus **remaining unexpired grants**,
|
|
131
|
+
so they vary with grants, consumption, expiry, and membership. They are not a
|
|
132
|
+
promise of a fixed monthly slice.
|
|
133
|
+
The workspace meter includes consumed grants from the selected period as well
|
|
134
|
+
as remaining grants; the member share base does not. Do not compute member
|
|
135
|
+
limits from `workspace.limit`.
|
|
136
|
+
|
|
137
|
+
## Settlement, attribution, and notifications
|
|
138
|
+
|
|
139
|
+
Only actual OpenGeni credit debits consume allowance. Externally funded
|
|
140
|
+
subscription/BYOK work without such a debit is exempt, not necessarily free
|
|
141
|
+
upstream. No reservation occurs: a call may overshoot, concurrent calls may
|
|
142
|
+
overshoot together, and the next admission is blocked. Reads remain authorized.
|
|
143
|
+
Service work without a verified initiating member uses the workspace ceiling
|
|
144
|
+
only. Member schedules, children, goal continuations, and recovery retain their
|
|
145
|
+
frozen causal initiating member, never a viewer or guessed session creator.
|
|
146
|
+
|
|
147
|
+
`OpenGeniAllowanceExhaustedError` carries `code: "allowance_exhausted"`,
|
|
148
|
+
`scope`, `resetsAt`, and optional `subjectId`; it is not an automatic retry.
|
|
149
|
+
Accepted messages can encounter asynchronous worker admission refusal; inspect
|
|
150
|
+
session state/events rather than resending a prompt.
|
|
151
|
+
Session `usage.exhausted` completes a budget-limited turn segment, leaves the
|
|
152
|
+
session idle/resumable, and pauses an active goal. A grant/reset is not an
|
|
153
|
+
automatic goal resume. Version/grant conflicts return 409; missing targets
|
|
154
|
+
404, unauthorized operations 403, invalid requests 400.
|
|
155
|
+
Historical `YYYY-MM` reads select anchor-month counters and the recorded
|
|
156
|
+
period configuration/rules/denominator/grant inventory, with expiry evaluated
|
|
157
|
+
at period end. Current named periods remain live; identities/row discovery
|
|
158
|
+
can still reflect current records, so this is not a complete historical roster.
|
|
159
|
+
Settlement time chooses the window; activation does not backfill earlier
|
|
160
|
+
ledger usage. Included capacity is spent first, then grants earliest-expiry
|
|
161
|
+
first; unused unexpired grants survive a monthly reset. Clearing config is
|
|
162
|
+
not a refund or history reset.
|
|
163
|
+
Paid Knowledge queries/indexing and warm-compute debits also retain exact
|
|
164
|
+
turn/request/enqueue/lease-epoch attribution; observers and creators do not
|
|
165
|
+
replace it. Legacy unknown paid attribution can defer/refuse work rather
|
|
166
|
+
than silently charge a service. Managed video retains prepaid billing;
|
|
167
|
+
matching refunds reverse the original period's recorded usage and exact
|
|
168
|
+
included/grant/member allocations once. Expired restored grants stay unusable;
|
|
169
|
+
legacy debits without allocation receipts do not get invented reversals.
|
|
170
|
+
|
|
171
|
+
The public webhook types are `usage.threshold_reached`,
|
|
172
|
+
`usage.exhausted`, and `usage.period_reset`; usage envelopes omit or null
|
|
173
|
+
session/turn IDs, have an optional sequence, and carry workspace/member scope
|
|
174
|
+
when present. Verify actual deployed
|
|
175
|
+
emission and reset timing, not only the type list. Verify signatures with
|
|
176
|
+
`verifyWebhookEvent`, dedupe by ID, tolerate unordered at-least-once delivery,
|
|
177
|
+
and reread usage after a notification. See `docs/workspace-integrations.md`.
|
|
178
|
+
Periodic maintenance in the API webhook-dispatch loop evaluates deduplicated
|
|
179
|
+
per-period/member thresholds, idle rollover, and expiry without usage readers
|
|
180
|
+
or inference. The exhaustion threshold is always evaluated. Sweeps are bounded
|
|
181
|
+
to 20 workspaces/100 members per page by default, normally one minute apart;
|
|
182
|
+
reset delivery is not guaranteed at the exact UTC boundary. GETs never enqueue
|
|
183
|
+
events. Receipt/outbox enqueue is transactional; maintenance failures are
|
|
184
|
+
recorded/retried without reversing earlier debits. Late subscribers are not
|
|
185
|
+
guaranteed past threshold replay.
|
|
186
|
+
|
|
187
|
+
Verify CAS/replayed grants, UTC month-end windows, fallback rules, expiry,
|
|
188
|
+
history, overshoot, frozen attribution, external funding, proxy rejection, and
|
|
189
|
+
real webhook emission before presenting a plan as enforced.
|
|
@@ -15,7 +15,7 @@ The public documentation index is **https://docs.opengeni.ai/llms.txt**. Fetch
|
|
|
15
15
|
it with the available web or HTTP tool, then read the relevant pages. Markdown
|
|
16
16
|
pages are available by adding `.md`, for example:
|
|
17
17
|
|
|
18
|
-
- Product integration: https://docs.opengeni.ai/
|
|
18
|
+
- Product integration: https://docs.opengeni.ai/embed-manually.md
|
|
19
19
|
- Authentication: https://docs.opengeni.ai/reference/authentication.md
|
|
20
20
|
- SDK: https://docs.opengeni.ai/reference/sdk.md
|
|
21
21
|
|
|
@@ -1,15 +1,34 @@
|
|
|
1
1
|
import { AsyncLocalStorage } from "node:async_hooks";
|
|
2
2
|
|
|
3
3
|
type Observer = (providerId: string, response: Response) => void;
|
|
4
|
-
|
|
4
|
+
type Prepare = (providerId: string, headers: Headers) => Promise<Headers>;
|
|
5
|
+
const observers = new AsyncLocalStorage<{
|
|
6
|
+
observe: Observer;
|
|
7
|
+
prepare?: Prepare;
|
|
8
|
+
}>();
|
|
5
9
|
|
|
6
10
|
/** Like Codex usage headers: free observations within this turn's provider context. */
|
|
7
|
-
export function withClaudeUsageObserver<T>(
|
|
8
|
-
|
|
11
|
+
export function withClaudeUsageObserver<T>(
|
|
12
|
+
observer: Observer,
|
|
13
|
+
run: () => Promise<T>,
|
|
14
|
+
prepare?: Prepare,
|
|
15
|
+
): Promise<T> {
|
|
16
|
+
return observers.run({ observe: observer, ...(prepare ? { prepare } : {}) }, run);
|
|
17
|
+
}
|
|
18
|
+
export async function prepareClaudeSubscriptionRequest(
|
|
19
|
+
providerId: string,
|
|
20
|
+
input: Parameters<typeof fetch>[0],
|
|
21
|
+
init?: RequestInit,
|
|
22
|
+
) {
|
|
23
|
+
const prepare = observers.getStore()?.prepare;
|
|
24
|
+
if (!prepare) return init;
|
|
25
|
+
const headers = new Headers(input instanceof Request ? input.headers : undefined);
|
|
26
|
+
new Headers(init?.headers).forEach((value, key) => headers.set(key, value));
|
|
27
|
+
return { ...init, headers: await prepare(providerId, headers) };
|
|
9
28
|
}
|
|
10
29
|
export function observeClaudeUsageResponse(providerId: string, response: Response): void {
|
|
11
30
|
try {
|
|
12
|
-
observers.getStore()?.(providerId, response);
|
|
31
|
+
observers.getStore()?.observe(providerId, response);
|
|
13
32
|
} catch {
|
|
14
33
|
// Usage telemetry must never change or consume a model response.
|
|
15
34
|
}
|
|
@@ -25,6 +25,7 @@ export function createFirstPartyAttemptClient(input: {
|
|
|
25
25
|
};
|
|
26
26
|
selectedTools: readonly FirstPartyMcpToolName[];
|
|
27
27
|
permissions?: readonly Permission[];
|
|
28
|
+
credentialRestriction?: "developer_setup";
|
|
28
29
|
fetch?: typeof fetch;
|
|
29
30
|
signal?: AbortSignal;
|
|
30
31
|
}) {
|
|
@@ -53,6 +54,9 @@ export function createFirstPartyAttemptClient(input: {
|
|
|
53
54
|
principalKind: "agent_attempt",
|
|
54
55
|
permissions: [...(input.permissions ?? DEFAULT_FIRST_PARTY_MCP_PERMISSIONS)],
|
|
55
56
|
firstPartyMcpTools: [...input.selectedTools],
|
|
57
|
+
...(input.credentialRestriction
|
|
58
|
+
? { credentialRestriction: input.credentialRestriction }
|
|
59
|
+
: {}),
|
|
56
60
|
exp: Math.floor(Date.now() / 1_000) + 60 * 60,
|
|
57
61
|
});
|
|
58
62
|
const headers = new Headers(init?.headers);
|