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

package/CHANGELOG.md

@@ -0,0 +1,120 @@
+# 0.7.0
+
+- Publish the JavaScript SDK as `@clone-ai/prompt-prediction`. Update imports, generated integration examples, archive names, npm verification and installation guides. Runtime exports and prediction behavior remain unchanged.
+
+# 0.6.4
+
+- Include public npm installation instructions in the distributed README and integration guides. Keep exact package versions and checksum-verified archive alternatives aligned, and point billing guidance to the API pricing page.
+- Allow a verified npm release to be published directly as `latest` or `next` through the configured trusted publisher. Preview publication remains the default.
+
+# 0.6.3
+
+- Keep pilot metrics and feedback events attributed to the originating prediction source. Fault tests remain separate from live and fixture usage after delayed responses, retries or source changes.
+- Include request attribution in example transport metrics and omit unrecognized observations instead of counting them as live usage. Attribution memory is bounded to the latest 1,000 predictions per example server.
+
+# 0.6.2
+
+- Keep successful submission events when an opted-in edited text exceeds the API content limit; omit the optional text instead of losing the event.
+- Clarify feedback integration: observe SDK insertions, human edits and Undo through the same value callback; keep the tracker stable between renders. The generated example already uses this wiring.
+
+# 0.6.1
+
+- Fix the example host proxy for an empty feedback-clear POST. Add an HTTP regression check for clearing and origin isolation.
+
+# 0.6.0
+
+- Packaged feedback tracker and bounded idempotent delivery.
+- Explicit evaluations, rejection and host-observed outcomes. Edited sent text remains opt-in and attributed.
+- Feedback revision and server-side memory clearing in JS and Python (0.2.0).
+- API contract for app/user/grant-scoped feedback memory; requires the matching server rollout.
+
+# Changelog
+
+## 0.5.0
+
+- Add optional content-free transport timing and outcome observations; broken observers do not affect predictions or submission.
+- Validate isolated customer proxies with opt-in latency and outage injection and private pilot observations. See [pilot validation](docs/pilot-validation.md).
+- Add a typed synchronous and asynchronous [Python client](https://github.com/cloneisyou/clone-sdk/blob/main/python/README.md) for all seven app-key operations, with bounded requests, safe errors and server-owned user identity.
+- Build and verify Python wheels on Python 3.11 and 3.14. Prepare separate, explicit npm and PyPI publication jobs tied to verified release distributions.
+
+## 0.4.0
+
+- Choose optional grapheme-safe typewriter presentation with `presentation: "typewriter"`; instant remains the default and Tab waits for the complete candidate.
+- Bound stalled SDK requests with prediction deadlines and server-side concurrency protection; cancellation also covers response-body reads. See [reliability](docs/reliability.md).
+- Offer explicitly started [Clone mode](docs/clone-mode.md) with preview, Stop, scope isolation, turn/time limits, agent attribution, and host completion acknowledgments.
+- Follow the [API guide](docs/api.md) and [agent installation guide](docs/start.md) for API Platform, installation choices, outage handling and personalization.
+- Try the local interaction example at `?clone-mode=1` to inspect preview, Stop and host completion behavior.
+
+## 0.3.1
+
+- Clarify installation, entry points and repository layout for public distribution.
+- Group generated types and the executable React demo by responsibility.
+- Clean build outputs and verify the actual package contents before packing.
+- Preserve HTTP body cancellation and reject malformed success envelopes without exposing response text.
+- Expand server authentication, PKCE, transport and packaging regression coverage.
+- Describe the hosted service through its public contract and document the publication review boundary.
+
+## 0.3.0
+
+- Align the one-prompt installation guide and billing documentation with the verified 0.3.0 package.
+- Allow an isolated browser-test port through `CLONE_SDK_TEST_PORT`.
+
+- Describe company-level PAYG, shared monthly invoices, alert budgets and opt-in hard limits.
+- Represent an unlimited PAYG usage cap as `null` and expose the billing model and cap scope in generated usage types.
+- Preserve prediction behavior and the existing runtime exports.
+
+## 0.2.1
+
+- Document app-key authentication and typed success/error responses in the SDK API contract.
+- Limit the contract to the seven app-key operations used by the server client.
+- Derive server client result types from the generated contract.
+- Exclude repository maintenance scripts from the installable package while retaining runnable examples.
+- Provide a public security contact and remove unnecessary internal testing details.
+
+## 0.2.0
+
+- Predict from product context without a Clone end-user account or connection.
+- Accept optional app-scoped user preferences; keep Clone profile/Goal personalization opt-in.
+- Invalidate candidates on changes between product context and Clone connections.
+- Update examples and agent onboarding so basic integrations need no callback.
+- `connection_id` is optional/nullable in requests and nullable in responses. App-only responses use an empty profile revision and grant revision zero. Existing connected requests retain their behavior.
+- Hosts must explicitly disable prediction on logout; absence of a Clone connection no longer disables it.
+
+
+## 0.1.6
+
+- Fix the README integration example to pass the required language field, so the copied TypeScript snippet compiles against the released package.
+- Use the public package type import in the host observation helper so it can be copied into a consumer without rewriting an internal source path.
+- Runtime exports and API schema are unchanged.
+
+## 0.1.5
+
+- Fix the examples losing the first typed character after accepting a suggestion when observation state updates during input capture.
+- Include submitted messages, their origins and updated conversation revisions in subsequent predictions for React and assistant-ui examples.
+- Verify exact edited text, manual corrections and history propagation in packaged consumer tests.
+- SDK runtime exports and API schema are unchanged. Live suggestion quality and customer-app acceptance remain separate checks.
+
+## 0.1.4
+
+- Executable React and assistant-ui examples now deliver presentation, acceptance, edit, dismissal and explicit-submission observations through the authenticated backend.
+- Preserve each observation ID across delivery retries; do not attribute manual submission after Undo or clearing removes a completion.
+- Include the host attribution helper in generated clean-consumer projects and extend browser acceptance tests.
+- SDK runtime exports and API schema are unchanged. Fixture observations do not prove suggestion quality or customer adoption.
+
+## 0.1.3
+
+- Private beta delivery through authenticated GitHub release downloads, checksum verification, and local archive dependencies.
+- Customer-agent prerequisites and CI instructions now describe repository access explicitly.
+- Release CI verifies authenticated download and installation; public npm publication is blocked while the repository is private.
+- Runtime behavior, API schema and the MIT license are unchanged.
+
+## 0.1.2
+
+First standalone open-source preview, following private package versions 0.1.0 and 0.1.1.
+
+- MIT-licensed headless controller, React input/hook, optional assistant-ui adapter, and server client.
+- Public API schema, agent integration guide, and synthetic video/slide examples.
+- Independent build, unit tests, Chromium interaction tests, and packaged React 18/19 consumer checks.
+- Separate public Git history, versioned release archives, and publication checks.
+
+Hosted service access is provisioned separately. This release does not establish live suggestion quality, native OS IME support, or acceptance in third-party applications.

package/CONTRIBUTING.md

@@ -0,0 +1,52 @@
+# Contributing
+
+Use Node 22.13+ and pnpm 11.19.0. Run `pnpm install --frozen-lockfile` from this repository. The default demo and all CI tests use synthetic data and need no API credentials.
+
+Before proposing a change, run:
+
+```sh
+pnpm generate:types
+git diff --exit-code -- src/generated/api-types.ts
+pnpm check
+pnpm exec playwright install chromium
+pnpm test:browser
+pnpm test:package
+pnpm check:public
+```
+
+For API contract changes, update `openapi.json` and regenerate the public types. Coordinate deployed service compatibility separately. Never copy an entire private service schema or implementation into this repository.
+
+Keep existing composer submission behavior intact. Test candidate insertion, Undo, dismissal, focus traversal, stale results, account/context changes, and composition handling when relevant. Browser composition events do not substitute for testing a native input method.
+
+Use synthetic examples. Do not submit credentials, private prompts, user conversations, customer names, internal links, screenshots of real accounts, or private repository history. Review your staged diff and author identity before pushing; public pull requests and workflow logs are public artifacts too. The automated checks are aids, not a complete disclosure review.
+
+Contributions are provided under this repository's MIT license. Declare any imported third-party code and preserve its license notices. Runtime dependencies retain their own licenses; no third-party runtime source is vendored here.
+
+This is the canonical SDK repository. Consume versioned npm packages or verified GitHub release archives in downstream applications. For local changes, build and pack this repository, then install the tarball in a consumer; do not maintain a second SDK source copy or add a Git submodule just to use the package.
+
+## Repository layout
+
+```text
+src/                    SDK implementation and stable entry points
+  generated/            Types generated from openapi.json
+examples/react/         Runnable React and assistant-ui demo, loopback backend
+scripts/                Build, package verification and example generator
+  lib/                  Shared publication checks
+tests/                  Unit tests for controller, HTTP and server boundaries
+  browser/              Composer interaction tests
+  scripts/              Build and publication regression tests
+docs/                   Integration, account, data and release guides
+.github/workflows/      Validation and opt-in release workflows
+```
+
+Keep the four package entry points stable. The controller owns prediction state; React owns native input interaction; HTTP decoding is shared by browser and server transports. Generated API types have one source of truth: `openapi.json`.
+
+The demo's loopback backend belongs under `examples/react`; it is not part of the runtime library. Build output is disposable and is cleaned before every build. The release manifest follows npm's actual file selection and checks each included file. `pnpm typecheck` also checks examples and test code. `pnpm test:scripts` checks cleanup and rejection of unintended package contents. Keep audit reports outside the repository.
+
+After moving source modules, regenerate and test the packed consumer. Update example-generator import mappings whenever example imports change. Never edit generated types directly.
+
+## Public documentation boundary
+
+Document the SDK, public request/response contract, customer-visible behavior and data-use commitments. Keep the hosted service implementation out of this repository, including model choices, internal prompts, algorithms, storage design, infrastructure and operational procedures. Treat service-issued identifiers and revisions as opaque values. A required payment or consent disclosure must remain accurate.
+
+Secret scanning does not establish that content is suitable for publication. Review prose, comments, generated files and the packed archive as well as code. Before making an existing repository public, review every branch and tag, Git history, pull requests, releases, Actions artifacts and logs. A clean latest commit does not sanitize those earlier records. Keep detailed audit findings in the private review location, not in public commits or release notes.

package/LICENSE

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

package/README.md

@@ -1,3 +1,121 @@
 # Clone SDK
 
-This registration version configures verified CI publishing. Use the documented SDK version from https://clone.is/docs/sdk-quickstart.
+Add next-prompt prediction and Tab completion to your existing composer. Suggestions appear as ghost text. **Tab inserts; your application decides when to send.**
+
+**SDK 0.7.0:** instant display remains the default. Set `presentation="typewriter"` for a cancellable display animation after the complete JSON response arrives; the API does not stream. These options and Clone mode are absent from the 0.3.1 package. Keep ordinary typing and sending available when predictions are loading, fail, or never return. See the [rendering contract](docs/agent-integration.md#suggestion-rendering-contract) before building a custom editor adapter.
+
+Use your product's conversation, selected artifact and user preferences as context. Your end users do not need a Clone account. Connecting a user's Clone context is optional.
+
+- **Headless controller** for custom editors.
+- **React hook and textarea**, plus an optional assistant-ui adapter.
+- **Server client** for prediction, usage and optional account connection.
+- **Python server client**, with sync and async interfaces. See [Python installation and usage](https://github.com/cloneisyou/clone-sdk/blob/main/python/README.md).
+- **Optional Clone mode**, explicitly started by the end user, with preview, Stop and bounded automatic sends. See [Clone mode](docs/clone-mode.md).
+- **Direct HTTPS API** for any backend or custom interface. See [API integration](docs/api.md).
+- **MIT licensed SDK.** The hosted prediction API is a separate service that requires a server-side app key. See [service boundaries](docs/data-and-service.md) and [billing](docs/billing.md).
+
+## Quick start
+
+Open your product repository in your coding agent and paste:
+
+```text
+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.
+```
+
+Your agent will handle setup, integration and verification. Production onboarding includes company account, app registration, pricing and card setup before SDK installation. You personally complete login, billing consent and card entry; no fee is charged at card registration. Choose **Try the free sandbox** for a separate card-free evaluation.
+
+<details>
+<summary>Manual setup</summary>
+
+First complete [production app and card setup](https://clone.is/developer/apps?setup=production), or explicitly choose the [free sandbox](https://clone.is/developer/apps?setup=sandbox). Save the one-time app key on your backend before leaving the console. Then install the package below.
+
+Node **22.13+**, ESM. React integrations support **18 and 19**. The headless controller and server client do not require React.
+
+Install the public npm package. Existing integrations can keep their pinned version while validating an upgrade:
+
+```sh
+npm install --save-exact @clone-ai/prompt-prediction@0.7.0
+```
+
+Use your project's package manager and commit its lockfile. Verified [GitHub release archives](docs/releases.md#download-and-install) remain available. Hosted API access requires a separate app key.
+
+```tsx
+'use client';
+import { useState } from 'react';
+import { createPredictionTransport } from '@clone-ai/prompt-prediction';
+import { TabCompletionInput } from '@clone-ai/prompt-prediction/react';
+
+const transport = createPredictionTransport('/api/clone/predict');
+
+export function Composer({ threadId, contextRevision }: {
+  threadId: string;
+  contextRevision: string;
+}) {
+  const [value, setValue] = useState('');
+
+  return (
+    <TabCompletionInput
+      aria-label="Instruction"
+      value={value}
+      onValueChange={setValue}
+      transport={transport}
+      context={{
+        session_id: threadId,
+        context_revision: contextRevision,
+        language: 'auto',
+        messages: [],
+      }}
+    />
+  );
+}
+```
+
+Implement `/api/clone/predict` in your authenticated backend using `CloneClient` from `@clone-ai/prompt-prediction/server`. Derive the user ID from the server session. Keep the app key on the server, never in browser code or `VITE_*` / `NEXT_PUBLIC_*` variables. Pass your real conversation and advance `context_revision` when it changes.
+
+For complete setup and verification, follow the [integration guide](docs/start.md).
+
+</details>
+
+## Try the demo
+
+```sh
+git clone https://github.com/cloneisyou/clone-sdk.git
+cd clone-sdk
+corepack enable
+pnpm install --frozen-lockfile
+pnpm dev
+```
+
+Open [localhost:4317](http://127.0.0.1:4317). Type, accept with Tab, then send explicitly. Add `?assistant=1` to try assistant-ui. The default demo uses synthetic suggestions and sends nothing to Clone.
+
+For a connected proxy, outage testing and private measurements, follow [pilot validation](docs/pilot-validation.md). Synthetic checks, real model calls and customer acceptance are separate evidence.
+
+## Choose an entry point
+
+| Import | Use it for |
+| --- | --- |
+| `@clone-ai/prompt-prediction` | Controller, browser transport, errors and public types |
+| `@clone-ai/prompt-prediction/react` | `useTabCompletion` or `TabCompletionInput` |
+| `@clone-ai/prompt-prediction/assistant-ui` | `CloneComposerInput` inside an existing assistant-ui composer |
+| `@clone-ai/prompt-prediction/server` | `CloneClient` and optional PKCE connection flow |
+
+The React input uses a native textarea. Rich-text editors need an insertion and Undo adapter around the controller. The assistant-ui adapter targets `@assistant-ui/react@0.15.21` and uses its `unstable_useComposerInput` hook; verify compatibility before upgrading it.
+
+## Develop
+
+```sh
+pnpm check
+pnpm exec playwright install chromium
+pnpm test:browser
+pnpm test:package
+```
+
+Package tests install the actual archive into React 18 and 19 consumers and verify build, Tab insertion, Undo, explicit send and context changes. These checks do not establish suggestion quality, native OS IME behavior or acceptance in your application.
+
+See [Contributing](CONTRIBUTING.md) for the repository layout and validation commands, [context mapping](docs/context-mapping.md) for request design, [reliability](docs/reliability.md) for outage handling and limits, and [Releases](docs/releases.md) for distribution.
+
+[Security](SECURITY.md) · [Changelog](CHANGELOG.md) · [MIT license](LICENSE)
+
+## Feedback loop
+
+SDK 0.7.0 can return explicit rejection, evaluations, edited successful submissions and host-observed outcomes to the API. Wire the packaged tracker to your host send and authenticated proxy. Text collection is off by default. See [feedback integration](docs/feedback.md) for scoped memory, delivery, expiry and clearing. These features require the API feedback deployment; event collection alone is not model learning.

package/SECURITY.md

@@ -0,0 +1,9 @@
+# Security
+
+Report suspected vulnerabilities privately to [contact@clone.is](mailto:contact@clone.is) with the subject **Clone SDK security report**. This is Clone's published [security and privacy contact](https://clone.is/privacy). It is available to all reporters, including people without repository access or an existing integration contact. Do not use public issues for security reports or include live keys, personal data, or account screenshots. Include the affected SDK version, impact and a synthetic reproduction.
+
+When this repository becomes public and private vulnerability reporting is enabled, GitHub's Security tab can also provide a private reporting form. Until that form is confirmed available, use the email address above.
+
+App keys and PKCE flow state belong on your authenticated server. This SDK does not replace your session authentication, CSRF checks, origin policy, or per-user connection storage. The included loopback backend uses one synthetic identity and in-memory state; it is not a production authentication example.
+
+The current preview is maintained on the latest 0.x version. There is no promised security-response SLA. Hosted service security and data-processing terms are separate from the SDK license.

package/dist/assistant-ui.d.ts

@@ -0,0 +1,5 @@
+import type { TabCompletionInputProps } from './react.js';
+/** Place inside your existing assistant-ui ComposerPrimitive.Root/runtime.
+ * Only reads/writes composer text; submission stays with the existing host form.
+ */
+export declare function CloneComposerInput(props: Omit<TabCompletionInputProps, 'value' | 'onValueChange'>): import("react/jsx-runtime").JSX.Element;

package/dist/assistant-ui.js

@@ -0,0 +1,26 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { unstable_useComposerInput } from '@assistant-ui/react';
+import { useState } from 'react';
+import { TabCompletionInput } from './react.js';
+/** Place inside your existing assistant-ui ComposerPrimitive.Root/runtime.
+ * Only reads/writes composer text; submission stays with the existing host form.
+ */
+export function CloneComposerInput(props) {
+    // This version-pinned public hook flushes external-store input updates before
+    // React restores the DOM, preserving native Undo and composition behavior.
+    const composer = unstable_useComposerInput({ disabled: props.disabled });
+    // Native edits also need immediate local state: an external store can render
+    // after React has already restored the old controlled value during execCommand.
+    const [local, setLocal] = useState({ value: composer.value, external: composer.value });
+    if (local.external !== composer.value)
+        setLocal({ value: composer.value, external: composer.value });
+    return _jsx(TabCompletionInput, { ...props, value: local.external === composer.value ? local.value : composer.value, onValueChange: value => { setLocal({ value, external: composer.value }); composer.setText(value); }, disabled: composer.isDisabled, onKeyDown: event => {
+            props.onKeyDown?.(event);
+            if (!event.defaultPrevented && event.key === 'Enter' && !event.shiftKey
+                && !event.nativeEvent.isComposing && event.keyCode !== 229 && composer.canSend) {
+                event.preventDefault();
+                composer.send();
+            }
+        } });
+}

package/dist/clone-mode.d.ts

@@ -0,0 +1,64 @@
+import type { CompletionRequest, PredictionOutput, PredictionTransport } from './types.js';
+export interface CloneModeInput {
+    /** Bind to the authenticated host user and thread. Never reuse across users. */
+    scopeId: string;
+    context: Omit<CompletionRequest, 'draft' | 'mode' | 'request_id'>;
+    draft: string;
+    enabled: boolean;
+    busy: boolean;
+    composing?: boolean;
+    visible?: boolean;
+}
+export interface CloneModeState {
+    status: 'off' | 'predicting' | 'reviewing' | 'submitting' | 'waiting' | 'stopped';
+    sent: number;
+    maxTurns: number;
+    candidate: PredictionOutput | null;
+    sendAt: number | null;
+    reason: string | null;
+}
+export interface CloneModeOptions {
+    transport: PredictionTransport;
+    /** Return true only after the host accepted the send. Unknown outcomes must not be retried. */
+    onSubmit: (text: string, metadata: {
+        requestId: string;
+        origin: 'agent';
+        signal: AbortSignal;
+    }) => Promise<boolean>;
+    reviewMs?: number;
+    requestTimeoutMs?: number;
+}
+/** Explicit, bounded delegation. Normal Tab completion never starts this controller. */
+export declare class CloneModeController {
+    private readonly options;
+    private input;
+    private disposed;
+    private scope;
+    private epoch;
+    private abort;
+    private timer;
+    private sessionTimer;
+    private pendingSubmission;
+    private submittedRevision;
+    private usedRequests;
+    private listeners;
+    private state;
+    constructor(options: CloneModeOptions);
+    getSnapshot: () => CloneModeState;
+    subscribe: (listener: () => void) => () => void;
+    private emit;
+    private identity;
+    private eligible;
+    update(input: CloneModeInput): void;
+    /** Call only from the end user's explicit Start action, never on mount or restore. */
+    start({ maxTurns, maxDurationMs }?: {
+        maxTurns?: number;
+        maxDurationMs?: number;
+    }): boolean;
+    stop(reason?: string): void;
+    /** Call after a real host turn finishes and its new context has been supplied via update(). */
+    turnCompleted(): boolean;
+    private predict;
+    private submit;
+    dispose(): void;
+}

package/dist/clone-mode.js

@@ -0,0 +1,156 @@
+import { withDeadline } from './deadline.js';
+/** Explicit, bounded delegation. Normal Tab completion never starts this controller. */
+export class CloneModeController {
+    options;
+    input = null;
+    disposed = false;
+    scope = '';
+    epoch = 0;
+    abort = new AbortController();
+    timer;
+    sessionTimer;
+    pendingSubmission = false;
+    submittedRevision = '';
+    usedRequests = new Set();
+    listeners = new Set();
+    state = { status: 'off', sent: 0, maxTurns: 3, candidate: null, sendAt: null, reason: null };
+    constructor(options) {
+        this.options = options;
+    }
+    getSnapshot = () => this.state;
+    subscribe = (listener) => { this.listeners.add(listener); return () => { this.listeners.delete(listener); }; };
+    emit(change) {
+        this.state = { ...this.state, ...change };
+        for (const listener of this.listeners)
+            listener();
+    }
+    identity(input) {
+        return JSON.stringify([input.scopeId, input.context.session_id, input.context.connection_id ?? null]);
+    }
+    eligible() {
+        return this.input?.enabled && this.input.visible !== false && !this.input.draft && !this.input.composing;
+    }
+    update(input) {
+        if (this.disposed)
+            return;
+        // Detach from host objects that may be mutated while a request is in flight.
+        const next = structuredClone(input);
+        const active = !['off', 'stopped'].includes(this.state.status);
+        const contextChanged = this.input && JSON.stringify(this.input.context) !== JSON.stringify(next.context);
+        this.input = next;
+        if (!active)
+            return;
+        if (this.identity(next) !== this.scope)
+            this.stop('scope_changed');
+        else if (!this.eligible())
+            this.stop(next.draft || next.composing ? 'user_input' : 'unavailable');
+        else if (['predicting', 'reviewing'].includes(this.state.status) && (contextChanged || next.busy))
+            this.stop('context_changed');
+    }
+    /** Call only from the end user's explicit Start action, never on mount or restore. */
+    start({ maxTurns = 3, maxDurationMs = 300_000 } = {}) {
+        if (this.disposed || !this.input || !this.eligible() || this.input.busy || this.pendingSubmission
+            || !['off', 'stopped'].includes(this.state.status))
+            return false;
+        if (!Number.isInteger(maxTurns) || maxTurns < 1 || maxTurns > 100
+            || !Number.isFinite(maxDurationMs) || maxDurationMs < 1000 || maxDurationMs > 3_600_000)
+            throw new Error('Invalid Clone mode limits');
+        this.stop('restarted');
+        this.abort = new AbortController();
+        this.scope = this.identity(this.input);
+        this.usedRequests.clear();
+        const epoch = this.epoch;
+        this.emit({ status: 'predicting', sent: 0, maxTurns, candidate: null, sendAt: null, reason: null });
+        if (epoch !== this.epoch)
+            return false;
+        this.sessionTimer = setTimeout(() => this.stop('time_limit'), maxDurationMs);
+        void this.predict();
+        return true;
+    }
+    stop(reason = 'user_stopped') {
+        this.epoch++;
+        this.abort.abort();
+        clearTimeout(this.timer);
+        clearTimeout(this.sessionTimer);
+        this.emit({ status: 'stopped', candidate: null, sendAt: null, reason });
+    }
+    /** Call after a real host turn finishes and its new context has been supplied via update(). */
+    turnCompleted() {
+        if (this.state.status !== 'waiting' || !this.input || this.input.busy || !this.eligible()
+            || this.input.context.context_revision === this.submittedRevision)
+            return false;
+        if (this.state.sent >= this.state.maxTurns) {
+            this.stop('turn_limit');
+            return false;
+        }
+        void this.predict();
+        return true;
+    }
+    async predict() {
+        const input = this.input;
+        const epoch = this.epoch;
+        const request = { ...input.context, connection_id: input.context.connection_id ?? null,
+            request_id: crypto.randomUUID(), mode: 'next_prompt', draft: { text: '', revision: 0 } };
+        this.emit({ status: 'predicting', candidate: null, sendAt: null });
+        if (epoch !== this.epoch)
+            return;
+        try {
+            const timeout = this.options.requestTimeoutMs ?? 15_000;
+            const candidate = await withDeadline(signal => this.options.transport(request, { signal }), Number.isFinite(timeout) ? Math.max(1, Math.min(timeout, 30_000)) : 15_000, this.abort.signal);
+            if (epoch !== this.epoch)
+                return;
+            if (!candidate || candidate.request_id !== request.request_id || candidate.session_id !== request.session_id
+                || candidate.context_revision !== request.context_revision || candidate.connection_id !== request.connection_id
+                || candidate.draft_revision !== 0 || !Number.isFinite(candidate.expires_at))
+                return this.stop('invalid_prediction');
+            if (candidate.status === 'abstained')
+                return this.stop('abstained');
+            if (candidate.status !== 'suggested' || typeof candidate.completion !== 'string' || !candidate.completion.trim())
+                return this.stop('invalid_prediction');
+            const delay = this.options.reviewMs ?? 2000;
+            const reviewMs = Number.isFinite(delay) ? Math.max(1000, Math.min(delay, 10_000)) : 2000;
+            const sendAt = Date.now() + reviewMs;
+            if (candidate.expires_at * 1000 <= sendAt)
+                return this.stop('expired');
+            this.emit({ status: 'reviewing', candidate, sendAt });
+            if (epoch === this.epoch)
+                this.timer = setTimeout(() => void this.submit(candidate, epoch), reviewMs);
+        }
+        catch {
+            if (epoch === this.epoch)
+                this.stop('prediction_failed');
+        }
+    }
+    async submit(candidate, epoch) {
+        if (epoch !== this.epoch)
+            return;
+        if (!this.input || !this.eligible() || this.input.busy
+            || candidate.expires_at * 1000 <= Date.now() || this.usedRequests.has(candidate.request_id))
+            return this.stop('not_ready');
+        this.usedRequests.add(candidate.request_id);
+        this.submittedRevision = this.input.context.context_revision;
+        this.pendingSubmission = true;
+        this.emit({ status: 'submitting', sendAt: null });
+        try {
+            if (epoch !== this.epoch)
+                return;
+            const accepted = await this.options.onSubmit(candidate.completion, { requestId: candidate.request_id, origin: 'agent', signal: this.abort.signal });
+            if (epoch !== this.epoch)
+                return;
+            if (!accepted)
+                return this.stop('send_rejected');
+            const sent = this.state.sent + 1;
+            this.emit({ status: 'waiting', sent, candidate: null });
+            if (sent >= this.state.maxTurns)
+                this.stop('turn_limit');
+        }
+        catch {
+            if (epoch === this.epoch)
+                this.stop('send_failed');
+        }
+        finally {
+            this.pendingSubmission = false;
+        }
+    }
+    dispose() { this.disposed = true; this.stop('disposed'); this.listeners.clear(); }
+}

package/dist/controller.d.ts

@@ -0,0 +1,61 @@
+import type { CompletionRequest, PredictionOutput, PredictionTransport } from './types.js';
+export interface CompletionInput {
+    value: string;
+    revision: number;
+    context: Omit<CompletionRequest, 'draft' | 'mode' | 'request_id'>;
+    focused: boolean;
+    composing: boolean;
+    selectionStart: number;
+    selectionEnd: number;
+    enabled?: boolean;
+}
+export interface CompletionState {
+    status: 'idle' | 'loading' | 'suggested' | 'unavailable';
+    candidate: PredictionOutput | null;
+    error: string | null;
+    /** Full in instant mode; a grapheme-safe prefix during optional animation. */
+    visibleCompletion: string;
+}
+export interface AcceptedCompletion {
+    value: string;
+    suffix: string;
+    requestId: string;
+}
+export interface CompletionOptions {
+    transport: PredictionTransport;
+    debounceMs?: number;
+    maxRequestsPerMinute?: number;
+    requestTimeoutMs?: number;
+    presentation?: 'instant' | 'typewriter';
+    onEvent?: (event: {
+        request_id: string;
+        kind: 'presented' | 'accepted' | 'dismissed';
+    }) => void;
+}
+/** Prediction lifecycle only. It has no submit, agent, or execution API. */
+export declare class CompletionController {
+    private readonly options;
+    private input;
+    private key;
+    private generation;
+    private timer;
+    private expiry;
+    private animation;
+    private deadline;
+    private abort;
+    private listeners;
+    private requestTimes;
+    private disposed;
+    private state;
+    constructor(options: CompletionOptions);
+    getSnapshot: () => CompletionState;
+    subscribe: (listener: () => void) => (() => void);
+    private emit;
+    private event;
+    private invalidate;
+    update(input: CompletionInput): void;
+    private predict;
+    accept(): AcceptedCompletion | null;
+    dismiss(report?: boolean): void;
+    dispose(): void;
+}