@lazyingart/agent-web 0.1.40

package/LICENSE

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

@@ -0,0 +1,438 @@
+# LazyingAgentWeb
+
+`@lazyingart/agent-web` is the standalone cloud PWA and HTTP/BFF for
+`llm.lazying.art`. It provides a usable browser chat surface while keeping
+AgInTi, LocalLLM, and LazyEdge independently replaceable.
+
+> **Deployment status (v0.1.29 candidate; v0.1.27 production):** production is promoted
+> independently from repository commits, with immutable acceptance receipts and
+> a verified rollback release. The current deployment enables AgInTi Agent only
+> through the accepted native AgInTi capability proof; if that proof is absent
+> or disabled, the BFF fails closed and Agent is unavailable. Direct Chat stays
+> separate and does not enable or authorize Agent. Current accepted Agent
+> requests can execute one exact fenced `python` block without model planning,
+> retain public failure reasons across reload, and follow exact idempotent Resume
+> successor runs with an optional corrected prompt. The accepted production release makes
+> completed Agent conversations truly multi-turn: later prompts resume the exact
+> terminal predecessor, retry an uncertain mutation once with the same idempotency
+> key, and keep any rejected prompt editable without an optimistic duplicate.
+> Direct Chat remembers the user's non-private workspace-mode preference across
+> a full reload, while
+> confirmed sign-out fences stale history reads. The accepted v0.1.23 release also
+> keeps failed-predecessor and corrected-success messages in chronological
+> order when their verified output and plot artifacts are restored after reload.
+> The baseline accepted artifacts remain declarative plot, table, and Markdown
+> schemas. Responsive plot artifacts in v0.1.25 use the available message width,
+> retain readable axes on DPR3 phones, wrap legends, and cannot be reflowed into
+> the sidebar column by privacy masking. The accepted v0.1.27 release also makes an
+> already-restored Agent-thread selection idempotent: clicking it cannot launch
+> a redundant ledger replay that detaches and rebuilds messages or figures, while
+> an invalid replay or unconfirmed mutation remains explicitly reopenable for
+> authoritative recovery. A brand-new conversation whose creation response is
+> lost retains its exact idempotency ticket for the next Send instead of
+> deadlocking or minting a duplicate. Numeric plot axes choose the shortest
+> distinguishing visible tick labels while retaining exact
+> values in accessible plot metadata. The v0.1.29 candidate also preserves an
+> unsent Agent follow-up across a release-fenced full reload: the encrypted
+> handoff retains its mode and owned thread, replays that thread after reload,
+> derives the authoritative terminal predecessor, and only then enables the
+> restored draft. The next Send therefore resumes the same Agent run instead of
+> silently changing to Direct Chat. v0.1.24 preserves the v0.1.23
+> backward-compatible, default-disabled grounded-search extension: only an exact
+> AgInTi capability may reveal the explicit Search
+> controls, bind `{mode: web|papers|both, limit: 1..20}` to one Agent input, and
+> admit bounded HTTPS-only `sources` artifacts. It also adds an exact-origin,
+> session-and-CSRF-bound fallback for iOS/PWA requests that omit all or part of
+> otherwise-valid Fetch Metadata,
+> retained mobile CSRF state, release-pinned requests with encrypted draft/image
+> refresh handoff, resume-time session validation, and secret-free rejection telemetry.
+> The browser has no direct LocalLLM search route.
+> Voice messages and general artifact uploads remain unavailable. The next
+> capability-gated artifact extension adds local-only PDF/TeX downloads: AgInTi
+> retains the bytes, while the cloud BFF only streams an authenticated bounded
+> response and never stores or caches it.
+
+The ownership model, Chat/Agent data planes, recovery semantics, artifact
+boundary, and replaceable-node contract are specified in
+[docs/architecture.md](docs/architecture.md).
+
+## Implemented surface
+
+- A bright-by-default installable PWA with persistent theme and workspace-mode preferences,
+  browser-password-manager integration, durable thread restoration, resumable
+  streaming, explicit cancellation, optional one-to-four-image Direct Chat input,
+  Markdown, KaTeX math, and safe declarative plot/table/Markdown rendering,
+  plus capability-gated text-only source cards that never fetch automatically
+  and safe Open/Download controls for AgInTi-owned PDF/TeX files.
+- A root-only Node HTTP/BFF with exact routes, host/origin/fetch-metadata/CSRF
+  enforcement, opaque remembered sessions, bounded request/stream/job
+  admission, owner-safe response projections, and graceful job draining.
+- `CloudIndexStore` for cloud accounts, digest-only browser sessions,
+  presentation-only AgInTi thread indexes, delivery cursors, and closed
+  idempotency receipts.
+- `DirectChatStore` for cloud-owned Direct Chat threads and hash-linked message
+  ledgers, atomic user-message/generation start, durable fenced dispatch leases,
+  exact-once assistant finalization, replayable deltas, cancellation, bounded
+  retention, compaction snapshots, private immutable vision attachments, and
+  receipt-authorized Direct Chat thread deletion.
+- `DirectChatContextCoordinator` for bounded LocalLLM context assembly and
+  provenance-bound chat compaction. The standalone service uses a deterministic
+  local summarizer that performs no model or network call, so compaction cannot
+  bypass the single-inference admission fence. Summaries are explicitly
+  labeled untrusted conversation data and never gain system, developer,
+  policy, tool, or Agent authority.
+- `createLocalLlmConnector()` for a fixed set of LocalLLM model aliases over an
+  exact authenticated `127.0.0.1` OpenAI-compatible `/v1` endpoint. It validates
+  models and SSE frames, bounds input/output, rejects redirects and partial
+  redispatch, sends canonical images only through the fixed `localllm-vision`
+  alias, and has no hosted-provider fallback.
+- A fail-closed AgInTi BFF transport and cloud-owned stateless adapter. The
+  browser can call only the frozen public protocol; the server derives
+  identity/session context, validates exact requests and responses, and sends
+  only `x-aginti-principal-id`, `x-aginti-browser-session-id`, and standard
+  `Idempotency-Key` authority to AgInTi. LazyEdge remains an opaque transport;
+  Agent state and decisions never move into this package. Search-bearing run
+  inputs receive a fresh server-side capability preflight, so a disabled or
+  legacy AgInTi never receives the extension field. The exact `file` capability
+  negotiates creation only; a verified file event and receipt remain durable
+  read authority across a read-compatible rollback. File bytes use a separate
+  authenticated release-bound GET/HEAD BFF route that converts one validated
+  browser range into structured AgInTi input, streams with backpressure, and
+  never forwards browser credentials or headers to the local service.
+
+## Component boundaries
+
+| Component | Owns | Must not own |
+| --- | --- | --- |
+| LazyingAgentWeb | Cloud accounts and browser sessions; Direct Chat history, deltas, and chat-only context; AgInTi presentation pointers and delivery cursors; PWA and safe rendering | Agent plans, Agent messages/context/compaction, tools, execution, artifact authority, inference implementation, tunnels |
+| AgInTi | Authoritative Agent threads, runs, plans, context, compaction, tools, event ledger, cancellation, and artifacts | Cloud login/session policy, LocalLLM inference implementation, LazyEdge transport |
+| LocalLLM | Text, coding, embedding, and vision inference | Chat persistence, Agent orchestration, cloud accounts, edge transport |
+| LazyEdge | Authenticated, replaceable transport between the cloud BFF and exact enrolled local services | Chat or Agent semantics, model behavior, cloud presentation state |
+
+Direct Chat is deliberately cloud-owned because LocalLLM inference is
+stateless. Agent mode is only another frontend for AgInTi: the cloud database
+must not contain AgInTi messages, summaries, plans, tool calls/results,
+commands, workspace paths, runtime policy, artifact bodies, or sandbox state.
+Removing a cloud Agent index cannot delete its authoritative AgInTi thread.
+
+## PWA releases and latest-version reload
+
+`createStandaloneAssetMap()` builds and brands a complete release map. Its
+immutable release ID is derived from the full shell content and pinned build
+inputs, and every JavaScript module, CSS file, KaTeX module, and icon is placed
+under `/assets/r/<release>/`. The server accepts only that verified branded map;
+it cannot be paired with a caller-invented release ID.
+
+The update authority is the stable `/sw.js` route, served with `no-store`,
+`no-cache`, and `must-revalidate`. The browser registers it with
+`updateViaCache: "none"`. Controlled pages check at startup and on bounded
+foreground/online transitions, while a fresh uncontrolled install skips a
+redundant immediate update race. A complete successor shell is verified by
+exact URL, MIME type, security headers, byte length, and SHA-256 before it can
+wait for activation.
+The page proves a waiting worker's release over a one-shot message channel and
+suppresses the banner only when it exactly matches the loaded shell. The UI
+offers **Update** and **Later** for a verified successor, conservatively falling
+back to the same offer for an unresponsive legacy worker; Update reloads once
+only after the new worker controls the tab. Activation retains the current and
+immediately previous verified shell. An offline or failed update leaves the
+current app usable.
+
+If Update is confirmed while a definitively unsent Direct Chat composer is
+eligible, or while an exact Agent composer is idle or follows an authoritative
+terminal run, the page stores one bounded AES-GCM ciphertext in a dedicated
+IndexedDB store. The v0.1.29 inner payload schema v3 preserves the exact mode,
+owned Agent thread when present, explicit Search settings or No Search, draft,
+and bounded images. Its random key exists only in the replacement navigation
+fragment, which browsers never send in HTTP requests. The fragment deliberately
+remains while authenticated take and decryption are pending; only a bounded
+recovery retry or verified release hop reattaches it, and successful recovery
+then scrubs it. The exact account, scope, source/target releases, expiry, digest,
+and canonical image contract are revalidated; restoration never dispatches the
+draft. Expired, malformed, and excess orphan records are pruned. Passwords,
+active sends or generations, nonterminal Agent work, and ambiguous mutations
+remain reload blockers.
+
+If a release fence is discovered while same-account sign-in is only restoring
+an already server-owned Agent or Direct Chat conversation, v3 may carry an
+empty exact thread selection as read-recovery metadata. It never carries or
+replays a mutation ticket. A durable ciphertext can also cross a signed-out
+release fence through a key-authenticated opaque hop; account verification
+still happens only in the successor before any plaintext is shown.
+
+A v0.1.27 handoff has an inner schema-v2 payload that cannot prove its original
+conversation mode or Search choice. v0.1.29 therefore keeps that recovered
+composer read-only until the user explicitly chooses its destination and then
+confirms **Search** or **No Search**; it never guesses and never auto-sends.
+
+The handoff accepts at most four canonical images and 16 MiB in aggregate. Any
+larger, active, ambiguous, malformed, expired, or ownership-mismatched draft is
+ineligible; the current page stays open rather than discarding it.
+
+Only immutable public shell assets enter Cache Storage. Login/session, Direct
+Chat, Agent, SSE, artifact, and upload traffic always bypasses it. Production
+must stage the entire immutable namespace before atomically switching the root
+HTML and stable worker response.
+
+Authenticated history and original attachment bytes remain authoritative in
+the cloud SQLite stores. The PWA may keep only a disposable, bounded per-tab
+Blob LRU for viewport-near attachment previews; it is never written to browser
+storage and is purged across authentication, account, and release boundaries.
+Historical rendered previews have a separate four-image / 64 MiB estimated
+decoded-pixel limit. Eviction revokes the object URL and leaves a tap-to-reload
+placeholder, so scrolling through a long image thread cannot retain every
+decoded surface. Up to four staged or just-sent composer images are transient
+rather than part of this history cache and are revoked at their existing send, view, and
+authentication boundaries.
+The server similarly caches only successful integrity-audit state, bounded by
+thread and invalidated by every local write or SQLite `data_version` change.
+It does not duplicate or relax validation of private message data.
+
+## Public package entry point
+
+The package root exports the implemented server and storage primitives plus the
+browser/PWA protocol:
+
+```js
+import {
+  CloudIndexStore,
+  DirectChatContextCoordinator,
+  DirectChatStore,
+  createAgintiAgentAdapter,
+  createCloudServer,
+  createLocalLlmConnector,
+  createStandaloneAssetMap,
+  failClosedCapabilities
+} from '@lazyingart/agent-web';
+```
+
+The three runtime stores/coordinators are intentionally injected into
+`createCloudServer()` rather than hidden behind globals. The LocalLLM connector
+also receives its transport credential through a server-side provider; neither
+that credential nor an AgInTi/LazyEdge credential is sent to the browser or
+stored in this repository.
+
+## Standalone service configuration
+
+`lazying-agent-web serve` reads one owner-only JSON configuration and separate
+owner-only `LoadCredential` files. A secret-free shape is:
+
+```json
+{
+  "schema": "lazying-agent-service/v1",
+  "listen": { "host": "127.0.0.1", "port": 18543 },
+  "publicOrigin": "https://llm.lazying.art",
+  "account": {
+    "username": "lachlanchen",
+    "principalId": "principal_account_one",
+    "displayName": "Lachlan"
+  },
+  "state": {
+    "cloudIndexDatabase": "/var/lib/lazying-agent-web/cloud/index.sqlite",
+    "directChatDatabase": "/var/lib/lazying-agent-web/chat/chat.sqlite"
+  },
+  "pwa": {
+    "versionLabel": "release",
+    "title": "LazyingArt Agent",
+    "name": "LazyingArt Agent",
+    "shortName": "Lazying Agent"
+  },
+  "localLlm": {
+    "baseUrl": "http://127.0.0.1:18008/v1",
+    "allowedModelAliases": ["localllm-deep", "localllm-vision"],
+    "defaultModelAlias": "localllm-deep",
+    "vision": { "enabled": false }
+  },
+  "aginti": {
+    "enabled": true,
+    "baseUrl": "http://127.0.0.1:18009"
+  },
+  "credentials": {
+    "passwordHash": "login-password-hash",
+    "localLlmToken": "localllm-token",
+    "agintiToken": "aginti-token"
+  }
+}
+```
+
+The filenames identify distinct credential files; raw password verifiers and
+bearer values never appear in the JSON. Credential directories and files may
+be systemd `LoadCredential` material owned by root (including its read-only
+root-group delivery modes under `/run/credentials/<unit>/`) or owner-only
+files owned by the service account;
+symlinks, hard links, world access, and any non-owner write access remain
+rejected. The preferred fixed-parameter scrypt verifier uses a 64-byte
+derived key, while the canonical 32-byte verifier used by the current v0.2
+login is accepted for a password-preserving migration. Set `aginti` to
+`{ "enabled": false }`
+and omit `credentials.agintiToken` when the Agent transport is intentionally
+absent. Configuring the transport does not claim Agent readiness: capability
+discovery stays fail-closed until AgInTi itself proves its native API, policy,
+sandbox, and current resource admission.
+
+Before switching an edge proxy to a candidate build, derive its exact,
+secret-free static allowlist from that same installed package and config:
+
+```sh
+lazying-agent-web edge-routes --config /etc/lazying-agent-web/service.json
+```
+
+The JSON contract contains the candidate content-bound `releaseId`, the exact
+`GET`/`HEAD` paths, and the query-bearing request targets used by the service
+worker. Stage and validate the proxy from this output, switch the proxy and app
+as one release, then verify every request target before retiring the previous
+allowlist. Unknown or foreign release assets must continue to return 404.
+
+Operators can inspect the deployed release and its decoupled runtime state
+without adding a public HTTP endpoint:
+
+```sh
+lazying-agent-web health --config /etc/lazying-agent-web/service.json
+```
+
+The command opens `CloudIndexStore` and `DirectChatStore` state read-only and
+reports them independently. LocalLLM and configured AgInTi probes are bounded;
+their errors collapse to fixed reason codes. Paths, origins, account identity,
+credentials, and raw upstream responses are never emitted. LazyEdge is always
+reported as `not_probed` with `healthClaim: false`; use LazyEdge doctor for
+transport health. A degraded or unavailable report exits nonzero. This is an
+operator diagnostic, not a public liveness endpoint: `/health` and
+`/api/health` remain default-deny 404s, and dependency health does not gate the
+static shell.
+
+Direct Chat vision remains fail-closed when `localLlm.vision` is absent or
+disabled. Enabling it requires the fixed `localllm-vision` alias while keeping a
+different default text alias. The PWA accepts one to four JPEG, PNG, HEIC, or
+HEIF still images plus a non-empty prompt and accepts each source file up to
+24 MiB. HEIC/HEIF support uses only a feature-detected native browser decoder;
+AVIF, sequences, conflicting brands, and malformed ISO-BMFF framing fail closed.
+The browser redraws and downscales every accepted source sequentially through a
+canvas to remove source metadata, and only canonical JPEG/PNG bytes can cross
+the wire or enter storage. Slow native decoding exposes a visible and accessible
+`Preparing images…` state; timeout, cancellation, session changes, and PWA
+controller changes fence late decoder completions. It enforces 4 MiB per
+canonical image and 16 MiB per message. A separate preview is bounded to 512
+pixels and 512 KiB so a visible
+mobile gallery never retains the full upload surfaces.
+The server independently validates MIME, framing, dimensions, metadata absence,
+digest, ordering, unique attachment IDs, count, and aggregate bytes before
+committing the user message, every private image, and the generation atomically.
+
+A minimal in-process storage-only probe is:
+
+```js
+import { CloudIndexStore, createCapabilityContract } from '@lazyingart/agent-web';
+
+const store = new CloudIndexStore({
+  databasePath: '/srv/lazying-agent-web/private/index.sqlite'
+});
+
+console.log(createCapabilityContract());
+console.log(store.healthCheck()); // DirectChatStore exposes the same safe shape.
+store.close();
+```
+
+## Runtime
+
+- Node.js 22.21.0 or newer, with the built-in `node:sqlite` module.
+- Exact runtime dependencies `es-module-lexer@2.3.1` and `katex@0.16.47`.
+- A local filesystem with normal POSIX ownership and locking semantics for the
+  private SQLite directories.
+
+`node:sqlite` emits an experimental warning on the tested Node 22.21.0 runtime.
+No native SQLite addon or browser CDN is used. The pinned parser verifies the
+complete immutable module graph, and the pinned KaTeX module provides local
+math rendering under the release namespace.
+
+## Storage and HTTP safety
+
+Both SQLite stores require absolute on-disk paths. They create state directories
+with mode `0700` and databases with mode `0600`, and reject symlinks, foreign
+owners/application IDs, insecure permissions, hard-linked database files,
+future schemas, migration checksum drift, integrity failures, and foreign-key
+corruption. SQLite uses `DELETE` journaling, `FULL` synchronous writes, foreign
+keys, `trusted_schema=OFF`, disabled extension loading, a bounded busy timeout,
+and `BEGIN IMMEDIATE` mutations.
+
+Raw browser session and CSRF tokens are never stored; `CloudIndexStore` retains
+only SHA-256 digests. An HTTP adapter derives every `accountId` from the verified
+browser session. Browser payloads and public JSON/SSE projections never choose
+or expose that owner identifier.
+
+Browser-session admission first removes expired rows. At the per-account cap,
+a successful new login atomically rotates only that account's oldest-issued
+session, with a deterministic digest tie-break; token collisions fail before
+eviction. This keeps sign-in available without deleting another account's
+session or temporarily exceeding the cap.
+
+Idempotency rows are bounded closed receipts rather than arbitrary response
+caches. Direct Chat starts a user message and its pending generation in one
+transaction. A durable owner digest plus monotonic fence prevents two cloud
+workers from dispatching the same generation concurrently; a stale worker
+cannot append or finalize after losing its lease.
+
+Direct Chat deletion is a distinct exact mutation:
+`POST /api/chat/threads/delete` requires the authenticated browser session,
+CSRF proof, a caller-generated idempotency key, and the exact current
+revision/hash cursor. The store refuses an active generation, a stale cursor,
+or a trailing user message whose send acceptance is unresolved. On success it
+atomically writes a content-free schema-v5 deletion receipt containing only
+identity, cursor metadata, and digests before removing the thread and its
+private descendants. The receipt is immutable, supports an exact retry without
+retaining the raw key or deleted content, and permanently retires that
+account/thread identifier. This route deletes only cloud-owned
+Direct Chat state; deleting an Agent presentation index or an authoritative
+AgInTi thread remains a separate contract.
+
+Canonical attachment bytes are durable only in the owner-private Direct Chat
+database. The message ledger and browser API expose a size/dimension/MIME/SHA-256
+descriptor, never the bytes or base64. Authenticated previews are `no-store`
+responses, and image data never enters Cache Storage, localStorage, or
+sessionStorage. IndexedDB is used only for the encrypted, expiring, one-shot
+confirmed-update handoff described above; it is not chat history or a retry
+queue. Base64 exists only transiently in the browser's exact in-memory retry
+ticket and the bounded browser-to-BFF and BFF-to-LocalLLM request bodies. The
+browser serializes a prepared image request once before entering the network
+ambiguity boundary, reuses those exact bytes only when a status probe proves
+the generation absent, and releases the raw images and serialized ticket as
+soon as the server accepts the durable turn.
+
+Ordered attachment responses use an explicit message-list schema request. A
+previous PWA that omits it receives the first descriptor in the legacy singular
+shape, so a stale open tab keeps its text/history protocol valid until the
+content-versioned PWA refresh takes control.
+
+Schema v5 adds the durable authority receipts required for safe Direct Chat
+thread deletion. It is now the common Direct Chat schema whether vision is
+enabled or disabled, so the ordered v4 attachment tables are materialized on
+upgrade while image use remains fail-closed at the application boundary.
+Existing v3 single-image rows still migrate to ordered position zero. A v5-aware
+build running with vision disabled can serve authenticated previews and exact
+retries of previously committed image turns, but refuses new image turns and
+follow-ups that would reuse stored images.
+
+A pre-v5 binary cannot reopen the migrated database. Before activation, block
+every dynamic API, stop the service, verify sidecar-free SQLite `DELETE`
+journal state, take an offline private database backup, and preflight a copy of
+that backup with the candidate release. The snapshot may be restored only
+while all dynamic APIs remain blocked and before any v5 write authority or the
+v5 deletion API is activated. After that boundary, preserve the live v5
+database and use only a v5-aware rollback release; restoring the older snapshot
+could discard accepted messages or deletion authority.
+
+The production server is designed to bind on loopback behind Caddy. It trusts
+the configured public authority/client-address headers only from that local
+proxy boundary. It does not terminate public TLS, manage a LazyEdge tunnel, or
+launch LocalLLM/AgInTi/sandboxes itself.
+
+## Checks
+
+Run the offline checks with:
+
+```sh
+npm run check
+npm test
+```
+
+These checks do not deploy the package or exercise the blocked live
+Docker/model acceptance gate.