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

package/CARDS.md

@@ -4,8 +4,8 @@ Cards let people open an existing agent, submit a prompt, check the same task, a
 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.
+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'
@@ -28,7 +28,9 @@ The optional entry bundles all JavaScript and CSS; the widget makes no direct ne
 
 ## Contract
 
-The existing `list_my_agents`, `connect_my_agent`, `prompt_agent`, and `get_task` tools receive `_meta.ui.resourceUri` when cards are enabled.
+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.
@@ -40,10 +42,13 @@ 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.
+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.
@@ -64,7 +69,15 @@ 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.
+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
@@ -78,6 +91,7 @@ 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.
@@ -89,10 +103,13 @@ The lifecycle proof recreates the iframe after an accepted admission with a lost
 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.
+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

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

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.