@webless/agent 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Webless AI
+
+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

@@ -0,0 +1,121 @@
+# `@webless/agent`
+
+Webless Agent SDK — Eve runtime client, React UI, embed mount API, and IIFE bundle builder.
+
+## Install
+
+```bash
+npm install @webless/agent eve react react-dom
+```
+
+`react` and `react-dom` are required for `@webless/agent/react` and `@webless/agent/embed`.
+
+## Headless client
+
+```ts
+import { createAgentClient, pingAgentHealth } from "@webless/agent";
+
+const health = await pingAgentHealth("https://runtime.staging.webless.ai");
+console.log(health.ok ? "ready" : health.detail);
+
+const agent = createAgentClient({
+  indexId: "YOUR_PUBLISHED_INDEX_ID",
+  runtimeOrigin: "https://runtime.staging.webless.ai",
+});
+
+const reply = await agent.sendTurn("What can you help me with?", {
+  handlers: {
+    onDelta: (delta) => process.stdout.write(delta),
+  },
+});
+```
+
+## React UI
+
+```tsx
+import { AgentRail, useAgentChat } from "@webless/agent/react";
+import "@webless/agent/react.css";
+
+function AssistPanel({ indexId }: { indexId: string }) {
+  const { state, submit } = useAgentChat({ indexId });
+
+  return (
+    <AgentRail
+      state={state}
+      onSubmit={(message) => void submit(message)}
+      onFollowUpSelect={(label) => void submit(label)}
+    />
+  );
+}
+```
+
+## Embed API (programmatic mount)
+
+```ts
+import { mountAgent, unmountAgent } from "@webless/agent/embed";
+
+const handle = mountAgent({
+  manifest: {
+    customerId: "cust_123",
+    indexId: "idx_abc",
+    runtimeOrigin: "https://runtime.staging.webless.ai",
+    placement: { side: "right", along: 50, inset: 0, variant: "outline" },
+  },
+});
+
+handle.open();
+handle.close();
+handle.unmount();
+// or unmountAgent("cust_123");
+```
+
+v1 defaults to a right-side edge tab + collapsible rail (Agent Studio tokens).
+
+## Customer IIFE bundle (`agent.js`)
+
+Build a copy-paste script bundle with manifest baked in:
+
+```bash
+cd packages/agent
+npm run build:bundle -- \
+  --manifest examples/agent.manifest.json \
+  --customer-id demo_customer \
+  --out-dir dist/bundles
+```
+
+Output: `dist/bundles/agent.js` exposing `window.WeblessAgent`:
+
+```html
+<script src="https://agents.webless.ai/demo_customer/agent.js" async></script>
+<script>
+  window.WeblessAgent?.open();
+</script>
+```
+
+## Runtime endpoints
+
+| Operation | Request |
+|-----------|---------|
+| Health | `GET /eve/v1/health` |
+| Start session | `POST /eve/v1/session?indexId=<index-id>` |
+| Continue session | `POST /eve/v1/session/:sessionId?indexId=<index-id>` |
+| Resume stream | `GET /eve/v1/session/:sessionId/stream?indexId=<index-id>` |
+
+## Local browser demo
+
+```bash
+cd webless-sdk
+cp apps/agent-demo/.env.example apps/agent-demo/.env.local
+npm install
+npm run dev:agent
+```
+
+Open **http://127.0.0.1:5178** for the headless Eve streaming demo.
+
+## Exports
+
+| Subpath | Purpose |
+|---------|---------|
+| `@webless/agent` | Headless Eve client |
+| `@webless/agent/react` | AgentRail, AssistEdgeTab, `useAgentChat` |
+| `@webless/agent/embed` | `mountAgent`, manifest normalization |