@clone-ai/prompt-prediction 0.7.0-bootstrap.0 → 0.7.0

package/docs/reliability.md

@@ -0,0 +1,33 @@
+# Reliability and limits
+
+## Your composer must keep working
+
+Mount the editor and process typing, attachments, Undo, IME and manual send independently of Clone. Never await prediction in the normal send path, disable the input during prediction, or gate the whole product on Clone health. Hide suggestions on failures. Telemetry is best effort.
+
+SDK 0.7.0 uses a 15-second default client deadline (configurable up to 30 seconds) including response-body reads. The reusable server client limits concurrent requests to 16 by default and fails fast on saturation. The controller drops expired, canceled and identity-mismatched results. Recovery does not send anything automatically. A request whose outcome is unknown must retain its ID and body for reconciliation.
+
+## Configured limits are not measured capacity
+
+The developer console reports your app's current requests-per-minute limit and prediction time limit. These are configured limits, not a guarantee of sustained throughput, active users or an SLA.
+
+Before increasing traffic, measure latency, accepted versus rejected requests, timeouts and normal composer behavior in your integration. Ask Clone for a capacity review when your expected peak exceeds the app limit.
+
+Use optional `onMetric` on `createPredictionTransport` to observe duration, outcome and HTTP status without logging draft text. The [pilot validation guide](pilot-validation.md) covers real proxy fault injection and opt-in measurements.
+
+## Errors
+
+| Status / code | Integration behavior |
+| --- | --- |
+| 402 quota or configured hard limit | Hide suggestions; preserve manual input/send; do not activate payment automatically |
+| 429 `rate_limited` | Observe `Retry-After`; avoid per-keystroke retry loops |
+| 503 `prediction_capacity_exceeded` | Service temporarily at capacity; request rejected without a billable suggestion |
+| 503 `client_capacity_exceeded` | SDK client's local concurrency bound reached |
+| 502 / 503 / 504 | Hide candidate and preserve core service; reconcile the original ID if settlement is unknown |
+| malformed JSON / network / never returns | Bound the request and show no candidate; never lose the draft |
+| revoked connection | Clear local personalization state; do not retry the same work as a new anonymous request |
+
+## Required outage test
+
+Inject 503, 429, 402, network failure, malformed JSON and a never-resolving request into the real customer proxy. Type and edit text, use Undo/IME, ensure Tab without a candidate traverses focus, and send the exact draft once. Restore the proxy and verify fresh Tab acceptance without sending. Check both empty and nonempty drafts. Test Clone mode separately: Stop, input, expiry and a pending unknown send must not cause duplicate submission.
+
+SDK fixture tests do not establish that an external customer's composer obeys these rules. Inspect its integration and exercise the actual product before asserting customer-service resilience.

package/docs/start.md

