product.md

Product scope

octoscode-web is the browser sibling of the Octoscode TUI. It is a focused Web workspace for work an agent does in a server folder: coding, and office deliverables such as reports, cleaned-up tables, and slide outlines. A request goes in, the agent works in that folder, and the result comes back as files the user can check. It preserves Octoscode's command and state semantics; Octos Core remains the runtime and source of durable truth.

Office work widens who the product is for, not what the browser owns. The browser still runs no agent, tool, or document pipeline; it presents what the server does in the chosen folder.

Product principles

1. Same action, same meaning. Launch, commands, prompt queueing, interruption, approvals, questions, and session transitions follow Octoscode rather than inventing a second browser dialect.
2. The server owns work. Sessions, permissions, diffs, plans, tasks, artifacts, cost, and replay are projections of octos serve state.
3. Capabilities are runtime truth. Optional controls appear only when the connected server advertises them. Safety-bearing ambiguity fails closed.
4. Recovery is a product invariant. Reconnect includes hydrate, cursor replay, deduplication, session scoping, and gap handling.
5. A focused surface wins. The app does not inherit the voice, home, learning, Studio, slides, sites, admin, or cloud shell from octos-web.
6. Behavior from Octoscode, product language from DSH. DeepSeek Harness is the audited visual and browser-product reference, not the runtime base.
7. Authentication is not work selection. Connecting identifies an Octos server; Workspace and Session choices happen inside the product shell.

Supported surface

Area	Current behavior
Connection	Origin/token authentication gate, durable origin only, same-tab selected-Session restore, and Settings disconnect/forget.
Start	Empty Session home: code/general templates fill the composer (never sent, never raise permission); last-Session link.
Navigation	Workspace/Session sidebar with search, tab-confirmed Session refs, grouped or flat views, create, switch, and Settings.
Onboarding	Two-step provider setup with domestic recommendations, advanced identity, custom endpoints, test-before-save, and TUI fallback.
Conversation	Durable Chat with readable tool steps, per-turn file/token summaries, prominent failures, safe GFM, and streaming Markdown.
Trajectory	Session-local plan, runtime policy, task lifecycle, bounded output, cancellation, and paged artifact/file previews.
Decisions	Approvals with action/impact/risk, explicit deny/session/once choices, questions, and one-click write on a read-only denial.
Coding safety	Server-confirmed permission/network choices beside the composer, dangerous-access acknowledgement, and diff review.
Session panel	Beside the chat (a drawer on phones): live plan, folders plus files this Session changed, non-modal diffs, and outputs.
Models	Effective Session runtime status in the composer; capability-gated provider configuration and Profile defaults in Settings.
Skills	Capability-gated installed-skill list, typed action invocation, and background job progress/results in Settings.
Memory	Capability-gated overview, entity/search detail, and ingest in Settings; optional request/promote only when advertised.
Connectors	Read-only MCP server status; no add/remove/edit or OAuth controls.
Scheduled	Sidebar page: preset schedules, task templates, Cron under advanced; next run, last real result, jump to it.
Workspace	Folder-first picker with manual path fallback, server-confirmed paths, same-cwd Sessions, and per-Session drafts.
Usage	Context-window, token, and cost projections from typed server state.
Recovery	Hydrate, cursor resume, dedupe, replay-loss detection, gap repair, reconnect, and explicit uncertain or interrupted state.

Remote one-click skill installation is not part of the Settings Skills section: its supply-chain review is still open. Existing skills are read from the active server Profile; the browser does not install executable tools or dependencies.

Memory edit and delete controls are not offered because the current protocol has no corresponding operations. Remember-this uses the explicit ingest RPC; accepted request/promote responses are described as accepted or staged, never as completed writes.

Delivered files, supervised-task artifacts, and files explicitly written by write_file/edit_file share an inline preview component. Tool arguments must carry the path; result prose is never scraped to invent an artifact. PDF and CSV parsers load only on demand; PDF pages, CSV rows, and long text are bounded rather than dumped into one DOM. HTML and SVG previews use opaque-origin frames with scripts, forms, external requests, and credential access disabled. DOCX, XLSX, PPTX, and other unsupported or oversized files fail honestly to Download. File bytes come from the authenticated Session blob API, and copy-path/download controls never put the server token in a URL.

