@opengeni/runtime 3.0.1 → 4.0.0

package/src/bundled_default_skills/opengeni-client/SKILL.md

@@ -0,0 +1,349 @@
+---
+name: opengeni-client
+audience: integration-agent
+description: >-
+  Integrate OpenGeni capabilities into an external product, website, backend,
+  CLI, or automation. Use for discovery, connecting repositories and resources,
+  SDK/API and React choices, implementation, verification, and handoff against
+  a managed, self-hosted, or local OpenGeni deployment. Not for changing
+  OpenGeni internals or mounting its runtime inside the customer's process.
+---
+
+# OpenGeni Client
+
+Use this skill when a customer's product and OpenGeni remain separate systems.
+That is the normal integration shape: the product owns its users and business
+UI, while a standalone OpenGeni deployment owns agent sessions and execution.
+
+Do not interpret "embed" as "move OpenGeni into the product process." Advanced
+in-process router/core embedding is a separate infrastructure choice. Route that
+work to the repo-maintainer `opengeni` skill and `docs/embedding.md`.
+
+Do not confuse two meanings of "skill": this file teaches a customer's coding
+agent how to integrate OpenGeni; session `skills` are runtime capabilities or
+instructions attached to an OpenGeni agent. The former designs the integration.
+The latter is product data sent through the installed SDK contract.
+
+Code and the live service are authoritative. Prefer `/v1/config/client`,
+`/v1/access/me`, the installed package types, and live probes over memorized
+route, model, tool, or backend lists. When source is available, verify exact
+behavior in `packages/sdk`, `packages/react`, contracts, and API routes.
+Read `docs/product-integration.md` when the repository is available; it is the
+canonical product boundary for organization keys, workspace mapping, and Skill
+ownership.
+
+Without repository access, start at https://docs.opengeni.ai/llms.txt and fetch
+the relevant Markdown pages. Before replacing an AI provider, answering a cost
+question, or reporting a setup blocker, read
+[Compatibility and troubleshooting](references/compatibility-and-troubleshooting.md).
+
+## Work Adaptively
+
+This same guide is bundled as `builtin:opengeni-client` in ordinary OpenGeni
+sessions and lives in `.agents/skills/opengeni-client` for external coding agents.
+No Pack, installation, repository clone, or sandbox is needed to read the bundled
+copy. It is guidance, not authority to access a repository, secret, or deployment.
+Embedded products may narrow bundled guidance with `bundledSkillIds`.
+
+- Inspect the customer's repository, authentication, tenancy, data routes,
+  frontend conventions, installed packages, tests, CI, and deployment guidance
+  before asking questions or choosing an integration shape.
+- If the target repository or resources are missing, first inspect available
+  authorized resources and connection/setup tools. Help the user connect or
+  attach the specific missing source; explain the next action in product terms.
+  Continue useful discovery without requesting broad credentials or pretending
+  missing access is configured. Read
+  [Discovery and autonomy](references/discovery-and-autonomy.md) for that workflow.
+- Ask only for consequential product choices or external authority that cannot
+  be inferred. Do not ask the customer to restate facts the system proves.
+- Use a reversible, clearly stated default when an unresolved choice is
+  low-risk. Resolve privacy, tenant authority, data writes, cost exposure, and
+  ambiguous external mutations before crossing those boundaries.
+- Match the requested delivery autonomy. Repository or cloud access is
+  technical capability, not permission to push, deploy, merge, or change
+  production.
+- This Skill guides an implementation agent. Never copy it into the runtime
+  Skills of the customer-facing agent.
+
+## Choose the product experience before the transport
+
+Read [Product shapes and UI](references/product-shapes-and-ui.md) when adding
+or changing a user-facing surface. Preserve a suitable existing interface;
+for new React chat, evaluate the packaged components and headless hooks before
+writing replacements. The chat facade below serves compatible/custom clients;
+packaged React conversation components use the normal session SDK and authenticated
+proxy routes. Choose the combination that fits the product, not the shortest snippet.
+
+Read [Integration configuration and verification](references/runtime-profile-and-verification.md)
+when defining agent behavior or verifying delivery. Use representative product
+questions to check useful answers and actual tool execution, not just connectivity.
+
+## Chat facade: `@opengeni/sdk/chat`
+
+When using `user`, first provision that user's approved workspace membership
+through the explicit onboarding flow in `references/external-users-and-connect.md`.
+The facade uses `asUser()` and never grants or restores membership on a chat
+request. An existing tenant is not proof that this user belongs to it. For shared
+conversations use the same OpenGeni session ID; identity changes authority, not
+the conversation address. Use `chatBySessionId` to reopen historical sessions
+whose IDs were derived with the old user-namespaced helper.
+
+Use this when the chosen frontend speaks one of the supported chat protocols
+and OpenGeni should sit behind it. Install, keep the organization API key on the
+server, and put one handler behind the chat endpoint:
+
+```bash
+bun add @opengeni/sdk
+```
+
+```ts
+import { OpenGeni, createChatHandler } from "@opengeni/sdk/chat";
+
+const og = new OpenGeni({
+  apiKey: process.env.OPENGENI_API_KEY!,
+  organizationId: process.env.OPENGENI_ORGANIZATION_ID!,
+});
+
+export const POST = createChatHandler(og, {
+  // Your auth hook. Tenant and user come from the authenticated request, never the body.
+  resolve: async (request) => {
+    const me = await authenticate(request);
+    return me ? { tenant: me.accountId, user: me.userId } : new Response("Unauthorized", { status: 401 });
+  },
+  // format: "vercel" keeps an existing useChat client; "openai-chat" / "openai-responses"
+  // keep an OpenAI-shaped client. The default streams native chunks for custom clients.
+});
+
+// Server-side use without an endpoint:
+const chat = await og.chat({ tenant: "acme", user: "u_42", conversation: "c_9" });
+const reply = await chat.send("hello"); // reply.text; chat.stream(...) yields chunks
+```
+
+Browser: use a custom or compatible frontend for the backend chat handler.
+For native OpenGeni React UI, install `@opengeni/react` and use
+`SessionConversation` or compose `MessageTimeline` and `ChatComposer` with
+the normal SDK and authenticated session routes. Reset private UI state and cancel old
+requests when the authenticated user or tenant changes. Every customer gets one workspace (`tenant`), every
+conversation one deterministic session, and each session picks its own
+isolation. Conversation IDs are independent of the acting user; ordinary API
+authorization decides who can use the same shared conversation. Without a `user`,
+`resolve` must return the `conversation` itself. The Vercel and OpenAI adapters
+send only the latest user message and import earlier messages once as context
+on the first message; afterwards OpenGeni owns the history.
+
+| Scenario | `agentAccess` | `memory` |
+| --- | --- | --- |
+| Support desk: agent confined to its chat tree | `"session"` (default) | `false` (default) |
+| Agents restricted to their canonical user's chats | `"user"` with `asUser()` | `"user"` |
+| A team collaborating across chats | `"workspace"` | `"workspace"` |
+| Any of the above with Knowledge authoring initially Off | any | `false` |
+
+`agentAccess` is enforced in the server-side session-authorization seam for
+agents as outbound task scope: own tree, same canonical user, or workspace.
+A narrow target remains reachable by an authorized broad coordinator; target
+private visibility and normal permissions still apply. `asUser()` establishes
+canonical authority, not a second end-user label. Graduate to `og.client`
+(`OpenGeniClient`) on the same `chat.sessionId` when the product needs files,
+tools, approval policies, forks, or realtime voice. The
+`examples/chat-quickstart` directory provides a backend-only server example.
+
+## Choose The Integration Shape First
+
+Pick the smallest surface that satisfies the product:
+
+1. **Stock OpenGeni handoff** — link or deep-link into the OpenGeni web app.
+   The product keeps no agent UI.
+2. **Headless product integration** — the product backend uses
+   `@opengeni/sdk`; the product renders its own UI and exposes tenant-scoped,
+   same-origin routes to its browser or mobile client.
+3. **React session integration** — compose `@opengeni/react/session` hooks and
+   pure projections into the product's UI. Add styled subpaths only for the
+   surfaces the product wants.
+4. **OpenGeni-rendered React experience** — mount the packaged composer,
+   timeline, realtime, or session chrome and import
+   `@opengeni/react/compiled.css` once. No Tailwind setup or source scan is
+   required. Override `--og-*` tokens only when branding is wanted.
+5. **Workbench integration** — mount the optional Changes/Files/Terminal/Desktop
+   workspace when the product genuinely exposes agent compute. It has optional
+   heavy peers and is not required for ordinary chat/session integration.
+
+Read `references/product-integration-shapes.md` before designing the boundary.
+Read `references/api-workflows.md` for session, upload, retry, repository,
+machine, and schedule patterns.
+
+For deeper implementation decisions, read selectively:
+
+- [Discovery and autonomy](references/discovery-and-autonomy.md)
+- [Isolation and authorization](references/isolation-and-authorization.md)
+- [Product shapes and UI](references/product-shapes-and-ui.md)
+- [Data tools and credentials](references/data-tools-and-credentials.md)
+- [Integration configuration and verification](references/runtime-profile-and-verification.md)
+- [External users and embedded connection setup](references/external-users-and-connect.md)
+
+This tree is the canonical developer guide for product integration. It does not define a runtime
+profile API, schedule Skill fields, or a new registry. Any references to an
+integration's "runtime profile" mean configuration owned by the customer's code,
+not a new OpenGeni resource. Use this Skill for a coding session, not an end-user
+runtime session.
+
+## Choose The Credential
+
+- Use an **organization API key** when one server-side product integration
+  provisions or manages many organization workspaces in one OpenGeni
+  organization.
+- Use a **workspace API key** when the integration is deliberately constrained
+  to one organization workspace and should not provision others.
+- Use a **delegated token** when the host acts with short-lived, explicit
+  user/workspace authority rather than one standing product credential.
+- A **deployment access key** is a coarse deployment perimeter. Never use it as
+  tenant identity or infer organization/workspace authority from it.
+
+## Default Trust Boundary
+
+- Keep the organization API key and operator credentials on the product server.
+- Authenticate the product's user first, resolve their allowed OpenGeni
+  workspace/session server-side, and expose only the routes that product needs.
+- Use `@opengeni/sdk` instead of reconstructing event streaming, upload signing,
+  retries, or wire types by hand.
+- Use `proxySessionEventStream` for a same-origin browser SSE route. Structural
+  React client types let a host implement only the methods its mounted hooks use.
+- Direct browser access is valid only when the deployment's normal browser auth
+  or an explicitly accepted bearer/CORS design makes it safe. Never ship a
+  privileged shared API key in a browser bundle.
+
+The product owns external identity, tenant-to-workspace mapping, business
+entities, navigation, presentation, and product-specific admission. OpenGeni
+owns sessions, turns, durable event history, approvals, agent execution,
+selected tools/resources, files, realtime session state, and compute lifecycle.
+Link records by opaque IDs; do not copy one system's whole data model into the
+other.
+
+## Organization And Workspace Bootstrap
+
+Use one organization API key for the external backend. Organization key
+administration is exposed through `listOrganizationApiKeys`,
+`createOrganizationApiKey`, and `deleteOrganizationApiKey`, corresponding to
+the organization-scoped `/v1/organizations/:organizationId/api-keys` routes.
+The create response shows the token once; store it only in the product's secret
+manager.
+
+For each chosen product sharing boundary, call `ensureWorkspace` /
+`PUT /v1/workspaces/external` with a stable external mapping identity and persist
+the returned `result.workspace.id`; `result.created` distinguishes the first
+insert from an idempotent replay. Call it an **organization workspace** in
+customer guidance; its exact wire kind is `"shared"`. Personal workspaces are
+excluded and must never be selected through a default-workspace fallback.
+
+Choose the workspace from who shares documents, workspace instructions,
+Connections, and integrations: normally one workspace per customer. Chat
+human visibility is controlled by `visibility`, not by `agentAccess` or Knowledge.
+Use `asUser(externalId)` for the authenticated product user. The server derives
+the canonical user; never supply an `endUser` label as authority. Separately,
+`agentAccess: "session" | "user" | "workspace"` controls cross-session agent
+reach. Compatibility `memoryScope: "workspace" | "user" | "off"` selects Knowledge
+authoring scope, not transcript visibility. Off initializes authoring to Off;
+existing authorized Knowledge remains retrievable. Personal Knowledge belongs
+to the verified user of the active
+turn, including when different users collaborate in one shared session. Use
+existing task notes for temporary session-tree coordination; there is no active
+session Memory scope. Use a separate workspace when groups need different
+Connections, integrations, or instructions.
+
+Unscoped organization-key-created top-level sessions are workspace-visible.
+For product-user ownership, use the server-side `asUser(externalId)` client and
+explicit workspace membership described in `references/external-users-and-connect.md`;
+verified external owners can create private sessions when the organization enables
+that feature. Private sessions do not make workspace Files or Sites private.
+Managed-human Only-me sessions are not a backend impersonation mechanism. A live
+agent with cross-session tools can reach unrelated sessions only when its
+outbound `agentAccess` scope and ordinary resource authorization allow it.
+The target's `agentAccess` never restricts inbound access; private-session
+ownership and ordinary permissions still apply.
+Removing tools is not a substitute for private human visibility.
+
+The external backend owns product Skills. Store and version them outside
+OpenGeni, then pass the selected definitions inline in
+`CreateSessionRequest.skills` for each product-created session. There is no
+organization-wide Skill registry or Skill inheritance in this integration
+contract.
+
+Use `CreateSessionRequest.bundledSkillIds` to narrow OpenGeni's bundled guidance
+independently: omitted means defaults, `[]` means none, and explicit IDs such as
+`builtin:opengeni-documents` allow only those whose normal inclusion rules hold.
+Children inherit and can only narrow; scheduled-task `agentConfig` and automation
+`sessionTemplate` accept the same field. This does not hide workspace or inline
+Skills, grant tools, or disable eager `skill_read`. Keep the selection stable on
+keyed-create retries. Never try to control it through arbitrary session metadata.
+
+New Skill inputs require valid `SKILL.md` frontmatter, which owns the name and
+description. Do not replay old headerless Skills as new session input.
+
+## Prompt And Context Contract
+
+Use each prompt surface for its exact authority and lifetime:
+
+- Workspace `agentInstructions`: stable workspace-wide system persona and behavior.
+- Session `instructions`: durable system-level agent refinement for one session.
+- `modelContext`: ordinary model-visible content attached to one exact user
+  message as a separate history part; standard timeline rendering omits it.
+- `initialMessage` and later message text: the visible part of that user message.
+
+`modelContext` is not secret, private, or privileged; full event/audit reads may
+return it. Do not hide business facts in a snapshot when the agent should inspect
+them with an authorized product MCP tool. Prefer concise message context plus
+canonical tool access. Changing `modelContext` must not change the persistent
+agent instruction prefix.
+
+## Client Workflow
+
+1. Resolve the API base URL and load the server-held organization API key.
+2. Resolve the authenticated product tenant, call `ensureWorkspace` with its
+   stable external identity, and persist or verify the opaque workspace mapping.
+3. Read client config and access context without falling back to a Personal
+   workspace.
+4. Load the exact Skills selected by the external product and pass them inline.
+5. Create a session with a stable idempotency key; optionally preallocate its ID
+   when the product must persist a link before the first turn can run.
+6. Attach only canonical resources and an explicit minimal tool selection the
+   user may use. Omitting tool selections inherits workspace/deployment
+   defaults, including first-party workspace and cross-session capabilities.
+7. Stream/replay session events through the SDK; tolerate unknown additive event
+   types.
+8. Send visible text separately from `modelContext`.
+9. Use the SDK upload helper; it owns begin, signed storage PUT, and completion.
+10. Surface approvals, human-input requests, queue state, errors, credit limits,
+   and reconnect state as product state rather than generic chat text.
+11. Add realtime, Connected Machines, schedules, or the workbench only when the
+   product use case needs them.
+
+## Guardrails
+
+- Workspace-scoped routes are canonical; resource IDs never authorize by
+  themselves.
+- Organization workspaces have wire `kind: "shared"`; Personal workspaces are
+  outside the external product mapping.
+- Use one workspace per customer and private/shared visibility for human
+  access. Knowledge settings and prompt instructions do not create a tenant boundary.
+  `agentAccess` optionally restricts agent reach further; tool removal is
+  defense in depth, not a replacement for authorization.
+- Use separate workspaces only when groups must not share documents,
+  Connections, integrations, or workspace instructions.
+- Do not invent an organization-wide Skill registry or rely on Skill
+  inheritance. The external backend passes selected Skills inline per session.
+- The SDK cannot accept arbitrary customer backend functions as remote tools.
+  Expose an existing API through a reviewed OpenAPI/GraphQL Integration or an
+  MCP server.
+- OpenGeni's credential broker encrypts secrets and keeps them out of model
+  context, but the trusted control plane can decrypt them for the authorized
+  provider request. Do not describe it as zero knowledge.
+- Do not call Temporal, NATS, Postgres, workers, sandbox providers, object
+  storage APIs, or MCP transports as substitutes for the public SDK/API.
+- Do not claim auth, model, tool, billing, CORS, storage, or compute behavior
+  until the live deployment or current source proves it.
+- Keep examples generic and parameterized. Skills may name non-secret origins
+  and conventions, but credentials come from a secret manager or environment.
+- Generate a customer-specific skill only for stable facts their coding agents
+  repeatedly need. Keep it beside their integration code, point it at the SDK,
+  include a config/access smoke probe, and never paste secrets into it.
+  Start from `references/customer-skill-template.md` when the OpenGeni skill
+  package is available.