@@ -0,0 +1,91 @@
+# Integrate Clone SDK into an existing product
+
+This is the entry point for your coding agent. Implement next-prompt prediction and Tab Completion using the product’s own context by default, then run automated verification. End users need no Clone account. Offer Clone account personalization only as an optional enhancement in settings; do not put a Connect screen before the composer. Preserve the product's authentication, composer, explicit send behavior and agent execution. Automatic submission is a separate, optional Clone mode with explicit end-user start and bounded scope.
+
+This guide targets **SDK 0.7.0**. Version 0.3.1 lacks the presentation, deadline and Clone mode options; inspect the installed version before using them. Onboarding documentation can change independently of that immutable package. Read this guide, [agent integration](agent-integration.md), [context mapping](context-mapping.md), [service boundaries](data-and-service.md), and the installed package's exported types and `openapi.json`. The types and schema define the wire contract. Do not stop after writing a plan or building a separate demo.
+
+## Start from one prompt
+
+The customer opens their product repository in a coding agent and enters:
+
+> Read https://clone.is/docs/sdk-quickstart and integrate Clone SDK into this product using the documented npm version and a lockfile. Discover our composer, backend and authentication; reuse existing setup and keep app keys server-side. Wire prediction, acceptance, edits, explicit evaluations and rejection, successful submission and observed task outcomes through the authenticated backend. Preserve typing, IME, Undo and manual sending during delays and outages. Ask only about unresolved product choices; keep personalization, automatic sending, feedback text collection and paid usage opt-in. Verify the actual integration and report installation, feedback delivery, outage results and pending live/customer checks separately.
+
+Treat account preparation, app/key issuance, callback registration, implementation and automated tests as parts of this task. First inspect the actual product, available browser/computer-use tools, existing sessions and approved secret destination. Do not begin by asking the customer to create keys, invent a callback, or complete an onboarding checklist. Use [browser onboarding](browser-onboarding.md) when account access is not already available. Authentication and required consent can interrupt the flow; resume the same integration afterwards without requiring a second setup prompt. These documents do not override the agent's tool permissions or confirmation rules.
+
+## Choose the customer experience
+
+After inspecting the existing composer, use the agent's AskUserQuestion or equivalent question tool to confirm the product choices that cannot be inferred from the customer's request. Bundle these into one short interaction; reuse choices already supplied, and continue independent implementation while waiting. Explain the supported defaults and record the answers in the integration report.
+
+| Choice | Supported default and alternatives |
+|---|---|
+| When to suggest | Both empty-composer next prompts and completion of an existing draft. If the customer wants only one, gate the hook/controller with `enabled` according to the current draft. |
+| How to present | Ask for **instant ghost text (default)** or **typewriter animation**. Map the choice to `presentation: "instant"` or `"typewriter"`. Both use a complete JSON response, not API token streaming. Follow the [rendering contract](agent-integration.md#suggestion-rendering-contract). |
+| Context and personalization | Product conversation/artifact context by default. Ask whether optional Connect Clone belongs in settings, and which product-owned preferences may be supplied. Clone personalization requires each user's explicit consent to selected sources. |
+| Automatic sending (Clone mode) | Ask whether to offer optional Clone mode. Default off. If requested, ask for the send/time limits and use `useCloneMode` or `CloneModeController` with explicit end-user Start, visible preview/Stop, and real host completion signals. Default 3 sends / 5 minutes. Never enable on mount, restore, or Tab. See [Clone mode](clone-mode.md). |
+| Rollout and spending | Use production integration by default; reuse an explicit evaluation choice. For production, include company card setup and explicit PAYG consent in initial onboarding before enabling production predictions. Keep card-free sandbox evaluation as a separate path. Ask about an end-user suggestion switch and rollout cohort. Budget alerts and a hard limit are separate choices; never activate paid use or a hard stop silently. |
+
+Do not ask customers to choose details the agent can discover, such as the framework, session store or callback route. Existing send behavior, Undo, IME safety and graceful failure are mandatory integration requirements rather than optional preferences.
+
+## 1. Register your app and settings
+
+Discover the customer's backend, session store, deployment origins and routing conventions. For basic integration, register an app with no callbacks (`redirect_uris: []`). Use the [production setup console](https://clone.is/developer/apps?setup=production) or [developer API](developer-apps.md) to register it and issue the app key. Reuse an existing verified Clone session or account token. Otherwise open the console with browser/computer use and follow [browser onboarding](browser-onboarding.md) to establish access. A separate management token is optional when the browser session is sufficient. A Clone operator and infrastructure access are not required for a verified account to register apps.
+
+| Setting | Agent action |
+|---|---|
+| `CLONE_API_URL` | Use `https://api.clone.is`, unless Clone supplied another environment. Do not append `/v1`. This is not a secret. |
+| `CLONE_APP_KEY` | Reuse the app's `clnp_...` key from the customer's backend secret store. If no app exists, create it through the console or developer API and save the returned key directly to that store using the supported secret-handling path. The key is shown once. |
+| `CLONE_CALLBACK_URL` | Optional. Only if the product offers Connect Clone, derive, implement and register an exact callback, and pass it to `clone.connect`. Basic predictions need no callback. |
+
+The developer account owns the app and billing; it is separate from the product’s end users, who need no Clone signup or login. Read [developer-apps.md](developer-apps.md) before mutation. List existing apps first, reuse their stable IDs, and update callbacks with `PATCH` and the current `config_revision`. On conflict, re-read and reconcile; do not overwrite another session's changes blindly. Keep the old callback registered while deploying its replacement if existing login attempts need to finish. Remove it afterwards: removal invalidates its pending connections, including issued but unexchanged codes. Completed user connections remain active.
+
+Production callbacks require HTTPS. A sandbox app can explicitly set `allow_loopback: true` for exact `http://127.0.0.1:<port>/<path>` callbacks. Wildcards, `localhost`, query strings and fragments are not supported. One developer account owns its app collection; all its apps share 1,000 sandbox predictions. Creating, rotating or disabling apps does not replenish that allowance. There is no automatic paid upgrade. Team ownership transfer is not self-service. After SDK billing is enabled for the service, the developer console supports explicit paid activation with a saved card; see [pricing and billing](billing.md). Integration alone never authorizes paid activation.
+
+Never print keys into chat, logs, screenshots, source code, callback URLs or `VITE_*`/`NEXT_PUBLIC_*` settings. Establish the secret-transfer path before issuing a key; the console shows it once. Verify secret presence without displaying values. Do not rotate a working key just because its plaintext is unavailable to the agent. Try the documented browser path before treating absent account credentials as a blocker. If login, email verification, repository access or secure storage still requires the customer, show the exact page and ask for only that action while continuing independent implementation and fixture tests. Do not create substitute accounts or fabricate credentials. See the browser guide for email verification and recovery.
+
+App registration enables predictions from customer-supplied context. Omit `connection_id` or send null for that mode. Optional Connect Clone adds explicitly selected, synced profile/Goal sources after per-user login/consent. Never discover a Clone identity from a customer email or infer consent from app ownership. Existing operator-provisioned pilot apps continue working but are not automatically claimed by a new developer account.
+
+### Complete company card setup before production installation
+
+Production integration is the default path: company account → app registration → pricing and card → SDK installation → verification. Use the separate **Try the free sandbox** path at `/developer/apps?setup=sandbox` only when the customer chooses evaluation. Do not silently fall back to sandbox if production card setup is canceled or unavailable.
+
+A newly registered app initially remains sandbox. Save its one-time key directly to the approved backend secret store before leaving the console for Stripe, then choose **I saved the key**. The console opens pricing and card setup for that same app. The customer must personally review the displayed unit price, authorize PAYG, and register the card on Stripe. Explain: **No charge when you register your card. Actual usage is billed monthly.** Reuse an existing company card through **Enable PAYG for this app**, with the customer's explicit consent, instead of creating another company or asking for another card.
+
+After the customer returns, the console calls billing sync and reads the app's authoritative billing state. Continue production installation only after the app is active with `plan: "paid"` and `payg: true` under an active company mandate. A success URL, card thumbnail, or `/sync` response alone is not proof. See [billing](billing.md) for readback and recovery. On cancel, pending setup, or processor failure, keep the same app and reconcile with **Refresh billing**. If setup is still incomplete, return through **Add company card and enable PAYG**; do not issue a new app/key or activate paid usage yourself. Inspection and preparation can continue while the customer completes the handoff.
+
+For the explicitly chosen sandbox path, save the key and continue without a card. Re-read that the app is actually sandbox; never describe an already-paid app as free merely because the URL contains `setup=sandbox`.
+
+## 2. Obtain and install the package
+
+Install the public npm package using the product's existing package manager:
+
+```sh
+npm install --save-exact @clone-ai/prompt-prediction@0.7.0
+```
+
+Commit the appropriate lockfile. Node 22.13+, ESM and React 18/19 are supported. Do not upgrade the entire host application without establishing compatibility. A Git submodule is not required.
+
+For a checksum-verified GitHub archive, follow [download and install](releases.md#download-and-install). Consume the built package instead of copying SDK implementation files into the product. See [release access and CI](releases.md#release-access-and-ci) for repeatable installs.
+
+## 3. Integrate with the product
+
+Follow [agent-integration.md](agent-integration.md) for the full backend routes, PKCE/session handling, errors, event attribution and acceptance cases. Use `CloneClient` in a JS/TS server. For another backend language, implement the same authenticated HTTP contract from `openapi.json`; do not introduce a second backend solely to use the client.
+
+Locate the real composer and successful-send callback. Prefer the headless React hook for an existing native textarea. Use the optional adapter only for an existing compatible assistant-ui runtime. Rich-text/contenteditable inputs require a controller-based insertion/Undo adapter. Keep the customer's editor, attachment/mention support and keyboard behavior.
+
+Optionally pass bounded `user_preferences` supplied by the customer product for its authenticated user. Supply current values on each request and update them when the user corrects a preference. Map actual conversation and artifact state using [context-mapping.md](context-mapping.md): video timelines, clip/time selection and known text summaries for video products; decks, selected slides and known slide text for slide products. Invalidate context on conversation/selection changes as well as artifact edits. Keep accepted or edited prediction origins distinct from independently typed text.
+
+Tab inserts a visible suggestion without sending. Escape dismisses it. The existing Enter/button sends exactly once. Errors, abstention and quota limits must preserve ordinary input/send. No Clone connection is the normal product-context mode. On logout disable prediction and clear candidates/attribution; on account switch bind a new session/context before re-enabling. On Clone disconnect clear the old candidate and connection, then use product context for subsequent new requests. An explicit invalid/revoked connection fails; never retry it as a new basic request automatically.
+
+## 4. Verify and hand off
+
+Run the customer's lint, typecheck, relevant tests and build. Use deterministic fixtures and Playwright in the actual product composer for the cases in [acceptance evidence](agent-integration.md#acceptance-evidence-to-return), including the first character after Tab, Undo, composition, context/account changes and failure recovery. Check event deduplication without additional billing. Synthetic composition checks do not prove native OS IME behavior.
+
+Once the chosen path is ready and its key is authorized, run at most four real prediction requests in total for bounded API verification. Sandbox requests use its shared allowance. Production verification requires the customer's explicit PAYG consent and adds usage charges: at $0.02 per valid suggestion, four suggestions cost at most $0.08. Basic mode needs no Clone test account or consent. Test optional personalization only when an authorized, consented test connection is available. Record abstentions and failures honestly. Do not increase the limit, activate paid use on the customer's behalf, or bypass login/consent. Do not require additional human real-use sessions or manual QA to finish the automated integration work. Report unavailable connected checks separately from passed fixture tests.
+
+Return a concise integration report with changed files, SDK version/checksum, commands/results, reproduction steps, secret **names** and deployment settings, and any external dependency such as SDK access, app issuance or user consent. Keep installation, fixture behavior, live API behavior and observed usefulness separate. Do not claim suggestion quality or production deployment from passing fixtures. Production deployment requires the customer's own authorization.
+
+## Credentials and optional MCP
+
+Prediction calls use the **Clone app key**. App management uses the owner's Clone browser session or an optional manual account API token, as documented in [developer apps](developer-apps.md). `CLONE_DEVELOPER_TOKEN` is only the suggested name for that optional token, not a required setup variable or runtime dependency. No additional service credentials are required for predictions. Ordinary fixtures need no service credentials.
+
+This documentation and the versioned package are sufficient inputs for an integration agent; no Clone docs MCP is required or currently supplied. A future read-only MCP could serve these same documents and schema. App/key/callback management uses the authenticated developer HTTP API; no MCP is needed.

package/examples/react/composer-events.ts

@@ -0,0 +1,3 @@
+// The host integration uses the packaged tracker rather than copying its logic.
+export { FeedbackTracker as ComposerEvents } from '../../src/feedback.js';
+export type { FeedbackEvent as ComposerEvent } from '../../src/feedback.js';

package/examples/react/demo.tsx

@@ -0,0 +1,195 @@
+import { StrictMode, useEffect, useMemo, useRef, useState } from 'react';
+import { createRoot } from 'react-dom/client';
+import { AssistantRuntimeProvider, ComposerPrimitive, useExternalStoreRuntime } from '@assistant-ui/react';
+import type { ThreadMessageLike } from '@assistant-ui/react';
+import { TabCompletionInput } from '../../src/react.js';
+import { CloneComposerInput } from '../../src/assistant-ui.js';
+import { createPredictionTransport } from '../../src/transport.js';
+import { createEventTransport } from '../../src/feedback.js';
+import type { CompletionRequest, PredictionTransport } from '../../src/types.js';
+import { CloneModeDemo } from './mode-demo.js';
+import { ComposerEvents } from './composer-events.js';
+import type { ComposerEvent } from './composer-events.js';
+
+const fixture = new URLSearchParams(location.search).get('connected') !== '1';
+const assistant = new URLSearchParams(location.search).get('assistant') === '1';
+const sessionId = crypto.randomUUID();
+
+function measure(body: Record<string, unknown>) {
+  if (!fixture) void fetch('/api/clone/metrics', { method: 'POST', headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ ...body, session_id: sessionId, observed_at: Date.now() }) }).catch(() => {});
+}
+type ConversationTurn = NonNullable<CompletionRequest['messages']>[number] & { role: 'user' | 'assistant' };
+
+const mockTransport: PredictionTransport = async (request, { signal }) => {
+  await new Promise(resolve => setTimeout(resolve, 50));
+  if (signal.aborted) throw new DOMException('Aborted', 'AbortError');
+  return { request_id: request.request_id, prediction_id: 'pred_' + request.request_id,
+    session_id: request.session_id, connection_id: request.connection_id ?? null,
+    draft_revision: request.draft.revision, context_revision: request.context_revision,
+    profile_revision: request.connection_id ? 'fixture-profile' : '', grant_revision: request.connection_id ? 1 : 0, status: 'suggested',
+    completion: request.artifact?.kind === 'video' ? ' 더 짧게 편집해줘.' : ' 결론부터 정리해줘.',
+    expires_at: Math.floor(Date.now() / 1000) + 60, context_truncated: false, usage: { prediction_units: 1 } };
+};
+
+function Demo() {
+  const [value, setValue] = useState('');
+  const [kind, setKind] = useState<'video' | 'slides'>('video');
+  const [revision, setRevision] = useState(1);
+  const [connection, setConnection] = useState('');
+  const [disconnecting, setDisconnecting] = useState(false);
+  const [receipts, setReceipts] = useState<string[]>([]);
+  const [conversation, setConversation] = useState<ConversationTurn[]>([
+    { role: 'assistant', content: '초안이 준비됐어요. 검토해주세요.', origin: 'agent' },
+  ]);
+  const [conversationRevision, setConversationRevision] = useState(1);
+  const [error, setError] = useState('');
+  const [faultsEnabled, setFaultsEnabled] = useState(false);
+  const [fault, setFault] = useState('none');
+  const [collectText, setCollectText] = useState(false);
+  const [guidance, setGuidance] = useState('');
+  const [lastRequest, setLastRequest] = useState('');
+  const [feedbackRevision, setFeedbackRevision] = useState('');
+  const composer = useRef<HTMLDivElement>(null);
+  const [events, setEvents] = useState<(ComposerEvent & { delivery: 'pending' | 'recorded' | 'failed' | 'cancelled' | 'fixture' })[]>([]);
+  const eventTransport = useMemo(() => createEventTransport('/api/clone/events'), []);
+  const telemetry = useMemo(() => new ComposerEvents((event, options) => {
+    setEvents(items => [...items.slice(-99), { ...event, delivery: fixture ? 'fixture' : 'pending' }]);
+    if (!fixture) return eventTransport(event, options);
+  }, { collectSubmittedText: collectText, onDelivery: receipt => {
+    if (fixture) return;
+    const delivery = receipt.status;
+    setEvents(items => items.map(item => item.event_id === receipt.event_id ? { ...item, delivery } : item));
+    measure({ ...receipt, delivery });
+  } }), [eventTransport, collectText]);
+  useEffect(() => () => telemetry.reset(), [telemetry]);
+  const observe = (event: Parameters<ComposerEvents['observe']>[0]) => {
+    if (event.kind === 'presented') setLastRequest(event.request_id);
+    telemetry.observe(event, composer.current?.querySelector('textarea')?.value ?? '');
+  };
+  const predictionTransport = useMemo<PredictionTransport>(() => fixture ? mockTransport : (request, options) =>
+    createPredictionTransport('/api/clone/predict', {
+      onMetric: metric => measure({ kind: 'metric', request_id: request.request_id,
+        duration_ms: metric.durationMs, status: metric.status, outcome: metric.outcome, code: metric.code }),
+    })(request, options), []);
+  const transport = useMemo<PredictionTransport>(() => async (request, options) => {
+    const result = await predictionTransport(request, options);
+    if (!options.signal.aborted) setFeedbackRevision(result.feedback_revision ?? '');
+    return result;
+  }, [predictionTransport]);
+  const context: Omit<CompletionRequest, 'draft' | 'mode' | 'request_id'> = {
+    connection_id: connection || null, session_id: sessionId, context_revision: `${revision}:${conversationRevision}`, language: 'ko',
+    messages: conversation,
+    artifact: { kind, id: kind === 'video' ? 'timeline-1' : 'deck-1', revision: String(revision),
+      selection: kind === 'video' ? 'clip-1 / 00:00–00:08' : 'slide-2', summary: '짧은 제품 소개 초안' },
+  };
+  function submitted(text: string) {
+    const origin = telemetry.submitted(text);
+    setReceipts(items => [...items, text]);
+    setConversation(items => [...items.slice(-29), { role: 'user', content: text, origin }]);
+    setConversationRevision(n => n + 1);
+  }
+  const messages: ThreadMessageLike[] = conversation.map(({ role, content }) => ({
+    role, content: [{ type: 'text', text: content }],
+  }));
+  const runtime = useExternalStoreRuntime({ messages, convertMessage: message => message, onNew: async message => {
+    submitted(message.content.filter(part => part.type === 'text').map(part => part.text).join(''));
+  } });
+  async function connect() {
+    try {
+      const response = await fetch('/api/clone/connect', { method: 'POST' });
+      const data = await response.json();
+      if (!response.ok) throw new Error(data.error);
+      location.assign(data.authorizeUrl);
+    } catch (cause) { setError(cause instanceof Error ? cause.message : 'Connection failed'); }
+  }
+  useEffect(() => {
+    if (!fixture) {
+      measure({ kind: 'session' });
+      void fetch('/api/clone/state').then(r => r.json()).then(data => {
+        setConnection(data.connection_id ?? ''); setFaultsEnabled(data.faults_enabled === true);
+      }).catch(() => setError('Example backend unavailable. Manual send still works.'));
+    }
+  }, []);
+  async function disconnect() {
+    telemetry.reset(); setDisconnecting(true); setError('');
+    try {
+      const response = await fetch('/api/clone/disconnect', { method: 'POST' });
+      if (!response.ok) throw new Error('Could not disconnect; retry or refresh connection.');
+      setConnection('');
+    } catch (cause) { setError(cause instanceof Error ? cause.message : 'Disconnect failed'); }
+    finally { setDisconnecting(false); }
+  }
+  async function readConnection() {
+    const response = await fetch('/api/clone/state');
+    const data = await response.json();
+    if (data.connection_id !== connection) telemetry.reset();
+    setConnection(data.connection_id ?? '');
+  }
+  return <main style={{ maxWidth: 700, margin: '60px auto', font: '16px/1.6 system-ui', padding: 24 }}>
+    <p style={{ color: '#64748b' }}>Clone · Tab Completion integration example</p>
+    <h1>Complete your next instruction</h1>
+    <p>{fixture ? 'Fixture mode: deterministic suggestions for interaction tests.' : 'API mode: suggestions from your product context. Clone personalization is optional.'}</p>
+    {faultsEnabled && <label>Local proxy fault <select aria-label="Local proxy fault" value={fault} onChange={event => {
+      const next = event.target.value;
+      void fetch('/api/clone/test-fault', { method: 'POST', headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ fault: next }) }).then(response => {
+          if (response.ok) { telemetry.reset(); setFault(next); setRevision(n => n + 1); }
+        }).catch(() => setError('Could not change the local test fault.'));
+    }}>{['none', '503', '429', '402', 'network', 'malformed', 'timeout', 'latency'].map(value =>
+      <option key={value} value={value}>{value}</option>)}</select></label>}
+    <label>Context <select aria-label="Context" value={kind} onChange={event => {
+      telemetry.reset();
+      setKind(event.target.value as 'video' | 'slides'); setRevision(n => n + 1);
+    }}><option value="video">Video timeline example</option><option value="slides">Slide deck example</option></select></label>
+    <p>Selected: {context.artifact?.selection} · revision {revision}</p>
+    {!fixture && <details><summary>Optional personalization</summary><p><button onClick={() => void connect()}>Connect Clone</button>{' '}
+      <button onClick={() => void readConnection()}>Refresh connection</button>{' '}
+      {connection && <button disabled={disconnecting} onClick={() => void disconnect()}>Disconnect</button>}{' '}
+      <span data-testid="connection">{connection ? 'Connected' : 'Product context'}</span></p></details>}
+    <p>Tab accepts a suggestion. You choose when to send.</p>
+    <div ref={composer} onInput={event => {
+      if (event.target instanceof HTMLTextAreaElement) telemetry.input(event.target.value);
+    }}>{assistant ? <AssistantRuntimeProvider runtime={runtime}><ComposerPrimitive.Root>
+      <CloneComposerInput aria-label="Instruction" rows={5} context={context} transport={transport} enabled={!disconnecting} onEvent={observe} />
+      <ComposerPrimitive.Send>Send</ComposerPrimitive.Send>
+    </ComposerPrimitive.Root></AssistantRuntimeProvider> : <form onSubmit={event => {
+      event.preventDefault(); if (value.trim()) { submitted(value); setValue(''); }
+    }}>
+      <TabCompletionInput aria-label="Instruction" rows={5} value={value} onValueChange={next => { telemetry.input(next); setValue(next); }}
+        context={context} transport={transport} enabled={!disconnecting} onEvent={observe}
+        onKeyDown={event => {
+          if (event.key === 'Enter' && !event.shiftKey && !event.nativeEvent.isComposing && event.keyCode !== 229) {
+            event.preventDefault(); event.currentTarget.form?.requestSubmit();
+          }
+        }} />
+      <button type="submit">Send</button>
+    </form>}</div>
+    <p role="alert">{error}</p>
+    <details><summary>Feedback loop · test fixture</summary>
+      <label><input type="checkbox" checked={collectText} onChange={event => setCollectText(event.target.checked)} />
+        Share edited submission text (optional)</label>
+      <p><button disabled={!lastRequest} onClick={() => telemetry.feedback(lastRequest, { rating: 'positive' })}>Helpful</button>{' '}
+        <button disabled={!lastRequest} onClick={() => telemetry.rejected(lastRequest, { reason: 'too_long' })}>Reject: too long</button></p>
+      <label>Feedback guidance <input value={guidance} onChange={event => setGuidance(event.target.value)} /></label>{' '}
+      <button disabled={!lastRequest || !guidance.trim()} onClick={() => {
+        telemetry.feedback(lastRequest, { rating: 'negative', guidance, content_opt_in: true }); setGuidance('');
+      }}>Send feedback</button>{' '}
+      <button onClick={() => {
+        if (!fixture) void fetch('/api/clone/clear-feedback', { method: 'POST' }).then(async response => {
+          if (!response.ok) throw new Error('Feedback clear failed');
+          setFeedbackRevision(''); setLastRequest(''); telemetry.reset();
+        }).catch(() => setError('Could not clear feedback.'));
+      }}>Clear feedback</button>
+      <p>Injected feedback revision: <code data-testid="feedback-revision">{feedbackRevision || 'none'}</code></p>
+    </details>
+    <h2>Host submit receipts · test fixture</h2>
+    <p data-testid="receipt-count">{receipts.length}</p>
+    <ul>{receipts.map((text, index) => <li key={index}>{text}</li>)}</ul>
+    <details><summary>Observation delivery · test fixture</summary>
+      <pre data-testid="observation-events">{JSON.stringify(events, null, 2)}</pre>
+    </details>
+  </main>;
+}
+
+createRoot(document.getElementById('root')!).render(<StrictMode>{new URLSearchParams(location.search).get('clone-mode') === '1' ? <CloneModeDemo /> : <Demo />}</StrictMode>);

