@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.
Files changed (117) hide show
  1. package/dist/agent-instructions/base-behavior.d.ts +8 -0
  2. package/dist/agent-instructions/compose.d.ts +59 -0
  3. package/dist/agent-instructions/identity.d.ts +21 -0
  4. package/dist/agent-instructions/index.d.ts +6 -0
  5. package/dist/agent-instructions/modules/admin.d.ts +3 -0
  6. package/dist/agent-instructions/modules/artifacts.d.ts +7 -0
  7. package/dist/agent-instructions/modules/attachments.d.ts +3 -0
  8. package/dist/agent-instructions/modules/environment.d.ts +11 -0
  9. package/dist/agent-instructions/modules/goals.d.ts +3 -0
  10. package/dist/agent-instructions/modules/knowledge.d.ts +6 -0
  11. package/dist/agent-instructions/modules/machines.d.ts +3 -0
  12. package/dist/agent-instructions/modules/renderer-markdown.d.ts +6 -0
  13. package/dist/agent-instructions/modules/repositories.d.ts +7 -0
  14. package/dist/agent-instructions/modules/sandbox.d.ts +3 -0
  15. package/dist/agent-instructions/modules/skills.d.ts +3 -0
  16. package/dist/agent-instructions/modules/subagents.d.ts +3 -0
  17. package/dist/agent-instructions/runtime-mechanics.d.ts +7 -0
  18. package/dist/agent-instructions/types.d.ts +55 -0
  19. package/dist/assets/codemode-client.json +1 -1
  20. package/dist/{chunk-JUFVYQCY.js → chunk-VDXKKMMD.js} +457 -165
  21. package/dist/chunk-VDXKKMMD.js.map +1 -0
  22. package/dist/{chunk-22M75RJF.js → chunk-ZY655LYR.js} +1636 -709
  23. package/dist/chunk-ZY655LYR.js.map +1 -0
  24. package/dist/claude-subscription-usage.d.ts +3 -1
  25. package/dist/first-party-client.d.ts +1 -0
  26. package/dist/index.d.ts +37 -28
  27. package/dist/index.js +28 -2
  28. package/dist/input-wait-yield.d.ts +4 -0
  29. package/dist/interaction-tools.d.ts +1 -0
  30. package/dist/lazy-tool-transport.d.ts +6 -2
  31. package/dist/mcp-run-credentials.d.ts +3 -2
  32. package/dist/mcp-transport-logger.d.ts +10 -0
  33. package/dist/model-context-inspector.d.ts +17 -1
  34. package/dist/model-preparation-diagnostics.d.ts +9 -0
  35. package/dist/model-provider-routing.d.ts +4 -0
  36. package/dist/model-provider.d.ts +1 -0
  37. package/dist/model-request-capture.d.ts +9 -0
  38. package/dist/replayable-json-body.d.ts +2 -1
  39. package/dist/responses-terminal-error.d.ts +17 -0
  40. package/dist/sandbox/codemode-authority.d.ts +1 -0
  41. package/dist/sandbox/index.d.ts +3 -3
  42. package/dist/sandbox/index.js +5 -1
  43. package/dist/sandbox/provider-command-session.d.ts +6 -0
  44. package/dist/sandbox/providers/modal-command-control.d.ts +7 -0
  45. package/dist/sandbox/providers/modal-command-router-wire.d.ts +8 -0
  46. package/dist/sandbox/providers/modal-command-session.d.ts +2 -1
  47. package/dist/sandbox/providers/modal-command-start-errors.d.ts +9 -0
  48. package/dist/sandbox/providers/modal.d.ts +3 -0
  49. package/dist/sandbox/routing/routing-session.d.ts +5 -4
  50. package/dist/workspace-tool-gateway.js +2 -2
  51. package/package.json +12 -12
  52. package/src/agent-instructions/PROMPT_CHANGELOG.md +149 -0
  53. package/src/agent-instructions/base-behavior.ts +120 -0
  54. package/src/agent-instructions/compose.ts +153 -0
  55. package/src/agent-instructions/identity.ts +42 -0
  56. package/src/agent-instructions/index.ts +24 -0
  57. package/src/agent-instructions/modules/admin.ts +25 -0
  58. package/src/agent-instructions/modules/artifacts.ts +39 -0
  59. package/src/agent-instructions/modules/attachments.ts +12 -0
  60. package/src/agent-instructions/modules/environment.ts +60 -0
  61. package/src/agent-instructions/modules/goals.ts +15 -0
  62. package/src/agent-instructions/modules/knowledge.ts +21 -0
  63. package/src/agent-instructions/modules/machines.ts +17 -0
  64. package/src/agent-instructions/modules/renderer-markdown.ts +17 -0
  65. package/src/agent-instructions/modules/repositories.ts +28 -0
  66. package/src/agent-instructions/modules/sandbox.ts +63 -0
  67. package/src/agent-instructions/modules/skills.ts +19 -0
  68. package/src/agent-instructions/modules/subagents.ts +42 -0
  69. package/src/agent-instructions/runtime-mechanics.ts +55 -0
  70. package/src/agent-instructions/types.ts +83 -0
  71. package/src/bundled_default_skills/opengeni-client/SKILL.md +116 -37
  72. package/src/bundled_default_skills/opengeni-client/references/agent-recipes.md +18 -8
  73. package/src/bundled_default_skills/opengeni-client/references/api-workflows.md +24 -4
  74. package/src/bundled_default_skills/opengeni-client/references/chat-facade-fallback.md +23 -4
  75. package/src/bundled_default_skills/opengeni-client/references/compatibility-and-troubleshooting.md +34 -1
  76. package/src/bundled_default_skills/opengeni-client/references/configure-the-agent.md +248 -0
  77. package/src/bundled_default_skills/opengeni-client/references/customer-skill-template.md +2 -1
  78. package/src/bundled_default_skills/opengeni-client/references/data-tools-and-credentials.md +15 -4
  79. package/src/bundled_default_skills/opengeni-client/references/discovery-and-autonomy.md +2 -2
  80. package/src/bundled_default_skills/opengeni-client/references/isolation-and-authorization.md +5 -3
  81. package/src/bundled_default_skills/opengeni-client/references/product-integration-shapes.md +6 -5
  82. package/src/bundled_default_skills/opengeni-client/references/product-shapes-and-ui.md +36 -3
  83. package/src/bundled_default_skills/opengeni-client/references/proxy-from-any-backend.md +170 -0
  84. package/src/bundled_default_skills/opengeni-client/references/session-history-import.md +147 -0
  85. package/src/bundled_default_skills/opengeni-client/references/usage-allowances.md +189 -0
  86. package/src/bundled_default_skills/opengeni-help/SKILL.md +1 -1
  87. package/src/claude-subscription-usage.ts +23 -4
  88. package/src/first-party-client.ts +4 -0
  89. package/src/index.ts +260 -146
  90. package/src/input-wait-yield.ts +7 -0
  91. package/src/interaction-tools.ts +16 -2
  92. package/src/lazy-tool-transport.ts +46 -16
  93. package/src/mcp-run-credentials.ts +18 -3
  94. package/src/mcp-transport-logger.ts +46 -0
  95. package/src/model-context-inspector.ts +37 -3
  96. package/src/model-preparation-diagnostics.ts +48 -1
  97. package/src/model-provider-client.ts +5 -1
  98. package/src/model-provider-routing.ts +95 -1
  99. package/src/model-provider.ts +1 -0
  100. package/src/model-request-capture.ts +28 -1
  101. package/src/provider-history-adapter.ts +24 -3
  102. package/src/replayable-json-body.ts +19 -2
  103. package/src/responses-terminal-error.ts +136 -0
  104. package/src/sandbox/codemode-authority.ts +4 -0
  105. package/src/sandbox/codemode-client.ts +18 -16
  106. package/src/sandbox/index.ts +45 -9
  107. package/src/sandbox/provider-command-session.ts +12 -0
  108. package/src/sandbox/providers/modal-command-control.ts +118 -12
  109. package/src/sandbox/providers/modal-command-router-wire.ts +40 -4
  110. package/src/sandbox/providers/modal-command-session.ts +36 -1
  111. package/src/sandbox/providers/modal-command-start-errors.ts +27 -0
  112. package/src/sandbox/providers/modal-legacy-command-control.ts +60 -30
  113. package/src/sandbox/providers/modal.ts +43 -2
  114. package/src/sandbox/routing/routing-session.ts +61 -6
  115. package/src/sandbox/turn-tool-cancellation.ts +8 -1
  116. package/dist/chunk-22M75RJF.js.map +0 -1
  117. 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. Not for
