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

package/CARDS.md

@@ -0,0 +1,135 @@
+# 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 optional cards entry is available in the published kit.
+This revision adds named discovery and a new versioned UI resource; release it before updating hosted consumers.
+
+```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 agent and task tools receive `_meta.ui.resourceUri` when cards are enabled.
+The renderer uses `ui://tangle-agents/cards-v2.html` so hosts do not reuse the earlier cached interface.
+Optional `list_my_threads` and `list_my_tasks` tools use the same resource.
+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.
+
+Hosts can supply `NativeServices.listThreads` and `listTasks` to expose named conversations and recent work.
+Thread discovery requires the existing list and connect grants; task discovery requires list and task grants.
+The kit checks visible workspaces, each returned target, and the live grant before returning bounded summaries.
+Task discovery supports optional workspace and conversation filters, search, cursors, and pages of at most ten results.
+Cards search and paginate actual native results without creating or restarting work.
+Hosts without discovery retain an advanced reference field and an app link when the host supports opening links.
+No conversation title, target, or app route is invented.
+
+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.
+Markdown results use the maintained Tangle UI sanitizer; other text retains whitespace.
+Images make no external requests, and supported external links open through the host bridge.
+File revisions and SHA-256 evidence remain in collapsed source details.
+Downloads appear only when the host advertises `downloadFile` and export the exact retained bytes through that bridge.
+The card does not implement a direct iframe download fallback.
+“Revise result” reconnects the same native target and opens an editable request; only explicit submission starts another task.
+The revision includes the original execution and response hash or file revisions, preserving the reviewed result.
+Settled failed or input-required responses remain readable when verified, without claiming completion.
+A missing or changed partial file does not discard that verified non-completion response.
+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
+node plugins/agents/cards/proof-ux.mjs
+```
+
+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 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.
+
+The document proof checks initial host-driven directory search, pagination, exact download bytes, an explicit revision, and reopening the original result.
+Its document is deterministic fixture content, not model output or customer research.
+
+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

@@ -81,26 +81,25 @@ engine, provider connection or billing ledger is implemented here.
 direct GTM route exposes file handoff or every generic action.
 The chat config follows a GTM source lane and is not hosted acceptance.
 
-## Readiness: what this PR does and does not prove
-
-The generator produces portable plugin packages. The adapter authenticates every
-protected request, discovers only available/permitted native operations, retains
-native target IDs, and refuses to verify success without execution-linked output
-revisions and retrieved bytes. The GTM adapter implements the reviewed
-workspace/thread/vault mappings, including create-only/update preconditions and
-partial creation receipts. Text files are supported; binary upload is not.
-
-**GTM is not yet a usable hosted OAuth plugin at the inspected revision.**
-`gtm-agent/src/lib/.server/auth-utils.ts` routes every Authorization header to
-`authenticateOperatorApi`; that verifier accepts the native `gak_` store, not
-resource-bound OAuth. Its current Hub OAuth scopes also do not grant GTM's
-`operator:*` scopes. Pointing ChatGPT at these endpoints or forwarding a Hub
-access token would be wrong. This PR does neither. A real GTM mount still needs
-an existing-identity OAuth/native authorization binding and persisted turn
-admission/observation ports. These are explicit host inputs, **not implemented
-backend services hidden behind stubs**. The second configuration likewise needs
-its real host binding. No hosted endpoint, OAuth login, ChatGPT installation,
-native GTM task, second product task, or provider delivery was executed.
+## Verified release and remaining acceptance
+
+On October 2, 2026, `@tangle-network/chatgpt-agents-kit@0.1.1` was publicly available from npm.
+A fresh external consumer installed that release, used its compiled CLI, and generated a plugin with the registered app connection.
+The generated GTM plugin was installed in ChatGPT and completed one authorized task in an existing workspace and conversation.
+After reload and reconnect, it returned the same retained output and native execution references.
+That fixed-response task establishes transport and continuity, not the quality of useful customer work.
+
+This evidence applies to that GTM connection and release.
+It does not establish Creative activation, ordinary Builder agents, phone continuity, or hosted result-card behavior.
+Those flows need their own acceptance through the deployed app.
+The current source skills guide discovery by name, useful deliverables, revision, and returning later.
+Install the release containing those changes before evaluating their hosted behavior.
+Their meaningful-work acceptance remains separate from source, package, and fixture checks.
+
+Every adopting app still owns its OAuth binding, native admission, authorization, and retained outputs.
+The generator creates a package; it neither implements missing host services nor grants capabilities.
+The adapter requires execution-linked output evidence before verifying completion.
+Text file support, when exposed by the host, handles UTF-8 content rather than binary uploads.
 
 The tests use the **unmodified, hash-verified maintained agent-app MCP envelope**
 and a test-only SQLite contract fixture. That fixture genuinely reads randomized
@@ -116,15 +115,15 @@ OAuth MCP endpoint; the app keeps its native account, agent profile, workspace,
 thread, task state, permissions and execution evidence. Package generation does
 not provision an agent or add capabilities to the endpoint.
 
-Before the first approved npm release, install an actual built kit tarball in
-your app directory. No checkout or TypeScript loader is needed by the adopter:
+Install this release in your app directory:
 
 ```sh
