@tangle-network/chatgpt-agents-kit 0.1.0 → 0.1.1

package/CARDS.md

@@ -0,0 +1,118 @@
+# Optional agent cards
+
+Cards let people open an existing agent, submit a prompt, check the same task, and read its retained result.
+They use the kit’s existing tools and OAuth scopes.
+No browser token, task store, native client, or extra backend is introduced.
+
+The cards entry is additive and unpublished until the next authorized kit release.
+For local adoption, build and install this checkout’s npm tarball.
+
+```ts
+import { createAgentsHandler } from '@tangle-network/chatgpt-agents-kit'
+import { createAgentCards } from '@tangle-network/chatgpt-agents-kit/cards'
+
+const handler = createAgentsHandler({
+  metadata,
+  oauth,
+  nativeMcp: createMcpToolHandler,
+  bind,
+  cards: createAgentCards({ domain: 'https://your-dedicated-widget-origin.example' }),
+})
+```
+
+Use your actual dedicated HTTPS widget origin for a hosted ChatGPT submission.
+Omit `domain` for local compatible-host development.
+Omit `cards` to retain the existing tools-only protocol.
+The main package entry does not import React, UI components, or the embedded HTML.
+The optional entry bundles all JavaScript and CSS; the widget makes no direct network requests.
+
+## Contract
+
+The existing `list_my_agents`, `connect_my_agent`, `prompt_agent`, and `get_task` tools receive `_meta.ui.resourceUri` when cards are enabled.
+The same authenticated handler serves `resources/list` and `resources/read` with `text/html;profile=mcp-app`.
+Resource CSP declares no network or external asset domains.
+Text and structured tool results remain available to clients that do not render UI.
+Native actions, OAuth, scope checks, and workspace authorization run through the existing dispatcher.
+
+The widget uses the official MCP Apps `App` bridge, with host theme and resize support.
+It reuses Tangle Brand tokens and the maintained Tangle UI Button, Input, and Textarea components.
+Only tools granted in the current native binding are offered as actions.
+A read-only grant does not expose a prompt form, even when the model can discover a consent-upgrade tool.
+Hosts without tool-call support display results and direct users back to chat.
+
+Current GTM discovery returns workspace IDs without conversation IDs.
+For those rows, cards require an existing conversation ID supplied by the user.
+They do not invent a thread, create a conversation, or expose unsupported thread discovery.
+Opening a card from a known `connect_my_agent` or `get_task` result skips that input.
+
+Submission requires an explicit click and includes the connected agent’s native `contextVersion` and a fresh `turnId`.
+A lost response offers a read of that same task; it never automatically resubmits.
+A failed recovery read retains that original task identity.
+When ChatGPT supports widget state, the card saves only the app/account identity, native target, task ID, and phase before admission.
+After iframe recreation it checks the current authenticated identity and rereads the native task.
+A restored card ignores host-replayed results; it renders only the fresh authorized native read.
+A different account cannot use the saved handle; an unverified task remains unavailable until its native read succeeds.
+The card also consumes complete host tool input when the host initiated a prompt call.
+Widget state holds no prompt, output, token, or authoritative task data and is not cross-session storage.
+An explicit task lookup failure keeps an editable task ID and a route back to the agent list.
+Kit validation and context checks mark pre-admission rejection with `error.admission: not-started`; cards then offer reconnect and preserve the prompt draft.
+Refresh always reads the original workspace, conversation, and task.
+When supported, the widget updates model context for task, directory, agent, loading, and failure transitions.
+The context describes the current selection and retained identity without output text.
+It never sends output text as instructions or starts a follow-up model turn.
+
+The UI displays native states without fabricated percentages.
+“Completed” requires `completionVerified: true` from the kit.
+Unverified outputs stay unavailable, and failed refreshes clear previously displayed results.
+Results render as text, retaining whitespace, file revision, and SHA-256 evidence.
+Cancellation, approval, provisioning, and messaging remain in the existing conversational tools; cards add no automatic actions.
+
+## Installed example and verification
+
+From the repository root:
+
+```sh
+npm ci --no-audit --no-fund
+npm run build --workspace @tangle-network/chatgpt-agents-kit
+npm run test:cards --workspace @tangle-network/chatgpt-agents-kit
+npx playwright install chromium
+npm run proof:cards --workspace @tangle-network/chatgpt-agents-kit
+npm run proof:cards:lifecycle --workspace @tangle-network/chatgpt-agents-kit
+```
+
+The browser proof packs the compiled kit and installs it outside the checkout.
+A consumer module imports the public package and `./cards` entry through ordinary Node resolution.
+Both GTM and Workspace configurations use that same installed renderer and the maintained Agent App MCP dispatcher.
+Their distinct workspace, thread, turn, and execution IDs are checked against the existing deterministic SQLite test host.
+The same task is refreshed and reopened without another admission.
+The lifecycle proof recreates the iframe after an accepted admission with a lost response.
+It checks the same task UUID, one native admission, renewed-account recovery, different-account denial, context changes, and partial theme updates.
+The installed package test imports both the root and `/cards` exports with install scripts disabled.
+
+The proof captures matching tool-only and rendered desktop/mobile images, light/dark themes, original interaction videos, keyboard use, and accessibility checks.
+It also checks an empty list, a read-only grant, changed output revisions, and revoked access after a successful result.
+Artifacts are written under `plugins/agents/receipts/cards/` and excluded from the published package.
+
+To keep the example running for manual inspection:
+
+```sh
+CARDS_PORT=4399 node plugins/agents/cards/example.mjs
+```
+
+Open the printed GTM and Workspace URLs.
+The example uses deterministic test data and test credentials confined to the local server.
+It does not connect to a hosted Tangle account or execute a model.
+Do not deploy this test host.
+
+Hosted OAuth, live native execution, and an actual ChatGPT installation remain separate acceptance steps owned by each adopting application.
+Install the released kit, enable cards on its existing authenticated endpoint, refresh tool discovery in ChatGPT, and repeat the same native identity/result checks.
+The local example is not evidence that those hosted steps passed.
+
+## Maintained contracts consulted
+
+- [OpenAI: Add UI to your MCP server](https://developers.openai.com/plugins/build/chatgpt-ui)
+- [OpenAI: Plugin UI reference](https://developers.openai.com/plugins/reference)
+
+Checked October 2, 2026.
+OpenAI recommends separate rendering tools when repeated iframe refreshes hurt a workflow.
+These compact cards attach to the existing tools to avoid duplicate public operations; their authenticated native results already contain the required data.

package/README.md

@@ -414,3 +414,9 @@ Root foundation owns the repository marketplace, lockfile and shared tooling.
 Official specifications reviewed on 2026-09-30:
 - https://developers.openai.com/plugins/build/plugins
 - https://developers.openai.com/plugins/build/auth
+
+## Optional agent cards
+
+Enable the separate `@tangle-network/chatgpt-agents-kit/cards` entry to render agents and verified task results through MCP Apps.
+See [CARDS.md](./CARDS.md) for setup, installed examples, and the hosted acceptance boundary.
+Omitting the option preserves tools-only clients.

package/dist/cards/server.d.ts

@@ -0,0 +1,6 @@
+import type { AgentCardsResource } from '../src/cards.ts';
+/** Bundled at release build time; compatible with Workers and Node, without filesystem access. */
+export declare function createAgentCards(options?: {
+    domain?: string;
+}): AgentCardsResource;
+export type { AgentCardsResource } from '../src/cards.ts';