@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
|
@@ -6,9 +6,10 @@ description: >-
|
|
|
6
6
|
automation. Defaults to embedding the full React conversation behind the
|
|
7
7
|
packaged SDK session proxy. Use for discovery, connecting repositories and
|
|
8
8
|
resources, SDK/API and React choices, implementation, verification, and
|
|
9
|
-
handoff against a managed, self-hosted, or local OpenGeni deployment
|
|
10
|
-
|
|
11
|
-
|
|
9
|
+
handoff against a managed, self-hosted, or local OpenGeni deployment, including
|
|
10
|
+
the agent's capabilities, identity, chat privacy, and server-only archived-session
|
|
11
|
+
migration. Not for changing OpenGeni internals or mounting its runtime inside
|
|
12
|
+
the customer's process.
|
|
12
13
|
---
|
|
13
14
|
|
|
14
15
|
# OpenGeni Client
|
|
@@ -17,6 +18,12 @@ Use this skill when a customer's product and OpenGeni remain separate systems.
|
|
|
17
18
|
That is the normal integration shape: the product owns its users and business
|
|
18
19
|
UI, while a standalone OpenGeni deployment owns agent sessions and execution.
|
|
19
20
|
|
|
21
|
+
For first-time organization and workspace provisioning, start with
|
|
22
|
+
[OpenGeni developer setup](https://docs.opengeni.ai/guides/developer-plugin), then return here to write
|
|
23
|
+
the embedding code. That skills-only workflow uses the coding agent's own
|
|
24
|
+
browser and public REST/SDK, with a scoped Developer setup key; no OpenGeni MCP
|
|
25
|
+
server is required.
|
|
26
|
+
|
|
20
27
|
Do not confuse two meanings of "skill": this file teaches a customer's coding
|
|
21
28
|
agent how to integrate OpenGeni; session `skills` are runtime capabilities or
|
|
22
29
|
instructions attached to an OpenGeni agent. The former designs the integration.
|
|
@@ -43,17 +50,21 @@ No Pack, installation, repository clone, or sandbox is needed to read the bundle
|
|
|
43
50
|
copy. It is guidance, not authority to access a repository, secret, or deployment.
|
|
44
51
|
Embedded products may narrow bundled guidance with `bundledSkillIds`.
|
|
45
52
|
|
|
46
|
-
- Inspect the customer's repository
|
|
47
|
-
frontend conventions, installed packages, tests, CI,
|
|
48
|
-
|
|
53
|
+
- Inspect before you build. In the customer's repository: authentication,
|
|
54
|
+
tenancy, data routes, frontend conventions, installed packages, tests, CI,
|
|
55
|
+
deployment guidance, and any OpenGeni code already there. In OpenGeni:
|
|
56
|
+
`getClientConfig()` (is `agentConfig.enabled`? which capabilities are
|
|
57
|
+
offered?), the workspace's `settings.sessionAgentDefaults`, and an existing
|
|
58
|
+
session's `agent` and `effectiveTools`. Only then ask questions or choose an
|
|
59
|
+
integration shape.
|
|
49
60
|
- If the target repository or resources are missing, first inspect available
|
|
50
61
|
authorized resources and connection/setup tools. Help the user connect or
|
|
51
62
|
attach the specific missing source; explain the next action in product terms.
|
|
52
63
|
Continue useful discovery without requesting broad credentials or pretending
|
|
53
64
|
missing access is configured. Read
|
|
54
65
|
[Discovery and autonomy](references/discovery-and-autonomy.md) for that workflow.
|
|
55
|
-
- Four choices belong to the user: who shares what (
|
|
56
|
-
|
|
66
|
+
- Four choices belong to the user: who shares what (`chats`: private, shared
|
|
67
|
+
or isolated), when things run (schedule and time zone), where outputs land
|
|
57
68
|
(which screen, record, or channel), and whether the agent may write. If the
|
|
58
69
|
request or repository does not settle any of them, ask ONE bundled question
|
|
59
70
|
(the structured question UI when available) with a recommended answer for
|
|
@@ -70,11 +81,17 @@ Embedded products may narrow bundled guidance with `bundledSkillIds`.
|
|
|
70
81
|
|
|
71
82
|
## Default: the full conversation behind a packaged proxy
|
|
72
83
|
|
|
73
|
-
Default to OpenGeni's complete conversation experience:
|
|
74
|
-
`OpenGeniChat` (the user's chat list plus `SessionConversation`)
|
|
75
|
-
`@opengeni/react/compiled.css` (brand it with
|
|
84
|
+
Default to OpenGeni's complete conversation experience: `OpenGeniProvider`,
|
|
85
|
+
`OpenGeniChat` (the user's chat list plus `SessionConversation`) from
|
|
86
|
+
`@opengeni/react/session-ui`, and `@opengeni/react/compiled.css` (brand it with
|
|
87
|
+
`--og-*` tokens). Import from `session-ui`, not the package root: the root also
|
|
88
|
+
exports the workbench, whose editors, terminal and desktop viewer are optional
|
|
89
|
+
peer dependencies your bundler would try to resolve. The UI is backed by the
|
|
76
90
|
normal session SDK through `createSessionProxyHandler`, a tenant/user-scoped
|
|
77
|
-
same-origin proxy on the product server with Next.js, Express, and Hono
|
|
91
|
+
same-origin proxy on the product server with Next.js, Express, and Hono
|
|
92
|
+
adapters (other backends: see
|
|
93
|
+
[Proxy from any backend](references/proxy-from-any-backend.md)). It already
|
|
94
|
+
provides streaming, replay, queue, steer, approvals,
|
|
78
95
|
human input, attachments, and pause/resume. Deviate only when the product needs
|
|
79
96
|
a materially different interaction model, a non-React frontend, or compute
|
|
80
97
|
surfaces, and record why.
|
|
@@ -108,6 +125,7 @@ await og.addExternalWorkspaceMember(workspace.id, {
|
|
|
108
125
|
const acme = (token: string) => ({ id: "acme", headers: { Authorization: `Bearer ${token}` } });
|
|
109
126
|
export const dynamic = "force-dynamic";
|
|
110
127
|
export const { GET, POST, PUT, PATCH, DELETE } = createSessionProxyRoute(og, {
|
|
128
|
+
chats: "private", // the default: each user's chats are theirs; "shared" | "isolated"
|
|
111
129
|
resolve: async (request) => {
|
|
112
130
|
const me = await authenticate(request); // the product's own session check
|
|
113
131
|
return me
|
|
@@ -119,10 +137,13 @@ export const { GET, POST, PUT, PATCH, DELETE } = createSessionProxyRoute(og, {
|
|
|
119
137
|
createSession: async ({ initialMessage, idempotencyKey }, { user }) => ({
|
|
120
138
|
initialMessage,
|
|
121
139
|
idempotencyKey,
|
|
140
|
+
agent: {
|
|
141
|
+
identity: "You are Acme's support assistant. Friendly and brief.",
|
|
142
|
+
capabilities: "none", // Acme's tools, asking questions, reading Skills; nothing else
|
|
143
|
+
},
|
|
122
144
|
skills: productSkills, // product-owned, inline
|
|
123
145
|
mcpServers: [{ ...acme(await mintUserToken(user)), url: ACME_MCP_URL, allowedTools }],
|
|
124
146
|
tools: [{ kind: "mcp", id: "acme" }], // a per-session server must also be selected here
|
|
125
|
-
firstPartyMcpTools: [],
|
|
126
147
|
sandboxBackend: "none", // pure chat/tool agent: no sandbox to start or shell around tools
|
|
127
148
|
}),
|
|
128
149
|
// Every forwarded message: fresh per-user token and server-owned page context.
|
|
@@ -136,7 +157,7 @@ export const { GET, POST, PUT, PATCH, DELETE } = createSessionProxyRoute(og, {
|
|
|
136
157
|
```tsx
|
|
137
158
|
// Browser: the unmodified SDK client, pointed at the mount.
|
|
138
159
|
import { OpenGeniClient } from "@opengeni/sdk";
|
|
139
|
-
import { OpenGeniChat, OpenGeniProvider } from "@opengeni/react";
|
|
160
|
+
import { OpenGeniChat, OpenGeniProvider } from "@opengeni/react/session-ui";
|
|
140
161
|
import "@opengeni/react/compiled.css";
|
|
141
162
|
|
|
142
163
|
const client = new OpenGeniClient({ baseUrl: "/api/opengeni" });
|
|
@@ -145,6 +166,11 @@ const client = new OpenGeniClient({ baseUrl: "/api/opengeni" });
|
|
|
145
166
|
</OpenGeniProvider>;
|
|
146
167
|
```
|
|
147
168
|
|
|
169
|
+
`agent` needs the deployment's agent settings (`agentConfig.enabled` in the
|
|
170
|
+
client config); on an older or rollout-disabled deployment send
|
|
171
|
+
`firstPartyMcpTools: []` instead of `agent` and see
|
|
172
|
+
[Configure the agent](references/configure-the-agent.md).
|
|
173
|
+
|
|
148
174
|
For an assistant bound to one record (a ticket, a dashboard), create the session
|
|
149
175
|
server-side as the user (`og.asUser(user.id, { source }).createSession(...)`
|
|
150
176
|
with a stable `idempotencyKey`) and render `<SessionConversation sessionId>`.
|
|
@@ -154,6 +180,19 @@ only chats the user created (`sessionList: "visible"` widens it). Never replace
|
|
|
154
180
|
proxy with a raw passthrough of arbitrary paths under the organization key.
|
|
155
181
|
Reset UI state when the user or tenant changes.
|
|
156
182
|
|
|
183
|
+
## Migrating from embedded OpenGeni
|
|
184
|
+
|
|
185
|
+
When moving old in-process sessions to a standalone deployment, read
|
|
186
|
+
[Archived session history import](references/session-history-import.md).
|
|
187
|
+
Use server-only functions from `@opengeni/sdk/session-history-import`, with the
|
|
188
|
+
existing tenant mappings and verified `asUser` creator/owner. Preserve timestamps
|
|
189
|
+
and visibility, re-upload files and replace references before import, and retain
|
|
190
|
+
exact import/batch requests for idempotent retries. This is a read-only event
|
|
191
|
+
archive, never model-facing history or resumable execution. Keep
|
|
192
|
+
`SessionConversation` behind the existing proxy; imported archives never offer
|
|
193
|
+
Send or Steer, and continuation is unsupported in v1. Do not add import routes
|
|
194
|
+
to the browser proxy or attach this implementation Skill to end-user agents.
|
|
195
|
+
|
|
157
196
|
## Deliberate deviations
|
|
158
197
|
|
|
159
198
|
Choose one only for its stated reason; read
|
|
@@ -164,6 +203,10 @@ Choose one only for its stated reason; read
|
|
|
164
203
|
queue, composer, approval, and human-input behavior.
|
|
165
204
|
- **SDK only**: a non-React frontend (Svelte, Vue, native mobile), a CLI, or
|
|
166
205
|
backend automation. Keep the SDK on a product backend route.
|
|
206
|
+
- **A non-JavaScript backend** (Django, Rails, Go, PHP, Java): keep the React
|
|
207
|
+
conversation and implement the proxy's small HTTP contract in that backend
|
|
208
|
+
instead of adding a Node sidecar. See
|
|
209
|
+
[Proxy from any backend](references/proxy-from-any-backend.md).
|
|
167
210
|
- **Workbench**: the product genuinely exposes agent compute (changes, files,
|
|
168
211
|
terminal, desktop). It has optional heavy peers.
|
|
169
212
|
- **Chat facade fallback** (`@opengeni/sdk/chat`): the product already has a
|
|
@@ -184,6 +227,27 @@ Read selectively: [Product integration shapes](references/product-integration-sh
|
|
|
184
227
|
[Data tools and credentials](references/data-tools-and-credentials.md), and
|
|
185
228
|
[External users and embedded connection setup](references/external-users-and-connect.md).
|
|
186
229
|
|
|
230
|
+
## Configure The Agent
|
|
231
|
+
|
|
232
|
+
Every surface takes one `agent` object: `capabilities` (start from `"all"` or
|
|
233
|
+
`"none"`, then switch `webSearch`, `humanInput`, `skills`, `goals`,
|
|
234
|
+
`subagents`, `knowledge`, `schedules`, `artifacts`, `browser`, `media`,
|
|
235
|
+
`workspaceFiles`, `workspaceConnectors`, `workspaceAdmin`), `identity` (who the
|
|
236
|
+
agent is), `instructions` and `renderer` (`"opengeni"` for OpenGeni's React
|
|
237
|
+
components, `"markdown"` for your own UI). Pick capabilities from the product's
|
|
238
|
+
intent, not from tool names: a customer-facing assistant usually starts from
|
|
239
|
+
`"none"` plus what it needs; an internal operator agent from `"all"` minus what
|
|
240
|
+
it must not do. Set workspace defaults with `sessionAgentDefaults`, schedules
|
|
241
|
+
with `agentConfig.agent`, and change a running session with `updateSessionAgent`
|
|
242
|
+
(from its next turn). Check the result on `session.agent` and
|
|
243
|
+
`session.effectiveTools`. Read [Configure the agent](references/configure-the-agent.md)
|
|
244
|
+
before choosing; it also covers `chats`, the admission switch and error codes.
|
|
245
|
+
|
|
246
|
+
For per-seat included usage, administrator splits, top-ups, team budgets, or
|
|
247
|
+
browser progress meters, read [Usage allowances](references/usage-allowances.md).
|
|
248
|
+
Keep organization-budget writes on the backend; the conversation proxy exposes
|
|
249
|
+
only own usage. These are post-call ceilings, not prepaid reservations.
|
|
250
|
+
|
|
187
251
|
## Build Gotchas
|
|
188
252
|
|
|
189
253
|
- Always pass `baseUrl` (`process.env.OPENGENI_API_BASE_URL`); the chat facade
|
|
@@ -265,9 +329,16 @@ Use one organization API key for the external backend (`createOrganizationApiKey
|
|
|
265
329
|
`listOrganizationApiKeys`, `deleteOrganizationApiKey`); the token is shown once,
|
|
266
330
|
so store it in the product's secret manager.
|
|
267
331
|
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
332
|
+
**A full-access organization API key is all the integration needs.** It creates
|
|
333
|
+
workspaces (`ensureWorkspace`, `workspaceIdFor`), adds external members, and
|
|
334
|
+
creates and controls sessions as those users (`asUser`). Do not judge it by
|
|
335
|
+
`/v1/access/me`'s `accountGrants` (`account:read`, `workspace:create`,
|
|
336
|
+
`api_keys:manage`) or its empty `workspaceGrants`: those list account-level
|
|
337
|
+
grants, not what the key may do inside shared workspaces. Check
|
|
338
|
+
`credential.access === "full"` and `credential.effectiveWorkspacePermissions`
|
|
339
|
+
instead; older deployments omit `credential`, so if it is missing, try the call
|
|
340
|
+
(`ensureWorkspace` is idempotent) rather than concluding the key is too weak.
|
|
341
|
+
Only an `access: "read"` key is limited, to reading.
|
|
271
342
|
|
|
272
343
|
For each chosen product sharing boundary, call `ensureWorkspace` /
|
|
273
344
|
`PUT /v1/workspaces/external` with a stable external mapping identity and persist
|
|
@@ -281,20 +352,21 @@ Connections, and integrations: normally one per customer, and a separate one
|
|
|
281
352
|
when groups need different Connections, integrations, or instructions. When
|
|
282
353
|
each end user is their own boundary, a workspace per user (the user id as
|
|
283
354
|
`externalId`) called with the organization key alone is a valid, simpler
|
|
284
|
-
option
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
355
|
+
option; `chats: "isolated"` provisions exactly that per tenant user. Otherwise
|
|
356
|
+
use `asUser(externalId)` for the authenticated product user; the server derives
|
|
357
|
+
the canonical user, so never supply an `endUser` label as authority.
|
|
358
|
+
|
|
359
|
+
Choose chat privacy with `chats` on the proxy or facade: `"private"` (the
|
|
360
|
+
default: only the user sees their chats, the agent reaches only its own session,
|
|
361
|
+
Knowledge goes to the user's personal Knowledge), `"shared"` (the workspace sees
|
|
362
|
+
and shares them), or `"isolated"` (private, in a workspace per tenant user).
|
|
363
|
+
Private chats need the organization's private-session setting; without it the
|
|
364
|
+
SDK throws `OpenGeniSetupError` naming who can enable it. `chats` sets
|
|
365
|
+
`visibility`, `agentAccess` and `memoryScope`, which stay available as explicit
|
|
366
|
+
create fields; private sessions do not make workspace Files or Sites private,
|
|
367
|
+
and removing tools is not a substitute for private visibility. Unscoped
|
|
368
|
+
organization-key-created top-level sessions are workspace-visible. See
|
|
369
|
+
`references/external-users-and-connect.md`.
|
|
298
370
|
|
|
299
371
|
The external backend owns product Skills. Store and version them outside
|
|
300
372
|
OpenGeni, then pass the selected definitions inline in
|
|
@@ -313,8 +385,14 @@ description. Do not replay old headerless Skills as new session input.
|
|
|
313
385
|
|
|
314
386
|
Use each prompt surface for its exact authority and lifetime:
|
|
315
387
|
|
|
316
|
-
-
|
|
317
|
-
|
|
388
|
+
- `agent.identity` (or the workspace's `sessionAgentDefaults.identity`): who the
|
|
389
|
+
agent is. It replaces only OpenGeni's introduction; older workspaces may still
|
|
390
|
+
carry this in `agentInstructions`.
|
|
391
|
+
- Workspace instructions (Knowledge > Instructions in the web app): stable
|
|
392
|
+
workspace-wide rules.
|
|
393
|
+
- Session `instructions` (the same field as `agent.instructions`): durable
|
|
394
|
+
refinement for one session. Instructions take priority over OpenGeni's
|
|
395
|
+
default working style, never over its safety rules or how it runs tools.
|
|
318
396
|
- `modelContext`: ordinary model-visible content attached to one exact user
|
|
319
397
|
message as a separate history part; standard timeline rendering omits it.
|
|
320
398
|
- `initialMessage` and later message text: the visible part of that user message.
|
|
@@ -328,10 +406,11 @@ snapshots, and never move it into instructions.
|
|
|
328
406
|
1. Load the server-held organization API key; resolve the authenticated product
|
|
329
407
|
tenant, call `ensureWorkspace`, and persist the opaque workspace mapping.
|
|
330
408
|
2. Read client config and access context without a Personal-workspace fallback.
|
|
331
|
-
3. Create sessions with
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
409
|
+
3. Create sessions with an explicit `agent` (capabilities and identity chosen
|
|
410
|
+
for the product), the product-selected inline Skills, a stable idempotency
|
|
411
|
+
key (optionally a preallocated ID), canonical resources, and the product's
|
|
412
|
+
own tools. Omitted `agent` inherits the workspace defaults, which are
|
|
413
|
+
normally everything the workspace offers.
|
|
335
414
|
4. Serve the browser through the packaged proxy, or stream/replay through the
|
|
336
415
|
SDK in a custom route; tolerate unknown additive event types.
|
|
337
416
|
5. Send visible text separately from `modelContext`; upload through the SDK
|
|
@@ -2,27 +2,37 @@
|
|
|
2
2
|
|
|
3
3
|
## Minimal agent
|
|
4
4
|
|
|
5
|
-
For a product agent that should only use the product's own tools,
|
|
6
|
-
|
|
5
|
+
For a product agent that should only use the product's own tools, start from
|
|
6
|
+
`"none"` and close the remaining optional surfaces:
|
|
7
7
|
|
|
8
8
|
```ts
|
|
9
9
|
await og.asUser(user.id, { source }).createSession(workspaceId, {
|
|
10
10
|
initialMessage,
|
|
11
11
|
idempotencyKey,
|
|
12
|
+
agent: {
|
|
13
|
+
identity: "You are Acme's ticket assistant.",
|
|
14
|
+
capabilities: { from: "none", humanInput: false, skills: false }, // Acme's tools only
|
|
15
|
+
},
|
|
12
16
|
mcpServers: [{ id: "acme", url: ACME_MCP_URL, allowedTools: ["get_ticket", "update_ticket"] }],
|
|
13
17
|
tools: [{ kind: "mcp", id: "acme" }], // exactly the product's server
|
|
14
|
-
firstPartyMcpTools: [], // no OpenGeni workspace/session tools
|
|
15
18
|
bundledSkillIds: [], // no bundled OpenGeni guidance
|
|
16
19
|
sandboxBackend: "none", // no sandbox, shell, or file tools
|
|
17
20
|
agentLearning: { knowledge: "off", instructions: "off", skills: "off" },
|
|
18
21
|
});
|
|
19
22
|
```
|
|
20
23
|
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
24
|
+
The model then sees the Acme tools and the runtime mechanics (waiting for
|
|
25
|
+
input, titling), and the prompt has no text about goals, Knowledge, subagents
|
|
26
|
+
or repositories. `session.effectiveTools` lists exactly that; see
|
|
27
|
+
[Configure the agent](configure-the-agent.md).
|
|
28
|
+
|
|
29
|
+
On a deployment without agent settings (`agentConfig.enabled` is false in the
|
|
30
|
+
client config) the same request would be refused. Use the older fields there:
|
|
31
|
+
`firstPartyMcpTools: []` instead of `agent`, plus the workspace settings
|
|
32
|
+
`memoryEnabled: false` and `agentHumanInputEnabled: false`. Skill loading,
|
|
33
|
+
model listing and the model provider's native web search then still remain.
|
|
34
|
+
Omitting `tools` or `firstPartyMcpTools` inherits workspace and deployment
|
|
35
|
+
defaults.
|
|
26
36
|
|
|
27
37
|
Tool schemas are prompt cost: one run with 23 MCP tools spent about 35k input
|
|
28
38
|
tokens per turn. Trim with `allowedTools` on each server, and set
|
|
@@ -25,6 +25,8 @@ Only add `x-opengeni-access-key` when the operator says the deployment
|
|
|
25
25
|
shared-key boundary is enabled. It is not a replacement for organization API
|
|
26
26
|
keys in managed SaaS.
|
|
27
27
|
|
|
28
|
+
A full organization API key can provision workspaces, members and asUser sessions; /v1/access/me reports this as credential.effectiveWorkspacePermissions.
|
|
29
|
+
|
|
28
30
|
## Minimal Server-Side Session Client
|
|
29
31
|
|
|
30
32
|
```ts
|
|
@@ -51,7 +53,7 @@ const created = await client.createSession(workspace.id, {
|
|
|
51
53
|
initialMessage: "Inspect the uploaded logs and summarize the failing deploy step.",
|
|
52
54
|
idempotencyKey: crypto.randomUUID(),
|
|
53
55
|
skills,
|
|
54
|
-
|
|
56
|
+
agent: { capabilities: { from: "none", workspaceFiles: true } }, // chosen per product
|
|
55
57
|
tools: selectedIntegrationServers,
|
|
56
58
|
});
|
|
57
59
|
|
|
@@ -86,11 +88,22 @@ workspace for cross-user chat privacy and a per-chat workspace for hard
|
|
|
86
88
|
same-user chat isolation. Knowledge authoring Off does not create either
|
|
87
89
|
boundary.
|
|
88
90
|
|
|
89
|
-
For a headless product, send an explicit
|
|
90
|
-
`tools` selection. Omission inherits
|
|
91
|
+
For a headless product, send an explicit `agent.capabilities` (usually
|
|
92
|
+
`{ from: "none", ... }`) and `tools` selection. Omission inherits the
|
|
93
|
+
workspace defaults. On deployments without agent settings, send an explicit
|
|
94
|
+
minimal `firstPartyMcpTools` instead. Removing
|
|
91
95
|
cross-session tools from a shared workspace is defense in depth, not a hard
|
|
92
96
|
tenant boundary.
|
|
93
97
|
|
|
98
|
+
## Archived session migration
|
|
99
|
+
|
|
100
|
+
For a move from an embedded/in-process runtime to a standalone deployment, use
|
|
101
|
+
the server-only `@opengeni/sdk/session-history-import` functions, not session
|
|
102
|
+
creation plus synthetic Send/Steer calls. Follow
|
|
103
|
+
[Archived session history import](session-history-import.md) for exact mappings,
|
|
104
|
+
file-reference replacement, idempotency and read-only rendering. Imported events
|
|
105
|
+
are historical facts only; they are never model-facing history or live execution.
|
|
106
|
+
|
|
94
107
|
## Automated work
|
|
95
108
|
|
|
96
109
|
Use the server-side `client.asService(name, context?)` for product jobs, bots,
|
|
@@ -142,7 +155,8 @@ model-supplied tenant ID.
|
|
|
142
155
|
|
|
143
156
|
## Runtime Profile And Models
|
|
144
157
|
|
|
145
|
-
Use
|
|
158
|
+
Use `agent.identity` (or the workspace's `sessionAgentDefaults.identity`) for
|
|
159
|
+
who the agent is, workspace instructions for stable workspace rules, session
|
|
146
160
|
`instructions` for one role/conversation, Skills for conditional procedures,
|
|
147
161
|
and `modelContext` for current dashboard or route state. Avoid duplicating one
|
|
148
162
|
policy across all four surfaces.
|
|
@@ -247,6 +261,12 @@ Never distribute an OpenGeni credential to a Connected Machine or try to inject
|
|
|
247
261
|
|
|
248
262
|
## Billing And Limits
|
|
249
263
|
|
|
264
|
+
For per-seat plans, team budgets, administrator splits, and top-ups, read
|
|
265
|
+
[Usage allowances](usage-allowances.md). Amounts are integer USD micros,
|
|
266
|
+
configuration/member writes are versioned, grants are operation-keyed, and
|
|
267
|
+
the conversation proxy exposes only `/usage/me`. Verify actual debit/reset
|
|
268
|
+
and webhook behavior before promising enforcement or notifications.
|
|
269
|
+
|
|
250
270
|
Managed SaaS uses prepaid Stripe credits and local usage/cost accounting. Client behavior should be simple:
|
|
251
271
|
|
|
252
272
|
- Show billing/credit status from `/v1/billing` when the user has billing permission.
|
|
@@ -30,20 +30,39 @@ export const POST = createChatHandler(og, {
|
|
|
30
30
|
return me ? { tenant: me.accountId, user: me.userId } : new Response("Unauthorized", { status: 401 });
|
|
31
31
|
},
|
|
32
32
|
format: "vercel", // or "openai-chat" / "openai-responses"; default: native chunks
|
|
33
|
+
toolParts: true, // optional Vercel activity indicators; off by default
|
|
33
34
|
});
|
|
34
35
|
|
|
35
36
|
const chat = await og.chat({ tenant: "acme", user: "u_42", conversation: "c_9" });
|
|
36
37
|
const reply = await chat.send("hello"); // reply.text; chat.stream(...) yields chunks
|
|
37
38
|
```
|
|
38
39
|
|
|
40
|
+
For the Vercel format, `toolParts: true` emits OpenGeni's tool activity as
|
|
41
|
+
`dynamic`, `providerExecuted` parts, not tools for your app to execute. The
|
|
42
|
+
successful output is only `{ status }`, not the actual result: this opt-in does
|
|
43
|
+
not restore tool results, artifacts or attachments. Leave it off for text-only
|
|
44
|
+
activity. Approval requests are emitted independently of this option (AI SDK
|
|
45
|
+
6+ is needed to answer them). When composing your own AI SDK stream, pass the
|
|
46
|
+
same option to `uiMessageStreamParts(chunks, { framing: false, toolParts: true })`;
|
|
47
|
+
`framing: false` leaves message framing to the outer stream.
|
|
48
|
+
|
|
39
49
|
Each tenant maps to one workspace and each conversation to one deterministic
|
|
40
50
|
session. Conversation IDs are independent of the acting user; authorization
|
|
41
51
|
decides who may use a shared conversation. Without a `user`, `resolve` must
|
|
42
52
|
return the `conversation`. `chatBySessionId` reopens sessions derived with the
|
|
43
|
-
old user-namespaced helper.
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
53
|
+
old user-namespaced helper. `chats` defaults to `"private"` when a `user` is
|
|
54
|
+
given (private visibility, session-only agent reach, the user's personal
|
|
55
|
+
Knowledge; pass `memory: false` to keep Knowledge authoring off). Without a
|
|
56
|
+
user, omitted `chats` keeps workspace visibility, session-only reach and
|
|
57
|
+
Knowledge off; use `chats: "shared"` for service-owned chats. `agent` takes the
|
|
58
|
+
same object as sessions, and the facade's renderer defaults to `"markdown"`
|
|
59
|
+
(only that implicit default is dropped on a server without agent settings).
|
|
60
|
+
`resolve` may return `chats` and `agent` too. See
|
|
61
|
+
[Configure the agent](configure-the-agent.md). The adapters send only the
|
|
62
|
+
latest user message. Earlier messages from your app are imported only when the
|
|
63
|
+
session is first created, as context on its first message; after that OpenGeni
|
|
64
|
+
owns the history, and messages your app shows but never sent are not added.
|
|
65
|
+
They run in the customer's backend: they do not add `/responses` or
|
|
47
66
|
`/chat/completions` to the OpenGeni service. See
|
|
48
67
|
[Compatibility and troubleshooting](compatibility-and-troubleshooting.md) and
|
|
49
68
|
`examples/chat-quickstart`.
|
package/src/bundled_default_skills/opengeni-client/references/compatibility-and-troubleshooting.md
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
Fetch https://docs.opengeni.ai/llms.txt for the official documentation index.
|
|
6
6
|
Read the relevant Markdown page, especially
|
|
7
|
-
https://docs.opengeni.ai/
|
|
7
|
+
https://docs.opengeni.ai/embed-manually.md,
|
|
8
8
|
https://docs.opengeni.ai/reference/authentication.md, and
|
|
9
9
|
https://docs.opengeni.ai/reference/sdk.md. An ordinary customer integration
|
|
10
10
|
does not require a clone of OpenGeni. If a fetch fails, report that source as
|
|
@@ -14,6 +14,39 @@ Documentation availability and deployed feature availability are separate.
|
|
|
14
14
|
Inspect the installed package exports/types and `/v1/config/client`; verify the
|
|
15
15
|
chosen contract against the intended deployment before implementing against it.
|
|
16
16
|
|
|
17
|
+
To check the full Skill's HTTP Markdown export from a repository checkout:
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
bun scripts/check-client-skill-markdown-export.ts
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
This opt-in network check compares the published `.md` sections with the local
|
|
24
|
+
generated mirror, including nested code fences. A mismatch may mean the docs
|
|
25
|
+
deployment has not caught up with the checkout; it is not evidence of a runtime
|
|
26
|
+
API failure. Use `--url` and `--expected` to check another deployment or a known
|
|
27
|
+
matching mirror. The local HTTP regression tests run without external services.
|
|
28
|
+
|
|
29
|
+
## CommonJS hosts
|
|
30
|
+
|
|
31
|
+
The SDK is ESM-only. In an existing `.cjs` host, use dynamic `import()` inside
|
|
32
|
+
an async initializer; `require("@opengeni/sdk")` is not the supported loading
|
|
33
|
+
path. Do not change the entire project's module type just to load the SDK.
|
|
34
|
+
|
|
35
|
+
```js
|
|
36
|
+
// opengeni.cjs — callers await createOpenGeniClient().
|
|
37
|
+
async function createOpenGeniClient() {
|
|
38
|
+
const { OpenGeniClient } = await import("@opengeni/sdk");
|
|
39
|
+
return new OpenGeniClient({
|
|
40
|
+
baseUrl: process.env.OPENGENI_API_BASE_URL,
|
|
41
|
+
apiKey: process.env.OPENGENI_API_KEY,
|
|
42
|
+
});
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
module.exports = { createOpenGeniClient };
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Keep this initialization on the server: never send the API key to a browser.
|
|
49
|
+
|
|
17
50
|
## Decide what is being replaced
|
|
18
51
|
|
|
19
52
|
| Customer dependency | Evidence needed |
|