-npm install --ignore-scripts /absolute/path/tangle-network-chatgpt-agents-kit-0.1.0.tgz
+npm install --save-exact --ignore-scripts @tangle-network/chatgpt-agents-kit@0.1.2
 ```
 
-After publication, an approved exact registry version can replace the tarball.
-Neither this command nor the generator publishes anything.
+Use the approved exact version when adopting a later release.
+No repository checkout or TypeScript loader is required.
+Neither installation nor package generation publishes anything.
 Create `app.json` using your own application origin and display metadata (the
 `.example` origin below is a placeholder, not a deployed service):
 
@@ -184,33 +183,13 @@ import { createAgentsHandler, type NativeBinding } from '@tangle-network/chatgpt
 import { createGtmBinding } from '@tangle-network/chatgpt-agents-kit/gtm'
 ```
 
-The source repository remains private. Packaging and a local install do not
-publish the kit or make a hosted ChatGPT connection available. After an approved
-release, consumers can pin `@tangle-network/chatgpt-agents-kit@0.1.0` from npmjs.
-A Tangle npm organization owner must bootstrap `0.1.0` from the reviewed merged
-source. They must authenticate to npmjs, inspect the full organization package
-inventory with owner access, and stop if the name already exists as restricted.
-These CLI checks help confirm the account and status:
+The public npm package is available independently of source repository access.
+Installing it does not deploy the app's endpoint or register a ChatGPT connection.
+Follow [installed-kit setup](./SETUP.md) for registration, generation, and the customer journey.
 
-```sh
-npm whoami --registry=https://registry.npmjs.org/
-npm view @tangle-network/chatgpt-agents-kit name version --json --registry=https://registry.npmjs.org/
-npm access get status @tangle-network/chatgpt-agents-kit --json --registry=https://registry.npmjs.org/
-```
-
-An `E404` from `npm view` can mean absent or inaccessible. `npm access get status`
-reports `private` even for an absent name. Neither result proves absence. Once
-the owner confirms the name is absent, they can run this from the merged source:
-
-```sh
-npm publish --workspace @tangle-network/chatgpt-agents-kit --ignore-scripts --access public --registry=https://registry.npmjs.org/
-```
-
-The manual `Publish Agents kit` workflow handles later versions only after the
-package is public. It requires a repository-owned `NPM_PUBLISH_TOKEN` with
-publish access to the Tangle npm scope. The workflow passes no access override
-and stops unless the package is already public. It does not deploy an MCP
-endpoint or install a ChatGPT plugin.
+Maintainers publish a reviewed version through the repository's `Publish Agents kit` workflow or its authorized release path.
+The workflow requires an existing public package and repository-owned npm publication credentials.
+Publication does not establish hosted app acceptance.
 
 For development, a GTM pnpm consumer can also install a commit-pinned Git
 subdirectory without copying this package:
@@ -274,8 +253,9 @@ No process-global inspection credential is retained.
 
 `createGtmBinding` in `src/gtm.ts` maps normal native routes. It has **no API-key
 parameter**. Its `request` callback must already be authorized as the resolved
-native identity; the current GTM source does not provide a turnkey OAuth-native
-request dispatcher. The `turns` ports must use the persisted agent-app chat
+native identity through the app's existing authorization path.
+The adapter does not supply an OAuth-native request dispatcher.
+The `turns` ports must use the persisted agent-app chat
 vertical, saved profile, native turn UUID admission/deduplication, retained
 terminal state and execution-linked file revisions. HTTP 200 or an open stream
 is not an admission or completion implementation. Missing ports hide delegation
@@ -299,12 +279,12 @@ substitute for `hosted-agent/application` continuation of the existing agent.
 
 ## Consumer workflow and receipts
 