package/examples/react/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Clone Tab Completion | Integration example</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/demo.tsx"></script>
+  </body>
+</html>

package/examples/react/mode-demo.tsx

@@ -0,0 +1,95 @@
+import { useEffect, useMemo, useState } from 'react';
+import { TabCompletionInput, useCloneMode } from '../../src/react.js';
+import { ComposerEvents } from './composer-events.js';
+import type { CompletionRequest, PredictionTransport } from '../../src/types.js';
+
+/** Local fixture only: no network, customer data, payment, or real agent execution. */
+export function CloneModeDemo() {
+  const [draft, setDraft] = useState('');
+  const attribution = useMemo(() => new ComposerEvents(() => {}), []);
+  const [presentation, setPresentation] = useState<'instant' | 'typewriter'>('instant');
+  const [fault, setFault] = useState('healthy');
+  const [busy, setBusy] = useState(false);
+  const [composing, setComposing] = useState(false);
+  const [revision, setRevision] = useState(1);
+  const [finished, setFinished] = useState(0);
+  const [receipts, setReceipts] = useState<{ text: string; origin: 'human' | 'agent' | 'accepted_prediction' | 'edited_prediction' }[]>([]);
+  const transport = useMemo<PredictionTransport>(() => async request => {
+    if (fault === 'pending') return new Promise(() => {});
+    if (fault === 'invalid') return JSON.parse('{invalid');
+    if (fault !== 'healthy') throw new Error(`Fixture ${fault}`);
+    return {
+      request_id: request.request_id, prediction_id: `pred_${request.request_id}`,
+      session_id: request.session_id, connection_id: null,
+      draft_revision: request.draft.revision, context_revision: request.context_revision,
+      profile_revision: '', grant_revision: 0, status: 'suggested',
+      completion: '이 영상을 30초로 줄이고 핵심 장면부터 보여줘.',
+      expires_at: Math.floor(Date.now() / 1000) + 60, context_truncated: false,
+      usage: { prediction_units: 1 },
+    };
+  }, [fault]);
+  const context: Omit<CompletionRequest, 'draft' | 'mode' | 'request_id'> = {
+    session_id: 'fixture-thread', context_revision: String(revision), language: 'ko',
+    messages: receipts.slice(-28).map(item => ({ role: 'user', content: item.text, origin: item.origin })),
+    artifact: { kind: 'video', id: 'fixture-timeline', revision: String(revision), summary: '제품 소개 초안' },
+  };
+  function submit(text: string, origin: 'human' | 'agent' | 'accepted_prediction' | 'edited_prediction') {
+    setReceipts(items => [...items, { text, origin }]);
+    setRevision(n => n + 1); setBusy(true);
+  }
+  const mode = useCloneMode({
+    transport, requestTimeoutMs: 1200, reviewMs: 3000,
+    input: { scopeId: 'fixture-user:fixture-thread', context, draft, enabled: true, busy, composing },
+    onSubmit: async (text, { origin, signal }) => {
+      if (signal.aborted) return false;
+      submit(text, origin); return true;
+    },
+  });
+  const active = !['off', 'stopped'].includes(mode.state.status);
+  useEffect(() => {
+    // A real host calls this from its completed-turn event with refreshed context.
+    if (finished > 0 && !busy && mode.state.status === 'waiting') mode.turnCompleted();
+  }, [finished, busy, mode.state.status, mode.turnCompleted]);
+  return <main style={{ maxWidth: 780, margin: '40px auto', padding: 24, font: '16px/1.6 system-ui' }}>
+    <p>Clone SDK 0.4.0 candidate · local interaction fixture</p>
+    <h1>Your composer stays in control</h1>
+    <p>These are deterministic suggestions. No external agent or billable API is called.</p>
+    <label>Suggestion display <select aria-label="Suggestion display" value={presentation}
+      onChange={event => setPresentation(event.target.value as typeof presentation)}>
+      <option value="instant">Instant (default)</option><option value="typewriter">Typewriter</option>
+    </select></label>{' '}
+    <label>Prediction service <select aria-label="Prediction service" value={fault}
+      onChange={event => { mode.stop(); setFault(event.target.value); }}>
+      {['healthy', '503', '429', '402', 'network', 'invalid', 'pending'].map(item => <option key={item}>{item}</option>)}
+    </select></label>
+    <form onSubmit={event => { event.preventDefault(); if (draft.trim()) { mode.stop(); submit(draft, attribution.submitted(draft)); setDraft(''); } }}>
+      <p>Tab inserts a fully visible suggestion. Enter or Send uses the normal host send path.</p>
+      <TabCompletionInput aria-label="Instruction" rows={4} value={draft} onValueChange={next => { attribution.input(next); setDraft(next); }}
+        onEvent={event => attribution.observe(event, draft)}
+        context={context} transport={transport} presentation={presentation} requestTimeoutMs={1200}
+        enabled={!busy && !active} onCompositionStart={() => setComposing(true)} onCompositionEnd={() => setComposing(false)}
+        onKeyDown={event => {
+          if (event.key === 'Escape') mode.stop();
+          if (event.key === 'Enter' && !event.shiftKey && !event.nativeEvent.isComposing && event.keyCode !== 229) {
+            event.preventDefault(); event.currentTarget.form?.requestSubmit();
+          }
+        }} />
+      <button type="submit">Send</button>
+    </form>
+    <section style={{ border: '1px solid #aaa', borderRadius: 12, padding: 20, marginTop: 24 }} aria-label="Clone mode">
+      <h2 style={{ marginTop: 0 }}>Optional Clone mode</h2>
+      <p>Start delegates up to 3 sends for 5 minutes. Each suggestion is shown for 3 seconds before sending.
+        Typing, Stop, errors or switching tabs stop the run. Already accepted sends cannot be recalled.</p>
+      <button disabled={active || busy || !!draft} onClick={() => mode.start()}>Start Clone mode</button>{' '}
+      <button disabled={!active} onClick={() => mode.stop()}>Stop</button>
+      <p role="status">{mode.state.status} · {mode.state.sent}/{mode.state.maxTurns} automatic sends {mode.state.reason ? `· ${mode.state.reason}` : ''}</p>
+      {mode.state.candidate && <blockquote data-testid="clone-preview">{mode.state.candidate.completion}</blockquote>}
+      <button disabled={!busy} onClick={() => { setBusy(false); setRevision(n => n + 1); setFinished(n => n + 1); }}>
+        Complete fixture agent turn
+      </button>
+      <p>The next send waits for this explicit host completion signal.</p>
+    </section>
+    <h2>Host send receipts: {receipts.length}</h2>
+    <ol>{receipts.map((item, index) => <li key={index}>{item.origin}: {item.text}</li>)}</ol>
+  </main>;
+}

