@opengeni/core 2.9.3 → 2.9.4-canary.0

package/dist/index.js

@@ -4110,7 +4110,7 @@ var productIntegrationSkillFiles = [
   },
   {
     "path": "references/product-shapes-and-ui.md",
-    "content": "# Product shapes and UI\n\n## Choose the smallest suitable surface\n\nOpenGeni supports several product shapes. Select from the product experience and host stack rather than assuming every integration needs a custom chat:\n\n| Need | Likely surface | Product owns |\n| --- | --- | --- |\n| The complete OpenGeni experience is acceptable | Link or deep-link to stock OpenGeni | Entry point and product navigation |\n| Custom UI in any framework, mobile app, CLI, or automation | OpenGeni SDK or public API behind product backend | All user-facing presentation |\n| React product wants canonical session state without packaged visuals | Headless React session hooks and projections | Components, layout, and styling |\n| React product wants packaged chat/session controls | Focused styled React subpaths | Shell, domain UI, and theming |\n| Product exposes files, changes, terminal, or desktop compute | Optional workbench surfaces | Product shell and selected tabs |\n\nStart with the narrowest surface that preserves the desired experience. Do not mount the full workbench for an ordinary analytics chat. Do not rebuild session streaming, replay, queueing, approval, or timeline projection when a compatible package already supplies the needed behavior.\n\n## Evaluate reuse before writing chat UI\n\nFor React hosts, inspect the installed OpenGeni React package before creating replacement components. Its subpaths are composable, and the styled surfaces use scoped compiled CSS plus runtime theme and density tokens. Compare:\n\n- packaged components with customer theme tokens;\n- headless hooks with customer-native components; and\n- a fully custom SDK-driven UI.\n\nChoose based on UX requirements and dependency compatibility, then record why. Styling differences alone are not a reason to skip reusable components if their structure fits. Conversely, do not force a packaged component when the product needs a materially different interaction model.\n\nFor Svelte, SvelteKit, Vue, native mobile, or another non-React frontend, use the product's native component system. Keep the privileged OpenGeni client on a compatible backend boundary. A SvelteKit server route may use the TypeScript SDK directly; a non-JavaScript backend may use the public HTTP contract or a small compatible adapter. The browser still speaks to authenticated product routes.\n\n## Browser/backend split\n\nThe product browser normally sends product-shaped requests to its own same-origin backend. The backend authenticates, resolves the allowed mapping, and calls OpenGeni. Never bundle an organization key into frontend code.\n\nFor live sessions, preserve event sequence, reconnect, replay, and duplicate suppression. The SDK's stream and proxy helpers are preferred where compatible. Treat unknown additive event types as forward-compatible data rather than crashing the UI.\n\nUploads may send bytes directly to a short-lived signed storage URL returned by the trusted flow. That URL is narrow transfer authority, not the OpenGeni API key. Verify storage CORS for every intended browser origin.\n\n## Decide what the user sees\n\nOpenGeni's durable event stream can support different product projections:\n\n- final answer only;\n- assistant messages plus progress and status;\n- selected tool-call summaries;\n- approvals and structured human-input cards; or\n- a detailed operational timeline.\n\nThe customer frontend chooses which event types and fields to render. Hiding an event from the chat view does not remove it from OpenGeni's durable history or from authorized audit readers. Do not promise data erasure or secrecy from presentation filtering.\n\nEven a final-answer-only UI should surface states the user must act on: failure, cancellation, credit or policy denial, approval requests, human-input requests, reconnect status, and a way to retry safely. Avoid presenting tool failures as ordinary assistant prose when product state can represent them more clearly.\n\n## Fit the host product\n\nFollow existing navigation, accessibility, responsive, loading, error, observability, localization, and design-system conventions. Keep OpenGeni IDs behind product-native identifiers. Make the smallest dependency addition that improves correctness.\n\nThe integration should feel native to the customer product while retaining OpenGeni's session semantics. Framework adaptation is expected; protocol reimplementation is not a goal.\n"
+    "content": "# Opening host-owned workbench tabs\n\nUse `SandboxWorkspace.openTabRequest={{ tab, requestId }}` to open a built-in or\nhost-injected tab from the host's UI. Increment `requestId` for each intentional\nopen, including repeated clicks on the same item. Keep artifact selection and\ninternal-link recognition in the host; the workbench only selects an available\ntab and expands the dock. Preserve modified clicks and external navigation.\nWhen handing off to a full-page artifact route, retain an explicit originating\nsession return path rather than relying on browser history.\n\n# Product shapes and UI\n\n## Choose the smallest suitable surface\n\nOpenGeni supports several product shapes. Select from the product experience and host stack rather than assuming every integration needs a custom chat:\n\n| Need | Likely surface | Product owns |\n| --- | --- | --- |\n| The complete OpenGeni experience is acceptable | Link or deep-link to stock OpenGeni | Entry point and product navigation |\n| Custom UI in any framework, mobile app, CLI, or automation | OpenGeni SDK or public API behind product backend | All user-facing presentation |\n| React product wants canonical session state without packaged visuals | Headless React session hooks and projections | Components, layout, and styling |\n| React product wants packaged chat/session controls | Focused styled React subpaths | Shell, domain UI, and theming |\n| Product exposes files, changes, terminal, or desktop compute | Optional workbench surfaces | Product shell and selected tabs |\n\nStart with the narrowest surface that preserves the desired experience. Do not mount the full workbench for an ordinary analytics chat. Do not rebuild session streaming, replay, queueing, approval, or timeline projection when a compatible package already supplies the needed behavior.\n\n## Evaluate reuse before writing chat UI\n\nFor React hosts, inspect the installed OpenGeni React package before creating replacement components. Its subpaths are composable, and the styled surfaces use scoped compiled CSS plus runtime theme and density tokens. Compare:\n\n- packaged components with customer theme tokens;\n- headless hooks with customer-native components; and\n- a fully custom SDK-driven UI.\n\nChoose based on UX requirements and dependency compatibility, then record why. Styling differences alone are not a reason to skip reusable components if their structure fits. Conversely, do not force a packaged component when the product needs a materially different interaction model.\n\nFor Svelte, SvelteKit, Vue, native mobile, or another non-React frontend, use the product's native component system. Keep the privileged OpenGeni client on a compatible backend boundary. A SvelteKit server route may use the TypeScript SDK directly; a non-JavaScript backend may use the public HTTP contract or a small compatible adapter. The browser still speaks to authenticated product routes.\n\n## Browser/backend split\n\nThe product browser normally sends product-shaped requests to its own same-origin backend. The backend authenticates, resolves the allowed mapping, and calls OpenGeni. Never bundle an organization key into frontend code.\n\nFor live sessions, preserve event sequence, reconnect, replay, and duplicate suppression. The SDK's stream and proxy helpers are preferred where compatible. Treat unknown additive event types as forward-compatible data rather than crashing the UI.\n\nUploads may send bytes directly to a short-lived signed storage URL returned by the trusted flow. That URL is narrow transfer authority, not the OpenGeni API key. Verify storage CORS for every intended browser origin.\n\n## Decide what the user sees\n\nOpenGeni's durable event stream can support different product projections:\n\n- final answer only;\n- assistant messages plus progress and status;\n- selected tool-call summaries;\n- approvals and structured human-input cards; or\n- a detailed operational timeline.\n\nThe customer frontend chooses which event types and fields to render. Hiding an event from the chat view does not remove it from OpenGeni's durable history or from authorized audit readers. Do not promise data erasure or secrecy from presentation filtering.\n\nEven a final-answer-only UI should surface states the user must act on: failure, cancellation, credit or policy denial, approval requests, human-input requests, reconnect status, and a way to retry safely. Avoid presenting tool failures as ordinary assistant prose when product state can represent them more clearly.\n\n## Fit the host product\n\nFollow existing navigation, accessibility, responsive, loading, error, observability, localization, and design-system conventions. Keep OpenGeni IDs behind product-native identifiers. Make the smallest dependency addition that improves correctness.\n\nThe integration should feel native to the customer product while retaining OpenGeni's session semantics. Framework adaptation is expected; protocol reimplementation is not a goal.\n"
   },
   {
     "path": "references/runtime-profile-and-verification.md",