-The skill offers **Connect my agent**, and offers **Create an agent** only when
-native discovery advertises it. It requires review of the exact brief/files,
-preserves workspace/thread/profile, treats files as data rather than new
-instructions, handles pending native decisions as delegated responses, and
-requires explicit review before messaging. No `approved: true` field is treated
-as proof that a human approved an operation.
+The skills find existing work by name through discovered tools and present its actual result.
+They retain native references internally for review, revisions, and returning later.
+Creation is offered only when requested and supported.
+Clear user instructions authorize their stated effects; ambiguous or new effects need clarification.
+File contents remain data, and native permission and approval controls still apply.
+No `approved: true` field proves that a human approved an operation.
 
 Handoff receipts distinguish the input hash from stored-byte verification.
 Acceptance rereads the stored input. Completion receipts require the retained
@@ -414,3 +394,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/SETUP.md

@@ -8,16 +8,16 @@ missing. Start with the app's reviewed endpoint, not a GTM connection ID.
 
 ## 1. Install the reviewed kit
 
-Use Node >=22.16 and npm >=10. Until an approved public release is available, get
-the built tarball from the release owner and install it in your own app project:
+Use Node >=22.16 and npm >=10.
+Install this release in your own app project:
 
 ```sh
-npm install --ignore-scripts --no-audit --no-fund /absolute/path/tangle-network-chatgpt-agents-kit-0.1.0.tgz
+npm install --save-exact --ignore-scripts --no-audit --no-fund @tangle-network/chatgpt-agents-kit@0.1.2
 npm ci --ignore-scripts --strict-peer-deps --no-audit --no-fund
 npm exec --no -- tangle-agents-plugin --help
 ```
 
-Use the approved exact version after publication, not an assumed npm release.
+Use the approved exact version when adopting a later release.
 `npm exec --no` uses the installed binary without fetching a replacement. Neither
 these commands nor the generator publishes anything. No repository checkout,
 workspace link, TypeScript loader or install hook is required by the consumer.
@@ -149,7 +149,43 @@ test in a new chat. A package import is separate from hosted tool calls. A local
 marketplace is optional and is not written into your home directory by this CLI.
 Public directory submission/review is a separate release-owner operation.
 
-## 5. Prove continuation, not just import
+## Refresh tools and update skills
+
+The registered app connection and generated plugin package have separate update paths.
+After deploying changed server tools, refresh the registered app's tool catalog.
+In the ChatGPT plugin UI checked on October 3, 2026 UTC:
+
+1. Open the registered app, such as Tangle GTM Agent.
+2. Choose **More actions → Manage → Manage app → Refresh tools**.
+3. Wait for refresh to finish, then reload the app details and inspect its tools.
+4. Open a new chat and make a read-only request using the changed tools.
+   Confirm the expected tools appear in the tool activity.
+
+A live `agent_capabilities` response can describe new tools while ChatGPT still holds the previous callable catalog.
+After refreshing, verify the callable tools in a new chat while keeping the same agent and workspace.
+
+For changed skills or package metadata, generate a new archive with the same plugin name.
+On the generated plugin, choose **More actions → Upload new version** and upload that archive.
+Then test the updated skills in a new chat.
+Uploading the package and refreshing server tools are distinct checks; neither proves task execution or completed work.
+
+## 5. Prove a useful customer journey
+
+Start with ordinary requests in the installed plugin:
+
+1. “Show my agents and help me choose what to work on.”
+2. “In [existing project], draft [a concrete useful deliverable] using [selected context].”
+3. “Change [a specific part] and keep [the correct facts or constraints].”
+4. In a new conversation, “Find my work on [project or task name] and show where we left off.”
+
+The customer should choose recognizable names and receive the actual work.
+Use supported discovery to resolve technical references internally.
+When discovery is unavailable or ambiguous, state what is missing and ask for a recognizable choice or existing-work link.
+Keep identifiers, hashes, and revisions in the acceptance receipt instead of the default customer response.
+Evaluate usefulness, preserved facts, requested changes, and whether the customer can return without operator assistance.
+A fixed response proves transport, not this journey's value.
+
+For the technical acceptance receipt:
 
 In the actual installed plugin, call `agent_profile` and `agent_capabilities` and
 inspect the real available tools. Connect to the same existing agent, workspace
@@ -207,5 +243,5 @@ to `receipts/agents-packaged-generator.json` by the existing harness.
 This is **installed package and local anonymous HTTP proof**, not hosted OAuth,
 ChatGPT import/calls, native task execution, output retrieval, reconnect,
 messaging delivery or authenticated foreign-customer denial. Publication,
-Native50 OAuth, Native60 admission, Builder/ADC release changes and Creative
-feature flags remain their owners' work; this flow changes none of them.
+OAuth, native admission, app deployments, and feature activation remain each host's responsibility.
+This setup flow changes none of them.

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';