10
- changing OpenGeni internals or mounting its runtime inside the customer's
11
- process.
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, authentication, tenancy, data routes,
47
- frontend conventions, installed packages, tests, CI, and deployment guidance
48
- before asking questions or choosing an integration shape.
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 (a per-user or shared agent
56
- and chats), when things run (schedule and time zone), where outputs land
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: `@opengeni/react`'s
74
- `OpenGeniChat` (the user's chat list plus `SessionConversation`) and
75
- `@opengeni/react/compiled.css` (brand it with `--og-*` tokens), backed by the
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 adapters. It already provides streaming, replay, queue, steer, approvals,
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
- The organization key needs `workspace:admin` (included in full-access keys;
269
- it implies session, file, MCP-attach, and member management). `/v1/access/me`
270
- shows only that account-level grant; an empty `workspaceGrants` is expected.
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. Otherwise use `asUser(externalId)` for the authenticated product user; the server derives the
285
- canonical user, so never supply an `endUser` label as authority. Human
286
- visibility is `visibility` (verified external owners can create private sessions
287
- when the organization enables it; private sessions do not make workspace Files
288
- or Sites private). `agentAccess: "session" | "user" | "workspace"` separately
289
- limits outbound agent reach; the target's `agentAccess` never restricts inbound
290
- access, and removing tools is not a substitute for private visibility.
291
- Compatibility `memoryScope: "workspace" | "user" | "off"` selects Knowledge
292
- authoring scope, not transcript visibility; Off leaves authorized retrieval
293
- available, and personal Knowledge belongs to the verified user of the active
294
- turn. Use task notes for temporary session-tree coordination; there is no
295
- active session Memory scope. Unscoped organization-key-created top-level
296
- sessions are workspace-visible, and managed-human Only-me sessions are not a
297
- backend impersonation mechanism. See `references/external-users-and-connect.md`.
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
- - Workspace `agentInstructions`: stable workspace-wide system persona and behavior.
317
- - Session `instructions`: durable system-level agent refinement for one session.
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 the product-selected inline Skills, a stable idempotency
332
- key (optionally a preallocated ID), canonical resources, and an explicit
333
- minimal tool selection. Omitted tool selections inherit workspace/deployment
334
- defaults, including first-party workspace and cross-session capabilities.
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, create the
6
- session with every optional surface closed:
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
- Workspace settings close two more: `memoryEnabled: false` (Memory tools) and
22
- `agentHumanInputEnabled: false` (structured questions). What always remains:
23
- skill loading and model listing, plus the model provider's native web search
24
- where the model supports it. Omitting `tools` or `firstPartyMcpTools` instead
25
- of passing them inherits workspace and deployment defaults.
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
- firstPartyMcpTools: selectedFirstPartyTools,
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 minimal `firstPartyMcpTools` and
90
- `tools` selection. Omission inherits deployment/workspace defaults. Removing
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 workspace `agentInstructions` for stable workspace behavior, session
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. The facade defaults to `agentAccess: "session"` and
44
- `memory: false`. The adapters send only the latest user message and import
45
- earlier messages once as first-message context; afterwards OpenGeni owns the
46
- history. They run in the customer's backend: they do not add `/responses` or
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`.
@@ -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/guides/integrate-your-product.md,
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 |