The connector surface is intentionally incomplete by protocol: there is no connector configuration/OAuth flow. The UI does not describe it as full management.

A scheduled task's last_status only says its Session accepted the run, so the list reads the outcome from the turn that run started. Turns do not record which job started them; the list pairs them by time, so a person's turn started in the same moment could be read as the run. A task that only delivers text (notify) shows nothing in a web Session, so the page does not offer it.

The expanded candidate also exposes capability-gated native peers and gather, agents/goals/loops/monitors, context/cache/compaction, snapshot undo, rewind/fork, native review, tool/MCP inventory, skills, and research lanes. /thinking captures per-Session reasoning effort in new queued turns; files dropped, pasted or picked (also /attach) upload straight away and wait in the composer: up to ten per message, four of them images (20 MiB each), the rest PDF, CSV, Markdown or plain text (50 MiB each). Office files are refused with an explanation. These controls do not imply full TUI parity or a passed live soak; acceptance is tracked in Feature parity.

Transcript rows are a bounded browser rendering projection, not the durable history store. When older rows fall outside that window the first visible row states how many were omitted and points back to server hydrate. Model-authored remote images render as alt text rather than making an automatic cross-origin request; explicit links remain user-initiated.

The connection gate asks only which Octos server to authenticate to. Inside the product, the user-facing hierarchy is Workspace → Session. Workspace is the coding object: it groups durable Sessions by a path on the Octos server. There is no separate generic “Object” type or browser-owned session database. The selected Session owns its Chat and Trajectory views and its permission control. The composer also reports the model served by that Session's runtime; it does not present a Session-only model override.

Current Core builds do not expose a complete server-wide Workspace/Session catalog. The browser remembers a bounded list of recent server paths and the minimal (workspace_root, active_profile_id, session_id) references that this tab has successfully opened. A local last-opened timestamp orders those rows. It does not cache Session titles, prompts, transcripts, model output, or other durable projections. Multiple confirmed Sessions may share one Workspace path without replacing each other.

Those rows remain incomplete navigation memory. Core rc.9 can silently ignore the requested cwd and loses the target Profile for some unscoped/admin session/list({cwd}) calls; its response does not echo either effective scope. The Web therefore does not project that list as a catalog. A new tab can reopen an exact saved conversation link after authenticating, but cannot browse a complete server Session directory until the scoped catalog tracked in octos#2146 lands.

Session navigation and running turns

Each confirmed Session retains one controller, FIFO, interaction ledger, cursor, and bounded transcript projection in the current tab. Several Sessions may run simultaneously, and switching or creating a Session is independent of another Session's queued prompts or pending start acknowledgement. The source queue drains on its own terminal events, not on selection. Returning selects that retained projection; reconnect still requires authoritative hydrate/replay. An unresolved turn-recovery state still blocks navigation until the user checks its status, so ambiguous dispatch evidence is not abandoned.

Approvals and questions remain attached to their exact Session and generation. A background waiting badge does not resolve them in the selected Session. Running/waiting states take precedence over retained terminal evidence; an empty or metadata-only Session has no completed-work badge. Candidate open failure leaves the source view intact. Stop and other mutations still require their own current authority and readiness checks. A fresh unambiguous activate decision opens automatically; cross_profile and no_profile remain explicit choices.

All retained Sessions share one physical authenticated WebSocket. The old eight-owner-connection cap and ACK navigation guard no longer govern this candidate. Native peers use server-staged identities and the same record engine; hosting a background master's peer does not change focus. Refresh blackboard reads Profile-wide peer results. /gather [all|slug…] additionally composes a bounded synthesis prompt in the originating master's FIFO, not an invented browser agent fleet.

Core rc11 still interrupts connection-owned work on transport loss. Refresh, tab close, network/proxy loss, and manual Disconnect are not detached continuation. Ordinary reconnect preserves in-memory queues but suspends dispatch until each record is rehydrated and reconciled; a failed/interrupted turn is not blindly resubmitted. Reload loses queued prompts and image drafts. Disconnect retires records but keeps confirmed navigation refs. Forget server or changing endpoint/token identity clears those refs, recent Workspace paths, and tab-scoped drafts. The downloadable runtime baseline is defined by core-runtime.json; feature acceptance requires its own evidence.

