@happyvertical/smrt-mcp-openai 0.0.0-stage → 0.51.39

package/AGENTS.md

@@ -0,0 +1,11 @@
+# Optional OpenAI navigation adapter
+
+`src/index.ts` composes existing principal-authorized app-MCP workflows. Settings
+persistence, atomic assignment and tenant checks stay in the owning application
+handler. The adapter validates wire contracts; it never authenticates or retries
+writes. `src/client.ts` uses only the portable browser bridge and bounded inert
+host context. No SDK v1 helper, second server, or OpenAI types in portable APIs.
+
+Pinned contract, fallbacks, package gates and external-host evidence limitations
+are in README.md; behavior/threat rows are in TEST-DESIGN.md. Run build, typecheck,
+test, test:e2e and verify:pack. Synthetic hosts do not prove OpenAI host support.

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/FILES.md

@@ -0,0 +1,77 @@
+# Optional native files
+
+Import browser APIs from `@happyvertical/smrt-mcp-openai/files` and server
+annotation from `@happyvertical/smrt-mcp-openai/files/server`. Neither is loaded
+by ordinary tools. This is a bounded small-file adapter, not a filesystem.
+
+`withOpenAiFileEntrypoint(existingWorkflow, ['.txt'])` adds the pinned file
+entrypoint and validates `{file:{name,resourceUri}}`. The existing read workflow
+must resolve the reference through its provider and current trusted principal,
+owner and active tenant. A handle, filename or `_meta["openai/resource"].path`
+is never authority. Remote servers must never read a host path as their own disk.
+
+After the portable bridge connects, create `OpenAiFileSession` with its initial
+file input, an existing `authorityTool`, a `fallbackTool`, `maxBytes` (1–16384)
+and explicit MIME allowlist. The authority tool receives `{file,operation}` and
+must reject anonymous, other-owner, other-tenant, guessed, revoked and stale grants
+using the application's existing policy/provider APIs. Successful empty tool
+results mean the application authorized that operation; the adapter does not
+supply a second grant database. No browser-supplied identity is accepted.
+
+The host independently enforces the opaque grant. Reads request the selected
+text/blob representation and validate exact URI, MIME and decoded byte count.
+Each operation checks application authority; reads recheck after the host result.
+Writes require a fresh read with `writable:true` and a nonempty ETag, always send
+`ifMatch`, reject parallel writes and never retry. Every outcome, including saved,
+conflict, too-large or unknown upstream failure, requires another authorized read.
+A host ETag is a compare/write guard, not an idempotency token.
+
+One bounded subscription refreshes only the initial URI and rechecks authority.
+Refreshes coalesce, revocation disposes the session, and stale/disposed results
+cannot update content. Dispose on UI unmount. Reconnect or a new file needs a new
+session; no handle migration is attempted. Unsubscribe is best effort during
+teardown, while local callbacks and authority end immediately.
+
+Absent/unknown resource capability uses the ordinary `fallbackTool` workflow
+for read/import/open/download or editor launch. It receives `{file,operation}`;
+it must return usable text/links/UI through the same application policy. The
+fallback does not silently replay a proposed native write. The user completes
+editing through the ordinary application workflow.
+
+`openOpenAiFile` requires explicit application confirmation, an existing provider
+tool resolving the selected object, and an exact trusted `allowedPaths` list. The
+host open request uses only the authorized provider's returned path. It never
+accepts a caller's raw path or reads that path on the server. Without native file
+opening, the provider tool's ordinary open/download result is returned. A remote
+provider should return a normal authorized download workflow, not desktop paths.
+
+## Protocol and evidence
+
+Pinned OpenAI source revision `e314720a0daac326217d1f123fcf51647868fa9f`:
+`docs/spec.md`, `typescript/src/shared/file-entrypoint.ts`,
+`typescript/src/app/resources.ts`, `typescript/src/app/files.ts`, and
+`typescript/src/shared/resources.ts`. Full Zod unions define wire fields.
+Native browser capability keys are `experimental["openai/resource"]` and
+`experimental["openai/files"]`, each `{}`; neither has a version field. The
+adapter uses the existing portable bridge's origin/source/lifecycle enforcement.
+There is no SDK-v1 helper, second server, or fabricated server subscription.
+Host resources are intercepted by the browser host; server SDK-v2 HTTP carries
+ordinary principal-authorized entrypoint tools and fallbacks (2026-07-28).
+
+Run build, typecheck, test, test:e2e, test:files:e2e, verify:pack and
+verify:files:pack with `pnpm --filter @happyvertical/smrt-mcp-openai` after normal
+install and dependency builds. FILES-TEST-DESIGN.md maps adversarial coverage.
+Synthetic HTTP/browser fixtures use no real files or user data. Actual OpenAI
+product/build/platform access is unavailable here; these tests do not establish
+live OpenAI host compatibility or permit advertising observed host support.
+
+Subscription lifecycle regression (#3214 review round 1): notifications during a
+pending write coalesce into a fresh authorized read after the write settles.
+Superseded refreshes retry a read without disposing the session; authority and
+validation failures still terminate it. Disposal dispatches best-effort host
+unsubscribe and releases local registration synchronously, allowing immediate
+replacement even when the host never replies. Deterministic session tests cover
+delayed read/write completion, the refreshed ETag, revocation, and replacement
+while unsubscribe is withheld.
+
+Resource URIs are preserved verbatim and reject Windows drive prefixes as well as URLs and filesystem paths. Matching resource-update notifications invalidate in-flight reads before callbacks publish content; refresh retries still obtain fresh authority. A session invalidated by the bridge's initial synchronous snapshot immediately releases its lifecycle listener.

package/FORMS-TEST-DESIGN.md

@@ -0,0 +1,42 @@
+# M6d form and resource-selection validation contract
+
+Refs #3216. Risk: high — asynchronous authorization and approval integrity.
+Source of wire truth: OpenAI mcp-extensions e314720a0daac326217d1f123fcf51647868fa9f,
+full server/forms/{schema,fields,file-picker,elicitation}.ts. No generated JSON schema artifact.
+
+| Behavior / reachable trigger | Positive | Negative / failure | Actor/context | Executor/transaction | Runtime/dialect | External edge | Test level / command |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| Form declaration before suspension | Primitive, select, array, resource variants | Unknown/oversized/accessor/prototype/schema injection, invalid defaults | Server-owned declaration | N/A: pure validation | Node/browser | Pinned complete schema unions, explicitly narrowed safety profile | Unit / pnpm --filter @happyvertical/smrt-mcp-openai test |
+| Form reply before use | Exact accept content, cancel, decline | Missing/unknown fields, wrong type/options/resource, oversized content | Untrusted host/app reply | N/A: validation precedes authoritative handler | Node/browser | Exact reply union | Unit / same |
+| Durable form continuation | Owner+tenant+record/revision/input key survive restart | Wrong owner/tenant/request/revision, duplicate/concurrent/cancelled reply | Verified application actor, active tenant | Existing McpTaskStore job row and CAS; no new store | SQLite/PostgreSQL | Existing M5 continuation | Integration / same with SMRT_TEST_POSTGRES_URL for PostgreSQL |
+| Live authority and application apply | Fresh authorization at start/resume/apply | Revocation before/after reply, callback failure, unknown external outcome | Verified actor × ownership × tenant | Existing TaskRunner, maxAttempts=1, owning handler transaction | SQLite/PostgreSQL | M5 authority callback; form answer never approval | Integration / same |
+| Capability/native transport decision | Explicit usable application form fallback | Absent/unknown capability, unsupported SDK path, upstream failure | Synthetic SDK client | Same authoritative workflow | SDK v2 HTTP | openai/elicitation create/MRTR support checked explicitly | Integration / same |
+| Functional form presentation | Keyboard usable accept/cancel/decline, escaped options | Inert injected text, invalid values | Synthetic browser user | Submit to owning application workflow; no browser authority | Chromium | Application form fallback, no host certification | Browser / pnpm --filter @happyvertical/smrt-mcp-openai test:forms:e2e |
+| Package boundaries | Packed forms browser and server entries load | SDK v1/server imports in browser | Package consumer | N/A: static bundle/load | Node/browser | Published explicit subpaths | Pack / pnpm --filter @happyvertical/smrt-mcp-openai verify:forms:pack |
+
+Full root gates and final independent review are coordinator-owned after #3205 repair.
+Actual OpenAI host verification remains M8; synthetic tests cannot satisfy it.
+
+Accepted review regression: for both multi-select and free-text arrays, untouched
+optional fields without defaults are omitted; editing then clearing submits an
+explicit empty array, accepted at minItems=0 and rejected at minItems=1. Untouched
+required arrays still undergo minItems validation. Browser fixtures cover each
+case; the two optional-omission cases fail against the pre-fix renderer.
+
+## PR3283 accepted round-3 corrections
+
+| Invariant | Reachable trigger | Positive | Negative/failure | Actor/context and executor | Runtime/contract edge | Level and command |
+|---|---|---|---|---|---|---|
+| Inert shared JSON | form schema/reply and shared native/context/message/mention/settings/file parsers | ordinary nested JSON; validation returns void | array getter/iterator/custom prototype, hidden getter/toJSON, inherited toJSON: zero callbacks; sparse/custom/symbol fields rejected | untrusted caller; no domain executor | Node and browser; pinned bounded JSON schema, unknown non-JSON rejected | full `test`, installed forms/shared-boundary probes |
+| Reversible string arrays | free array form editor defaults and edited values | newline item, empty item, >4096 total with bounded items | invalid JSON, non-string/oversized item, minItems empty | local form input; submission spy/HTTP fixture only, no domain approval | Chromium; existing 64-item/4096-item/65536-byte profile | `test:forms:e2e`, installed validator |
+| Optional empty choice | enum/oneOf selection/default | defined empty choice survives | untouched optional text omitted | local form; authenticated route still owns execution | Chromium select placeholder vs explicit empty option | `test:forms:e2e` |
+| Real date-time | reply/default string validation | leap day, fractional second, offsets crossing date boundary | February31/nonleapFebruary29/April31, hour24, minute/second60, offset overflow | untrusted input; no persistence mutation | Node/public installed API; existing RFC3339-style profile | `test`, installed forms probe |
+
+Baseline production48bc with test-only overlays: descriptor/date unit regressions
+and actual Chromium round-trip/choice regressions fail before fixes; overlay hashes
+and exact logs are retained externally in round-3-pr-feedback. Shared `json()`
+callers were audited in validation, index, client, settings, context, messages,
+mentions, file-contracts, files and forms-server: all call the boundary before
+interpreting wire values; stricter descriptor rejection has full owning-package
+unit/browser/installed coverage. SQL/PG/root-wide replay is N/A for these parser
+and presentation-only corrections; existing durable authority remains unchanged.

package/FORMS.md

@@ -0,0 +1,112 @@
+# Optional extended forms and resource selection
+
+`@happyvertical/smrt-mcp-openai/forms` validates the bounded OpenAI wire profile.
+`/forms/view` renders a functional application form without host capabilities.
+`/forms/server` composes that input with the existing durable MCP workflow.
+No form answer supplies identity, file permission, or domain approval.
+
+## Pinned contract and native limitation
+
+Wire source: OpenAI mcp-extensions
+[e314720a0daac326217d1f123fcf51647868fa9f](https://github.com/openai/mcp-extensions/tree/e314720a0daac326217d1f123fcf51647868fa9f/typescript/src/server/forms):
+full `fields.ts`, `file-picker.ts`, `schema.ts`, and `elicitation.ts` were inspected.
+The repository supplies TypeScript/Zod source, not a generated JSON schema artifact.
+Official [MCP guidance](https://developers.openai.com/plugins/build/mcp-server)
+requires server-side authorization and says elicitation collects information,
+not credentials or authentication bypasses.
+
+The pinned extension advertises `extensions['openai/elicitation'].form` and calls
+`openai/elicitation/create`. SMRT's scoped `@modelcontextprotocol/server` 2.0.0,
+protocol 2026-07-28, has a public `InputRequest` union of `CreateMessageRequest |
+ListRootsRequest | ElicitRequest`. `inputRequired.elicit` emits only
+`elicitation/create`; `ServerContext.mcpReq.elicitInput` explicitly throws on
+2026-07-28. The public MRTR union does not include the OpenAI method. The upstream
+helper uses monolithic SDK v1 and is not an acceptable substitute. Therefore
+`openAiFormSupport` returns `native:false` even with a present host capability,
+with `sdk-mrtr-unsupported`. Absent and unknown capabilities also select the
+functional application-form fallback. No OpenAI extension capability is
+advertised, no callback is kept alive, and the stateless mount is unchanged.
+Actual OpenAI host support is unverified and remains the M8 acceptance gate.
+
+## Bounded wire profile
+
+Supported fields cover boolean, number/integer, string, titled/legacy single
+select, titled/untitled multi-select, string arrays, suggestions, thumbnail/preview
+metadata, and file/resource picker strings or arrays. Replies are exactly
+`{action:'accept',content:{...}}`, `{action:'cancel'}`, or `{action:'decline'}`.
+The parser rejects unknown fields instead of stripping semantic instructions.
+Limits: 64 fields/options/selections, 4096-character values, 256-character resource
+names, 2048-character URIs, 65536-byte inert JSON budget, depth 16. Numeric bounds
+must be finite; integer answers must be safe integers. Required/enum/default and
+resource-selection rules are checked without coercion or inserted defaults.
+
+Deliberate stricter safety profile: arbitrary regex `pattern` is rejected rather
+than evaluated; prototype-sensitive names and accessors are rejected; images
+must be HTTPS without credentials or bounded raster data URIs. The fallback
+renderer does not fetch images. Resources must use opaque absolute URIs;
+`file:`, `data:`, and `javascript:` are rejected, and a remote application cannot
+interpret a desktop path. The owning grant provider must authorize every selected
+URI, including offered options and implicit/user-supplied selections. Selection
+is input only. Unknown resource metadata does not become permission.
+
+## Durable application integration
+
+Inside the existing task runner, call `continueOpenAiForm` with a server-owned
+`McpWorkflowContinuation` (`recordId`, immutable `revision`, unique `inputKey`,
+HTTPS or loopback `reviewUrl`), schema, fresh `authorizeApply`, and `applyInput`.
+Forms containing pickers also require `authorizeResource`. The task must already
+have the exact same continuation binding. M5 persists its owner and active tenant,
+checks live task authority at start/resume, and uses one job row for suspension,
+first-response CAS, cancellation, and execution. No new approval store exists.
+
+The authenticated application form reads the descriptor through
+`createMcpContinuationTool` or its actor/tenant-bound `McpTaskStore`, renders it
+with `renderOpenAiForm`, then calls `submitOpenAiForm` on its server. Supply that
+verified actor's tenant-bound store and a policy callback which resolves fresh
+application authority. Never derive either from submitted form values. Submit
+validates the stored schema, a canonical SHA-256 schema fingerprint, and exact binding before persisting a bound reply;
+the worker validates again, checks selected resource grants, then reauthorizes both application access and active task ownership after asynchronous checks
+before `applyInput`. Direct `tasks/update` cannot bypass worker validation.
+
+A submitted reply is not a completed operation. Concurrent replies use the
+existing store's first-response-wins CAS; stale/cancelled/consumed requests fail
+closed. Poll the task for its authoritative result. Worker restart replays the
+handler, so all code before suspension must be read-only or use the existing
+owning action/runOnce idempotency API. Remote jobs use `maxAttempts:1`; unknown
+external outcomes fail for manual reconciliation, not automatic replay.
+`applyInput` must enforce domain review and immutable revision in its owning
+transaction, and external access must recheck applicable authority at its own
+boundary. Iolaus retains its dedicated human review page and no employer
+transmission occurs in fixtures. Accepting a form does not approve an application.
+
+Run package build, typecheck, test, test:forms:e2e and verify:forms:pack. See
+[FORMS-TEST-DESIGN.md](FORMS-TEST-DESIGN.md) for the evidence contract. Tests use
+synthetic data only; PostgreSQL authority tests use `SMRT_TEST_POSTGRES_URL`.
+
+In the application form, an untouched optional array without a default is
+omitted from the reply. Editing then clearing an array submits an explicit
+empty array, which must satisfy `minItems`. Required arrays and declared
+defaults always remain subject to the schema's normal reply validation.
+
+### Inert inputs and reversible fallback values
+
+Form schemas and replies are interpreted and serialized from a detached snapshot
+of own enumerable data descriptors. Accessors, sparse/custom-prototype arrays,
+custom array properties/iterators, hidden fields and serialization hooks are
+rejected without invoking supplied callbacks. The shared JSON validator retains
+its validation-only return contract and existing depth/node/byte bounds; ordinary
+JSON data remains supported. Native, context, messages, mentions, settings, file
+and continuation callers share this boundary. Host callbacks/functions belong in
+adapter options, never in wire JSON.
+
+The free string-array fallback uses an explicitly labeled JSON array editor:
+`["first", "second"]`, `["a\nb"]`, `[""]` and `[]` remain distinct. Each item and
+the complete reply retain their existing limits; the editor allows up to 65,536
+characters and wire validation enforces the byte limit. Invalid JSON remains
+editable and does not submit. Untouched optional arrays/text remain omitted;
+intentional empty choices and empty defaults are retained. A blank array editor
+means an intentional empty list after interaction, preserving minItems checks.
+
+Date-time replies require a real calendar date, hours 00–23, minutes/seconds
+00–59 and offset hours/minutes 00–23/00–59, in the existing `T` and `Z`/offset
+profile. Invalid dates normalized by JavaScript's Date parser are rejected.

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright <2025> <Happy Vertical Corporation>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,176 @@
-# Temporary Holding Version
+# @happyvertical/smrt-mcp-openai
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Optional navigation, settings, context, messages and mentions for s-m-r-t MCP Apps. Ordinary s-m-r-t apps do not
+import this package. The `./client` entry is browser-only and depends on the
+portable `@happyvertical/smrt-mcp-apps` bridge; the root entry composes existing
+app-MCP workflows without creating another server or authorization policy.
+
+## Contract and scope
+
+This package implements the navigation/settings and context/messages/mentions children of [#3202](https://github.com/happyvertical/smrt/issues/3202)
+under the [M0 integration standard](../../docs/content/architecture/mcp-apps-integration.md):
+
+- Global and thread entrypoint metadata on idempotent read UI tools accepting `{}`.
+- Structured primitive settings and permission-filtered layout actions; modern
+  discovery advertises `capabilities.extensions['openai/settings']` only when
+  both settings tools are in the request's authorized catalog.
+- Resource display-mode metadata and portable display requests with inline fallback.
+- Validated native/web app links and observed host deep links resolved through an
+  existing domain-authorized read tool.
+- Manifest onboarding declaration; packaged skill/assets verification belongs to M7.
+
+Exact baseline: [OpenAI extension spec e314720](https://github.com/openai/mcp-extensions/blob/e314720a0daac326217d1f123fcf51647868fa9f/docs/spec.md),
+revalidated as upstream main on 2026-09-30 UTC, and the [official extension guide](https://developers.openai.com/plugins/build/extensions)
+and [UI guide](https://developers.openai.com/plugins/build/chatgpt-ui). The SDK v1
+OpenAI helper is deliberately not a dependency. Server transport uses native
+scoped MCP SDK 2.0.0 / protocol `2026-07-28`; browser Apps uses `2026-01-26`.
+
+Only implemented features are declared. Files/forms remain separate planned M6 children. Settings support booleans, strings/enums/length bounds,
+numbers/integers/range/multiple bounds. Arbitrary regex patterns are explicitly
+rejected to avoid running unbounded patterns; applications can use an enum or
+an existing domain validator. No silent schema downgrade occurs. Metadata is
+bounded to 64 KiB, depth 16; settings to 64 fields, strings to 4096 characters,
+routes to 2048 characters. Unknown fields/types fail closed.
+
+## Server composition
+
+Use `withOpenAiEntrypoints(existingReadWorkflow, ['global', 'thread'])` and pass
+the result to the existing `createMcpAppServer({ workflowTools })`. It retains the
+handler and portable `_meta.ui.resourceUri`. Initial tool results still render
+without duplicate entrypoint calls. Give thread views distinct descriptive titles.
+
+`bindOpenAiSettings({ schema, read, update, server: () => appServer })` wraps two
+existing workflow definitions. Add its `workflows` to that server, then mount it
+with `extensions: ({ tools }) => settings.extensions(tools)`. The callback runs
+on `server/discover` with the same verified principal and filtered catalog used
+for tool discovery. Neither annotations nor extension metadata grant permission.
+
+Read handlers return `structuredContent: { schema, values, layout? }`, with a
+value for every property. Update handlers receive `{ set: { changedField: value } }`
+and return `structuredContent: { values }`. Updates are absolute-value assignments,
+not toggles or increments. The binding verifies their declared read/write effects,
+requires idempotent assignment, validates inputs/outputs, and never retries.
+
+**Owning handlers must authorize resource ownership, recheck active tenant and
+membership, and persist patches atomically using their existing executor and
+revision policy.** The adapter does not provide persistence, transaction guards,
+or domain approval. The host wire contract has no revision parameter; do not add
+an invented field. Workflows requiring a human review/revision token should keep
+that flow in the application, rather than force it into native settings. Tests
+exercise an owning SQLite transaction, guarded update, rollback and retries.
+
+Pass `openAiDisplayMetadata({ availableDisplayModes: ['inline', 'fullscreen'],
+preferredDisplayMode: 'fullscreen' })` as a declared resource's `metadata`.
+Resource security metadata and digest remain owned by app-MCP. `pip` is not part
+of this pinned OpenAI display contract. Omitted fields preserve upstream defaults;
+preferences remain hints.
+
+`openAiOnboardingDeclaration('./skills/setup/SKILL.md')` returns only
+`{ extensions: { 'com.openai': { onboardingSkill: ... } } }`. Merge that into the
+plugin manifest; it does not install or execute the skill.
+
+## Browser navigation and fallbacks
+
+Import `./client`, pass the existing `McpAppBridge` to
+`observeOpenAiNavigation({ bridge, resolveTool, onResult, onFallback })`, and call
+the returned disposer when unmounting. It consumes bounded `rawHostContext` from
+the bridge's validated origin/source and lifecycle, recognizes only
+`openai/deepLink: { url }`, and calls the designated server tool with `{ url }`.
+The domain tool must reject guessed or cross-tenant objects. Server applications
+can use `resolveOpenAiNavigationTarget` to dispatch only an authorized read tool.
+
+Repeated identical routes do not duplicate calls; new routes cancel old requests
+and ignore stale replies. URLs are app-relative, fragment-free, traversal-free,
+and reject protocol-relative, double-encoded and control-character forms. Treat
+query parameters as untrusted input, never as identity or approval. The literal
+query delimiter is separated before pathname decoding, so encoded question marks
+cannot hide traversal segments. Traversal-like text in query values remains legal.
+
+Only a rejected tool call or an `isError` result selects the `denied` fallback.
+Consumer callback exceptions are not authorization failures and never retry a
+fallback. Callbacks should handle their own rendering errors; uncaught exceptions
+in asynchronous result/fallback callbacks surface as unhandled promise rejections.
+
+`createOpenAiAppLink` emits pinned desktop (`codex`), mobile (`chatgpt`) or web
+formats with separately encoded plugin/tool/path components. `openAiNavigationLink`
+requires explicit `'present'` support to choose a native link; `'absent'`, unknown
+or malformed support uses a configured HTTPS application URL. This support input
+is a deployment/observed-host decision, **not an invented MCP capability field**.
+Entrypoints/onboarding similarly have no client advertisement in the pinned spec;
+keep ordinary tool/setup navigation available. Native structured settings are
+optional: the same settings tools and application settings page remain usable.
+
+`requestOpenAiDisplayMode` uses negotiated portable modes; missing/unknown modes
+or a rejected request return `'inline'`. The UI must actually retain its inline
+layout and render an ordinary link when navigation cannot be resolved.
+
+## Context, messages and composer mentions
+
+Browser consumers import `updateOpenAiModelContext` from `./context` and
+`sendOpenAiMessage` from `./messages`. Server consumers import
+`withOpenAiMentionSearch` and `resolveOpenAiMentionSelection` from `./mentions`.
+These subpaths share the existing portable bridge and authorized app-MCP server.
+
+`updateOpenAiModelContext({ bridge, value, native })` replaces context with
+`{ text: { text, title?, thumbnail? }, structuredContent? }`. Text is nonempty and
+at most 16384 characters; titles are limited to 512. Set `background: true` on the text value to emit assistant-only audience
+metadata; background is a presentation
+hint, **not a privacy boundary**: the model/provider still receives the context.
+Only send data authorized for that recipient. Negotiated `openai/modelContext`
+uses the supplied native callback. Missing support or native failure falls back
+to portable text and structured content, without native metadata. Abort/disposal
+prevents a late fallback.
+
+`sendOpenAiMessage({ bridge, value, native })` accepts text and `target: 'active'`
+(the default) or `'new'`. Active conversations can use portable text messages.
+New conversations require negotiated `openai/message` and a native callback;
+missing or malformed support rejects before any message reaches the active
+conversation. Unknown targets/modalities fail closed and sends are not retried.
+
+`withOpenAiMentionSearch(existingReadWorkflow)` declares app-only composer search
+metadata and a `{ query }` input (at most 256 characters, including empty search).
+Its owning handler returns `structuredContent: { items }`, with at most 25
+`{ type: 'resource', resourceUri, title, subtitle?, icons? }` entries. Handles
+are nonempty opaque strings of at most 2048 characters; titles/subtitles are
+nonempty and bounded to 512. Each of at most eight icons requires `src` (2048),
+with optional `mimeType` (128), up to eight nonempty `sizes` strings (32 each),
+and `theme: 'light' | 'dark'`. Unknown fields and malformed values reject.
+The published output schema describes these same closed objects and limits.
+
+Search results are discovery hints, never authorization grants. Pass the exact
+returned `resourceUri` as the existing selection workflow's argument through
+`resolveOpenAiMentionSelection({ server, tool, arguments, principal })`. The
+application supplies the trusted, freshly resolved principal; app-MCP policy
+rechecks actor, active tenant, scopes and membership on every call, and the
+owning workflow rechecks handle ownership. Never derive identity from a handle,
+browser metadata or search-time permission. Guesses, cross-tenant calls and
+revocation after search must not select private data. This helper adds no
+selection handler, identity provider, persistence or authorization policy.
+
+## Validation and evidence
+
+Run `pnpm install`, then the documented dependency build and package gates:
+
+```sh
+pnpm exec turbo build --filter=@happyvertical/smrt-mcp-openai...
+pnpm --filter @happyvertical/smrt-mcp-openai typecheck
+pnpm --filter @happyvertical/smrt-mcp-openai test
+pnpm --filter @happyvertical/smrt-mcp-openai test:e2e
+pnpm --filter @happyvertical/smrt-mcp-openai verify:pack
+```
+
+The behavior/threat matrix is in [TEST-DESIGN.md](TEST-DESIGN.md). Protocol tests
+use the actual SDK client and HTTP mount, including real loopback JWKS/MCP sockets
+through the public M2 auth gateway with token, actor, tenant and revocation denials; the browser suite uses a real Chromium
+sandboxed iframe with no-network CSP and built browser output. Packed exports
+are checked for declaration and browser/server boundaries. Existing app-MCP full
+suite/typecheck/pack and portable bridge gates also apply to integration changes.
+The coordinator schedules all root gates and independent review.
+
+**No actual OpenAI host compatibility is claimed.** The synthetic host does not
+prove desktop, Work web, iOS, Android or account rollout support. No configured
+OpenAI host connection or deployable registered synthetic plugin was provided;
+record exact host/build/platform, auth profile, asset revision and observed
+navigation/settings outcomes before claiming supported-host acceptance. The
+upstream support matrix is expected support only; web refers to Work, excluding
+classic ChatGPT. Actual host acceptance remains open for M8.

package/dist/client.d.ts

@@ -0,0 +1,27 @@
+import type { McpAppBridge, ToolResult } from '@happyvertical/smrt-mcp-apps';
+import { type OpenAiDisplayMode } from './validation.js';
+export { appRelativeUrl, OPENAI_EXTENSIONS_REVISION } from './validation.js';
+export type CapabilityState = 'present' | 'absent' | 'unknown';
+/** Deployment/host-observation input, not an invented MCP wire capability. */
+export declare function capabilityState(value: unknown): CapabilityState;
+export interface OpenAiAppLink {
+    pluginId: string;
+    toolName: string;
+    path?: string;
+    marketplace?: string;
+    platform: 'desktop' | 'mobile' | 'web';
+}
+export declare function createOpenAiAppLink(options: OpenAiAppLink): string;
+/** No host-brand inference: absent/unverified support yields an ordinary application link. */
+export declare function openAiNavigationLink(capability: unknown, link: OpenAiAppLink, fallbackUrl: string): string;
+/** Display negotiation remains portable; unknown modes and host failures retain inline UI. */
+export declare function requestOpenAiDisplayMode(bridge: McpAppBridge, requested: unknown): Promise<OpenAiDisplayMode>;
+export declare function readOpenAiDeepLink(rawHostContext: unknown): string | undefined;
+/** Observe inert host context, then request a domain-authorized read; never route to arbitrary URLs. */
+export declare function observeOpenAiNavigation(options: {
+    bridge: McpAppBridge;
+    resolveTool: string;
+    onResult(result: ToolResult, url: string): void;
+    onFallback(reason: 'unavailable' | 'invalid' | 'denied'): void;
+}): () => void;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAC7E,OAAO,EAKL,KAAK,iBAAiB,EAIvB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,cAAc,EAAE,0BAA0B,EAAE,MAAM,iBAAiB,CAAC;AAC7E,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAC/D,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CAE/D;AACD,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,SAAS,GAAG,QAAQ,GAAG,KAAK,CAAC;CACxC;AACD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CAwBlE;AAOD,8FAA8F;AAC9F,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,OAAO,EACnB,IAAI,EAAE,aAAa,EACnB,WAAW,EAAE,MAAM,GAClB,MAAM,CAKR;AACD,8FAA8F;AAC9F,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,OAAO,GACjB,OAAO,CAAC,iBAAiB,CAAC,CAkB5B;AACD,wBAAgB,kBAAkB,CAChC,cAAc,EAAE,OAAO,GACtB,MAAM,GAAG,SAAS,CAOpB;AACD,wGAAwG;AACxG,wBAAgB,uBAAuB,CAAC,OAAO,EAAE;IAC/C,MAAM,EAAE,YAAY,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAChD,UAAU,CAAC,MAAM,EAAE,aAAa,GAAG,SAAS,GAAG,QAAQ,GAAG,IAAI,CAAC;CAChE,GAAG,MAAM,IAAI,CAkDb"}

package/dist/client.js

@@ -0,0 +1,125 @@
+import { appRelativeUrl, displayMode, json, keys, record, text, toolName, } from './validation.js';
+export { appRelativeUrl, OPENAI_EXTENSIONS_REVISION } from './validation.js';
+/** Deployment/host-observation input, not an invented MCP wire capability. */
+export function capabilityState(value) {
+    return value === 'present' || value === 'absent' ? value : 'unknown';
+}
+export function createOpenAiAppLink(options) {
+    json(options);
+    keys(record(options), [
+        'pluginId',
+        'toolName',
+        'path',
+        'marketplace',
+        'platform',
+    ]);
+    const plugin = encodeURIComponent(text(options.pluginId, 256));
+    const tool = encodeURIComponent(text(options.toolName, 128));
+    const path = appRelativeUrl(options.path ?? '/');
+    const marketplace = options.marketplace === undefined
+        ? ''
+        : `@${encodeURIComponent(text(options.marketplace, 128))}`;
+    if (options.platform === 'web') {
+        if (marketplace)
+            throw new TypeError('Web links require a published ChatGPT plugin');
+        return `https://chatgpt.com/plugins/${plugin}/app/${tool}?path=${encodeURIComponent(path)}`;
+    }
+    if (options.platform !== 'desktop' && options.platform !== 'mobile')
+        throw new TypeError('Unsupported link platform');
+    return `${options.platform === 'desktop' ? 'codex' : 'chatgpt'}://plugins/${plugin}${marketplace}/app/${tool}?path=${encodeURIComponent(path)}`;
+}
+function appUrl(value) {
+    const parsed = new URL(text(value, 2048));
+    if (parsed.protocol !== 'https:' || parsed.username || parsed.password)
+        throw new TypeError('Expected credential-free HTTPS application URL');
+    return parsed.href;
+}
+/** No host-brand inference: absent/unverified support yields an ordinary application link. */
+export function openAiNavigationLink(capability, link, fallbackUrl) {
+    const fallback = appUrl(fallbackUrl);
+    return capabilityState(capability) === 'present'
+        ? createOpenAiAppLink(link)
+        : fallback;
+}
+/** Display negotiation remains portable; unknown modes and host failures retain inline UI. */
+export async function requestOpenAiDisplayMode(bridge, requested) {
+    let mode;
+    try {
+        mode = displayMode(requested);
+    }
+    catch {
+        return 'inline';
+    }
+    const snapshot = bridge.snapshot;
+    if (snapshot.state !== 'ready' ||
+        !(snapshot.hostContext.availableDisplayModes ?? ['inline']).includes(mode))
+        return 'inline';
+    try {
+        return displayMode(await bridge.requestDisplayMode(mode));
+    }
+    catch {
+        return 'inline';
+    }
+}
+export function readOpenAiDeepLink(rawHostContext) {
+    json(rawHostContext);
+    const context = record(rawHostContext);
+    if (context['openai/deepLink'] === undefined)
+        return undefined;
+    const link = record(context['openai/deepLink']);
+    keys(link, ['url']);
+    return appRelativeUrl(link.url);
+}
+/** Observe inert host context, then request a domain-authorized read; never route to arbitrary URLs. */
+export function observeOpenAiNavigation(options) {
+    const name = toolName(options.resolveTool);
+    let last;
+    let generation = 0;
+    let disposed = false;
+    let pending;
+    const unsubscribe = options.bridge.subscribe((snapshot) => {
+        if (disposed || snapshot.state !== 'ready')
+            return;
+        let url;
+        try {
+            url = readOpenAiDeepLink(snapshot.rawHostContext);
+        }
+        catch {
+            last = undefined;
+            generation++;
+            pending?.abort();
+            options.onFallback('invalid');
+            return;
+        }
+        if (url === undefined || url === last)
+            return;
+        last = url;
+        const current = ++generation;
+        pending?.abort();
+        if (!snapshot.hostCapabilities.serverTools) {
+            options.onFallback('unavailable');
+            return;
+        }
+        pending = new AbortController();
+        void options.bridge.callTool(name, { url }, pending.signal).then((result) => {
+            if (disposed || current !== generation || options.bridge.signal.aborted)
+                return;
+            if (result.isError)
+                options.onFallback('denied');
+            else
+                options.onResult(result, url);
+        }, () => {
+            if (!disposed &&
+                current === generation &&
+                !options.bridge.signal.aborted)
+                options.onFallback('denied');
+        });
+    });
+    return () => {
+        disposed = true;
+        generation++;
+        pending?.abort();
+        unsubscribe();
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}