package/src/bundled_default_skills/opengeni-client/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "OpenGeni Client"
+  short_description: "Developer guide for tenant-safe OpenGeni SDK and UI integration; not runtime instructions."
+  default_prompt: "Integrate my product with OpenGeni using the smallest safe surface. Keep standing credentials server-side, choose organization vs workspace key vs delegated token explicitly, map each external tenant to an organization workspace without Personal-workspace fallback, and pass product-owned Skills inline per session."

package/src/bundled_default_skills/opengeni-client/references/api-workflows.md

@@ -0,0 +1,256 @@
+# OpenGeni API Workflows
+
+This reference is intentionally pattern-level. Check the live service or source
+contracts for exact schemas before generating SDK code. When the repository is
+available, `docs/product-integration.md` is the canonical organization-key,
+workspace-mapping, and Skill-ownership guide.
+
+## Access Setup
+
+Choose one credential deliberately:
+
+- Managed SaaS product integration: create an organization API key through
+  `POST /v1/organizations/:organizationId/api-keys` /
+  `createOrganizationApiKey`, store the one-time token on the product server,
+  and send `Authorization: Bearer <api-key>`.
+- One-workspace automation: use a workspace API key and do not call
+  organization provisioning routes.
+- User/workspace delegation: use a short-lived delegated token with explicit
+  authority rather than a standing organization key.
+- Configured/self-hosted perimeter: a deployment access key may gate the
+  deployment, but it is not tenant identity.
+- Local development: the service may resolve a default dev subject/workspace without external auth.
+
+Only add `x-opengeni-access-key` when the operator says the deployment
+shared-key boundary is enabled. It is not a replacement for organization API
+keys in managed SaaS.
+
+## Minimal Server-Side Session Client
+
+```ts
+import { OpenGeniClient } from "@opengeni/sdk";
+
+const client = new OpenGeniClient({
+  baseUrl: process.env.OPENGENI_API_BASE_URL!,
+  apiKey: process.env.OPENGENI_ORGANIZATION_API_KEY!,
+});
+
+const organizationId = process.env.OPENGENI_ORGANIZATION_ID!;
+const { workspace } = await client.ensureWorkspace({
+  accountId: organizationId,
+  externalSource: "acme-product",
+  externalId: productTenant.id,
+  name: productTenant.displayName,
+});
+if (workspace.kind !== "shared") {
+  throw new Error("Product integrations require an organization workspace");
+}
+
+const skills = await productSkillStore.resolveForSession(productTenant.id);
+const created = await client.createSession(workspace.id, {
+  initialMessage: "Inspect the uploaded logs and summarize the failing deploy step.",
+  idempotencyKey: crypto.randomUUID(),
+  skills,
+  firstPartyMcpTools: selectedFirstPartyTools,
+  tools: selectedIntegrationServers,
+});
+
+for await (const event of client.streamEvents(workspace.id, created.id)) {
+  if (event.type === "agent.message.delta") {
+    process.stdout.write((event.payload as { text?: string }).text ?? "");
+  }
+}
+```
+
+This code belongs on the product server, not in a browser bundle. For a browser
+timeline, expose a tenant-scoped same-origin route and use the SDK's
+`proxySessionEventStream` helper. Authenticate the product user and resolve the
+allowed workspace/session before opening the upstream stream.
+
+`ensureWorkspace` maps through `PUT /v1/workspaces/external`. Use a stable
+external source/id pair and persist the returned opaque id. The returned
+organization workspace has wire `kind: "shared"`. Personal workspaces are
+excluded; do not fall back to `/v1/access/me`'s default/personal workspace.
+The method returns `{ workspace, created }`; use `workspace.id`, and treat
+`created: false` as the normal idempotent replay result.
+
+The product backend stores and versions Skills outside OpenGeni and passes the
+selected definitions inline in `CreateSessionRequest.skills`. There is no
+organization-wide Skill registry or Skill inheritance in this integration
+contract.
+
+The product must choose the workspace mapping from its sharing rule before
+running this flow. A tenant-shared workspace is suitable only when that tenant
+may share workspace-scoped agent authority and resources. Use a per-user
+workspace for cross-user chat privacy and a per-chat workspace for hard
+same-user chat isolation. Knowledge authoring Off does not create either
+boundary.
+
+For a headless product, send an explicit minimal `firstPartyMcpTools` and
+`tools` selection. Omission inherits deployment/workspace defaults. Removing
+cross-session tools from a shared workspace is defense in depth, not a hard
+tenant boundary.
+
+## Existing APIs As Agent Tools
+
+The SDK cannot serialize ordinary customer backend functions into tools. Use
+one of the supported network boundaries:
+
+- For an existing HTTP API, host a focused OpenAPI 3.0/3.1 document and call
+  `previewApiIntegration`, then `installApiIntegration` with the exact revision,
+  digest, Connection, stable instance key, and selected operations.
+- For GraphQL, use the same preview/install lifecycle with the GraphQL source.
+- For MCP, install a workspace capability or pass a session-specific
+  `mcpServers` definition with an HTTPS URL, allowed tools, approval policy, and
+  write-only headers or a `connectionRef`.
+
+Preview/install is deterministic backend work and can be reconciled across many
+workspaces; a model does not need to read and approve the same API description
+for every workspace. Persist the returned Integration instance/server IDs and
+skip unchanged desired versions rather than reinstalling on every chat.
+
+Create API-key credentials with `createConnection`. Rotate ordinary credentials
+through `updateConnection` with `expectedVersion`; OAuth providers use their
+dedicated reconnect flow. For session-specific MCP headers, later message
+requests may carry the supported MCP credential update. Responses expose
+metadata and credential versions, never the values.
+
+OpenGeni encrypts brokered credentials at rest and keeps them out of model
+context. The trusted control plane can decrypt them to call the exact provider;
+the model and sandbox receive only schemas and bounded results. The provider API
+must still enforce tenant/user scope on every operation and must not trust a
+model-supplied tenant ID.
+
+## Runtime Profile And Models
+
+Use workspace `agentInstructions` for stable workspace behavior, session
+`instructions` for one role/conversation, Skills for conditional procedures,
+and `modelContext` for current dashboard or route state. Avoid duplicating one
+policy across all four surfaces.
+
+Inline Skills are transmitted once in `createSession` and fixed onto that
+session, not sent on each turn. Version the customer-owned runtime profile and
+apply new Skill content to new sessions unless the product deliberately
+migrates old ones.
+
+Workspace `sessionDefaults` set the default model and reasoning for new
+sessions. A session or message may override them subject to the workspace model
+access policy. Resolve model IDs from the live client configuration rather than
+hard-coding a remembered list.
+
+OpenGeni-credit models in every organization workspace draw from the same
+organization account balance; workspace creation does not create separate
+wallets. Connected subscriptions and workspace-owned provider credentials may
+instead use an externally billed path. Preserve the workspace and product
+boundary in usage attribution when the customer needs a per-user or per-tenant
+view over the shared organization balance.
+
+Reconcile stable workspace settings, Connections, Integrations, and runtime
+profile versions during provisioning, startup, deployment, or a controlled
+migration. Do not PATCH the same settings or reinstall the same Integration on
+every chat request when no desired version changed.
+
+## Session Creation Options
+
+Beyond `initialMessage`/`tools`/`resources`, the create body (`POST /v1/workspaces/:workspaceId/sessions`, the SDK's `createSession(workspaceId, request)`) chooses where the session runs:
+
+- `sandboxBackend` — pick the managed sandbox execution backend; omit for the deployment default.
+- `targetSandboxId` (uuid) — run the session on an enrolled **Connected Machine** (a user-owned machine) instead of a managed sandbox. It seeds the session's active-sandbox pointer at creation so the first turn routes to that machine; an invalid/unowned/offline target fails the create.
+- `workingDir` — the host path the machine runs the session under (the base for its agent cwd, terminal, and file dock). **Only valid together with `targetSandboxId`** — sending `workingDir` alone is a 422. Omit it to use the machine's default working directory.
+- `sandbox` — shared-sandbox placement for managed sandboxes, a three-way union: `"shared"` (join the creating session's box; a top-level `"shared"` is a 422), `"new"` (mint a fresh box), or `{ groupId }` (join a specific sibling group in the same workspace). Omitted resolves a context-dependent default server-side.
+- `idempotencyKey` (1–200 chars) — a workspace-scoped CREATE idempotency key (see below).
+
+`targetSandboxId`/`workingDir` are the managed-sandbox-vs-Connected-Machine choice; `sandboxBackend` and the `sandbox` placement union only apply to managed sandboxes. To move a session onto a different machine *after* creation, use the active-sandbox swap (below) — not `updateSession`, whose only field is the session `title`.
+
+## Replay And Retry
+
+- Persist the latest event sequence seen by the client.
+- On reconnect, list events after the last known sequence before reopening the stream.
+- Retry idempotent reads and stream reconnects with bounded backoff.
+- Session creation exposes a workspace-scoped `idempotencyKey` (distinct from the per-call `clientEventId`): forward a stable value so concurrent/retried creates of the same logical session collapse to a single session. Without it every create is independent, so a blind retry can double-create — keep sending a stable key when you retry.
+- Treat unknown event types as extensible timeline entries, not client crashes.
+
+## Files
+
+The usual flow is:
+
+1. `POST /v1/workspaces/:workspaceId/files/uploads`
+2. `PUT` bytes to the returned signed object-storage URL with the required headers.
+3. Complete the upload through the returned workspace upload endpoint.
+4. Attach the file resource to a session, follow-up turn, or scheduled task only after it is ready.
+
+Never attach a file id from another workspace. Correct behavior is no data leak: 403 when the credential has no workspace grant, 404 when the resource is not in the granted workspace.
+
+## Knowledge And Search
+
+Uploaded originals remain Files. Attaching a ready file in a normal chat lets the
+accepted agent turn prepare its searchable source content when Knowledge
+authoring is enabled; users do not need a separate document-base upload flow.
+The attempt-bound `knowledge_retain_file` tool provides explicit preparation.
+Retained sources, findings and collections share the canonical Knowledge entries
+API. Use `listKnowledgeEntries` and `getKnowledgeEntry` for retrieval, or the
+first-party `knowledge_*` tools for agents. A finding cites a specific source
+revision; a collection relates existing entries across sources without copying.
+
+Default retrieval returns published content. Explicit `view: "needs_review"`
+returns accessible pending proposals as unapproved context, so an agent can
+improve an existing entry instead of creating duplicates. Agent learning resolves
+workspace/personal defaults plus chat or scheduled-task overrides: Automatic
+publishes, Review first stages without pausing work, and Off disables agent
+authoring while retaining authorized retrieval. Conversation history and
+temporary task notes remain separate. Inspect the installed SDK and live schema
+for exact request shapes rather than using the retired Memory writers.
+
+## GitHub Repositories
+
+For private repos, use the workspace GitHub repository list before attaching a resource. A valid repository resource normally includes clone URL, ref, mount path, GitHub installation id, and GitHub repository id from OpenGeni's listing response. The worker mints short-lived GitHub App tokens for selected repositories and should not persist clone credentials in session manifests.
+
+Do not ask customers to paste GitHub App private keys into their client integration. Managed SaaS uses the OpenGeni-owned app; self-hosted operators configure their own app server-side.
+
+## Connected Machines And Enrollment
+
+A Connected Machine is a user-owned machine enrolled into a workspace and used as first-class primary compute (no cloud box behind it; it uses its own git auth; repos are not cloned onto it). `selfhosted` is the internal `sandboxBackend` enum value for such a machine.
+
+Discover and target machines:
+
+- `GET /v1/workspaces/:workspaceId/machines` — list the workspace's machines (each with its derived state, latest metrics, and shared-session count) plus the active-sandbox pointer. Pass `?sessionId=` for an in-session view that also includes the session's own group box. SDK: `listMachines(workspaceId, { sessionId })`.
+- `GET /v1/workspaces/:workspaceId/machines/:enrollmentId/metrics/series?window=15m|1h|6h|24h` — the downsampled (~1/min) metrics history. SDK: `machineMetricsSeries(workspaceId, enrollmentId, { window })`.
+- Create a session with `targetSandboxId` (a machine's `sandboxId` from the list) plus an optional `workingDir` to run on it.
+- `POST /v1/workspaces/:workspaceId/sessions/:sessionId/active-sandbox` with `{ target }` — swap the session's active sandbox mid-conversation; `target` is a machine's `sandboxId`, or `"session"`/`"default"` to return to the session's own group box. The response echoes `swapped`, `activeSandboxId`, `activeEpoch`, and a `reason` when a target is refused. SDK: `swapActiveSandbox(workspaceId, sessionId, { target })`.
+
+Enroll a machine (the client-driven parts):
+
+- Interactive device flow: the machine's own agent starts and polls the flow agent-side (unauthenticated). A workspace operator resolves the pending request by user code with `POST /v1/enrollments/device/lookup` (no workspace in the path — the server resolves it from the code, then authorizes `enrollments:read`), then `POST /v1/workspaces/:workspaceId/enrollments/device/approve` (the loud consent step; `allowScreenControl` opts into screen control) or `.../device/deny`. SDK: `lookupDeviceEnrollment(userCode)`, `approveDeviceEnrollment(workspaceId, { userCode, allowScreenControl })`, `denyDeviceEnrollment(workspaceId, { userCode })`.
+- Headless / fleet: `POST /v1/workspaces/:workspaceId/enrollments/token` mints a short-TTL SECRET enroll token (surface it once with a copy-now warning); the machine's agent redeems it agent-side at `POST /v1/enrollments/token/exchange`. SDK: `mintEnrollToken(workspaceId, { allowScreenControl })`.
+- `POST /v1/workspaces/:workspaceId/enrollments/:enrollmentId/revoke` removes a machine. Approving, minting, and revoking all require `enrollments:manage`; listing needs `enrollments:read`.
+
+Never distribute an OpenGeni credential to a Connected Machine or try to inject git tokens into it — the machine authenticates to git with its own credentials. Device start/poll and token exchange are agent-side calls, not client SDK methods.
+
+## Billing And Limits
+
+Managed SaaS uses prepaid Stripe credits and local usage/cost accounting. Client behavior should be simple:
+
+- Show billing/credit status from `/v1/billing` when the user has billing permission.
+- Stop costly writes/runs when the API returns a credit/limit denial.
+- Preserve read/export paths when writes are blocked.
+- Surface top-up links from OpenGeni; do not call Stripe directly from a customer agent unless OpenGeni explicitly returns a Stripe URL.
+
+## Generated Customer Skills
+
+When generating a customer-specific agent skill that teaches their coding agents how to call OpenGeni:
+
+- Include only their non-secret base URL, organization-workspace mapping
+  convention, and safe API examples.
+- Tell the agent to read API keys from the customer's secret manager or environment, never from the skill.
+- State that the backend uses an organization API key, organization workspaces
+  have wire `kind: "shared"`, and Personal workspaces are excluded.
+- State where the external product stores Skills and that it passes selected
+  definitions inline per session; never invent an organization-wide Skill
+  registry or inheritance layer.
+- Keep the skill versioned with their integration code and add a quick smoke command that calls `/v1/config/client` and `/v1/access/me`.
+- State which integration shape the product chose and where its tenant-safe
+  proxy/client lives; do not teach every possible shape in every customer skill.
+- Describe only primitives proven by the installed SDK and live deployment; do
+  not turn roadmap assumptions into customer instructions.
+- Start from `customer-skill-template.md` in this directory so the generated
+  skill records the chosen shape and smoke probes without copying credentials.