Unsent composer drafts survive refresh and tab close. After authenticating again, opening the same Session restores its text for the server-confirmed user. Drafts are browser editing state, not server transcript history, and are never automatically submitted on restore. Forget clears that user's saved drafts; changing credentials clears the current editing view without deleting another user's saved text. Pending queued messages are still tab-runtime state and are not restored after a full reload. Storage failures preserve in-memory editing and show a warning; an older persisted draft can remain when the browser refuses an update or deletion. Forgetting reports failure if the browser refuses to clear saved data. When inserting a new nonempty draft at the cache's 50-entry threshold, the cache evicts its oldest insertion and attempts to remove the saved copy. Updating an existing entry does not reorder it. Restore suppresses durable deletion while rebuilding the cache. See ADR 0021 for storage scope, restoration, and cleanup.

The tab title counts unseen background responses that complete or need input. General Settings offers an explicit desktop-notification opt-in. Notifications contain generic status text, not prompts, file paths or output; replaying history does not notify again. A hidden current Session uses explicit turn terminal events, never the disappearance of a local queue, to detect completion.

Settings opens from the bottom of the sidebar. General shows the active server and Workspace and provides Disconnect and Forget server. When the server advertises server/shutdown (a local octos serve --solo), General also offers a confirmation-guarded Stop server that disconnects the tab on success. Models distinguishes the Session runtime model from the active Profile default. It reads Core's configured primary and fallback models and, when the corresponding methods are advertised, can add, edit, test, discover, save, select, or delete a provider/model/route entry. The editable route fields are label, base URL, credential environment name, and protocol. Provider discovery supplies model id suggestions; it does not remove the manual model-id path.

The provider API-key field is write-only. Its value exists only in the current open editor and request, and is sent to Core for Test, Fetch models, or Save. Core owns the saved credential and returns only has_api_key; the Web does not retrieve it or claim anything about Core's storage encryption. Leaving the field blank for a configured route preserves and reuses the Core-owned key. Save tests the exact draft before mutating the Profile, and Delete requires confirmation.

Changing the Profile default affects every Session using that Profile and can require an Octos restart; it is not a Session-scoped choice. The inspected rc11 AppUI contract supports typed per-model temperature, top_p, context_window, reasoning defaults, and compatibility hints. Neither the pinned TUI nor Web offers an editor for those overrides. Web preserves known configured values when editing a provider and blocks edits it cannot preserve safely. The separate /thinking control captures per-turn reasoning. /activity searches confirmed Sessions and reads their task snapshots in batches of four while its dialog is open. It refreshes ten seconds after each scan completes and stops polling when closed; it never opens Sessions to discover work. See ADR 0022. Tool/MCP, skills/research, context, history, and peer controls open scoped product panels rather than a raw RPC console.

Deliberate non-goals

• Running an agent, model, tool, sandbox, plugin, or durable store in the browser.
• Importing the DSH/Cordis host runtime or the old octos-web application.
• Voice, camera, smart home, Learn, Studio, slides, sites, or administration.
• PTY terminal emulation, a full code editor, or a general repository filesystem API.
• Loading arbitrary third-party JavaScript into the client.
• Guessing unsupported capabilities or reconstructing server truth from prose.

Forward work

The current self-hosted slice has bounded recovery and execution guarantees. The expanded product is an acceptance candidate, not a blanket parity pass. Fixture results and limited real-Core checks must remain distinct from the multi-Session/native-peer live soak. Broader parity also depends on explicit Core contracts rather than more client-side inference:

• Generate request, result, and event payload types from a machine-readable Core schema (tracking issue #1).
• Add a persistent Core Workspace/Session object model with globally addressable descriptors (octos#2146).
• Make durable Session policy/full-access administration and Session-scoped model choice explicit Core contracts (octos#2147, octos#2148).

These are upstream contract boundaries, not invitations to add a transcript store or a second event dialect. The current decisions are retained Sessions, durable drafts, and on-demand Activity. The ADR index links their historical predecessors.