package/examples/react/pilot-observations.ts

@@ -0,0 +1,57 @@
+import { appendFile } from 'node:fs/promises';
+import { createHmac, randomBytes } from 'node:crypto';
+
+const kinds = new Set(['session', 'prediction', 'presented', 'accepted', 'edited', 'dismissed', 'submitted', 'metric',
+  'rejected', 'feedback', 'outcome']);
+const sources = new Set(['fixture', 'live', 'fault']);
+
+/** Preserve the source of each prediction across late events and fault changes. */
+export function createPredictionSources(source: 'fixture' | 'live') {
+  const requests = new Map<string, 'fixture' | 'live' | 'fault'>();
+  return {
+    register(request: string, fault: boolean) {
+      if (!requests.has(request)) requests.set(request, fault ? 'fault' : source);
+      if (requests.size > 1000) requests.delete(requests.keys().next().value!);
+      return requests.get(request)!;
+    },
+    get(request: unknown) {
+      return typeof request === 'string' ? requests.get(request) : undefined;
+    },
+  };
+}
+
+/** Opt-in, local-only pilot measurements. Never store prompts, keys or user IDs. */
+export function createPilotRecorder(file?: string, source = 'fixture', pilot?: string) {
+  if (pilot && !/^[a-zA-Z0-9_-]{1,64}$/.test(pilot)) throw new Error('Use a non-personal pilot label');
+  const salt = randomBytes(32);
+  const hash = (id: unknown) => typeof id === 'string' && id.length <= 200
+    ? createHmac('sha256', salt).update(id).digest('hex').slice(0, 24) : undefined;
+  let pending = Promise.resolve();
+  return (input: Record<string, unknown>) => {
+    if (!file || !kinds.has(String(input.kind))) return;
+    const record: Record<string, unknown> = {
+      kind: input.kind, source: sources.has(String(input.source)) ? input.source : source,
+      recorded_at: Date.now(),
+    };
+    if (pilot) record.pilot = pilot;
+    if (typeof input.observed_at === 'number' && Math.abs(Date.now() - input.observed_at) < 86_400_000) {
+      record.observed_at = input.observed_at;
+    }
+    for (const name of ['request_id', 'session_id', 'event_id']) {
+      const value = hash(input[name]); if (value) record[name] = value;
+    }
+    if (typeof input.duration_ms === 'number' && Number.isFinite(input.duration_ms) && input.duration_ms >= 0) {
+      record.duration_ms = Math.min(120_000, input.duration_ms);
+    }
+    if (typeof input.status === 'number' && Number.isInteger(input.status) && input.status >= 0 && input.status <= 599) {
+      record.status = input.status;
+    }
+    if (['suggested', 'abstained', 'failed', 'cancelled'].includes(String(input.outcome))) record.outcome = input.outcome;
+    if (typeof input.code === 'string' && /^[a-z][a-z0-9_]{0,127}$/.test(input.code)) record.code = input.code;
+    if (['recorded', 'failed', 'cancelled'].includes(String(input.delivery))) record.delivery = input.delivery;
+    if (input.kind === 'outcome' && ['succeeded', 'failed'].includes(String(input.outcome))) record.task_outcome = input.outcome;
+    // Serialize append order; a recording failure is isolated from the composer.
+    pending = pending.then(() => appendFile(file, JSON.stringify(record) + '\n', { mode: 0o600 }))
+      .catch(() => { console.warn('Pilot observation could not be written'); });
+  };
+}