diff --git a/CHANGELOG.md b/CHANGELOG.md index ac62386..7baab69 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,7 +4,15 @@ Delivered changes are recorded here. Version tags use `v` followed by a semantic ## [Unreleased] -No unreleased changes. +### Added + +- Research workspace specification covering conversation, execution state, live artifact revisions, evidence navigation, responsive layouts and application acceptance scenarios. +- Minimal OpenLab Harness specification and ADR 0002 selecting a self-developed first runtime, AG-UI at the Platform gateway and assistant-ui for conversation. + +### Changed + +- Product, architecture, logging, architecture diagram and bilingual README now describe Platform-owned conversations, steps, human interactions and artifacts independently of runtime, model, tools and UI. +- OpenCode becomes an optional future adapter; ADR 0001 preserves the historical selection with a supersession notice. This revision delivers documentation only, with no application code or new runtime dependency. ## [0.0.1] - 2026-10-24 diff --git a/README.md b/README.md index 239d015..e01ee73 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,9 @@ OpenLab is a local-first research workspace being designed to connect open resea | Automated documentation, workflow, and secret checks | Available in GitHub Actions and local tooling | | Local service with browser UI, Windows first | Planned | | Projects, skill installation, model configuration, and literature research | Planned | -| Supervisor-Skills execution through OpenCode | Planned; not an endorsed or verified integration yet | +| OpenLab Harness: default single-agent literature runtime | Specified; implementation and native Windows validation planned | +| Supervisor-Skills execution through the platform runtime adapter | Planned; not an endorsed or verified integration yet | +| Conversation, execution state, and live artifacts workspace | Specified with assistant-ui and AG-UI; no runnable UI yet | | Source tracking, execution history, and artifact export | Specified; implementation planned | ## First research release @@ -44,7 +46,9 @@ The initial application is intended to start locally and open in a browser. User ![Planned OpenLab architecture](assets/docs/architecture.svg) -OpenLab will own projects, run records, artifacts, and provenance. A replaceable adapter will connect an existing agent runtime. The [architecture](docs/architecture.md) separates this design from functionality already implemented. +OpenLab is an open research platform, not a wrapper around a single agent framework. It will own projects, conversations, execution records, sources, artifacts and provenance. Agent runtimes, models, scientific tools and user interfaces must be independently replaceable; research records remain owned by OpenLab and its users. + +The planned workspace combines project navigation, conversation with execution state, and live artifacts. assistant-ui provides the conversation foundation; the Platform gateway uses AG-UI. shadcn/ui and AI Elements supply supporting views, while CopilotKit is an interaction reference without an SDK dependency. The first runtime is the minimal self-developed OpenLab Harness behind RuntimeAdapter; OpenCode is a later optional adapter. See [architecture](docs/architecture.md) and [ADR 0002](docs/decisions/0002-workspace-and-harness.md) for the current design and its implementation gates. ## Documentation @@ -53,7 +57,10 @@ OpenLab will own projects, run records, artifacts, and provenance. A replaceable | [Original vision, Chinese](docs/vision.zh-CN.md) | Founding product vision, preserved as supplied | | [Product specification](docs/product.md) | Users, first milestone, behavior, and acceptance criteria | | [Architecture and contracts](docs/architecture.md) | Components, research objects, and runtime interface | +| [Research workspace](docs/workspace.md) | Three-region layout, interaction states, live artifacts and UI acceptance | +| [OpenLab Harness](docs/harness.md) | Minimal first runtime, replaceable capabilities and execution gates | | [Technical decisions](docs/decisions/0001-foundation.md) | Accepted baseline and implementation gates | +| [Workspace and Harness decision](docs/decisions/0002-workspace-and-harness.md) | Current UI/protocol and default-runtime selection; supersedes OpenCode first | | [Logging and provenance](docs/logging.md) | Diagnostics, research records, retention, and export | | [Product mark](docs/brand.md) | Vector assets, exact symmetry, and reproduction | | [Repository operations](docs/maintaining.md) | GitHub settings, labels, checks, and release procedure | diff --git a/README.zh-CN.md b/README.zh-CN.md index c658212..3d24ded 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -25,7 +25,9 @@ OpenLab 致力于建立本地优先的科研工作空间，将已有的开源科 | 文档、工作流与密钥扫描 | GitHub Actions 与本地工具提供 | | Windows 优先、本地启动、浏览器交互 | 计划实现 | | 项目管理、技能安装、模型配置与文献研究 | 计划实现 | -| 通过 OpenCode 执行 Supervisor-Skills | 计划集成，尚未通过执行验证 | +| OpenLab Harness：默认单 Agent 文献研究运行时 | 已定义规格，待实现及原生 Windows 验证 | +| 通过平台运行时适配器执行 Supervisor-Skills | 计划集成，尚未通过执行验证 | +| 对话、执行状态与实时研究产物工作台 | 已确定 assistant-ui 与 AG-UI 方向，目前没有可运行界面 | | 来源追踪、运行历史与成果导出 | 已定义规格，待实现 | ## 首个科研版本 @@ -40,15 +42,20 @@ OpenLab 致力于建立本地优先的科研工作空间，将已有的开源科 ## 架构方向 -![OpenLab 规划架构：浏览器、本地控制层、项目文件、技能目录与运行时适配器](assets/docs/architecture.svg) +![OpenLab 规划架构：科研工作台、平台 API 与 AG-UI 网关、平台研究记录、运行时适配器及 OpenLab Harness](assets/docs/architecture.svg) -平台持有项目、运行记录、成果和来源信息，通过可替换的适配器连接 Agent 运行时。实现边界见[架构文档](docs/architecture.md)。 +OpenLab 是开放科研平台，不是某个 Agent 框架的封装。平台持有项目、对话、执行记录、成果和来源信息；运行时、模型、科研工具和界面必须能够独立替换，研究记录与成果由 OpenLab 及用户掌握。 + +科研工作台采用“项目导航 + 对话与执行状态 + 实时研究产物”布局。assistant-ui 提供对话基础，平台网关采用 AG-UI，shadcn/ui 与 AI Elements 补充计划、审批和引用等视图；CopilotKit 作为交互模式参考，首版不引入其 SDK。首个运行时改为通过 RuntimeAdapter 接入的最小自研 OpenLab Harness；OpenCode 保留为后续可选适配器。实现边界见[架构文档](docs/architecture.md)与[新技术决策](docs/decisions/0002-workspace-and-harness.md)。 ## 文档导航 - [原始产品愿景](docs/vision.zh-CN.md)：保留用户提供的完整规划。 - [产品规格](docs/product.md)：用户、首版流程和验收条件。 - [架构与接口](docs/architecture.md)、[技术决策](docs/decisions/0001-foundation.md)。 +- [科研工作台规格](docs/workspace.md)：布局、交互状态、实时成果与界面验收。 +- [OpenLab Harness 规格](docs/harness.md)：最小运行时、可替换接口与验证条件。 +- [工作台与 Harness 决策](docs/decisions/0002-workspace-and-harness.md)：记录界面协议和默认运行时的路线变更。 - [日志与科研追溯规范](docs/logging.md)。 - [产品标识与矢量文件](docs/brand.md)：精确镜像轮廓、圆弧与中心对称波浪。 - [仓库维护与发布](docs/maintaining.md)、[验证记录](docs/verification.md)、[变更日志](CHANGELOG.md)。 diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md index 882a8b0..628a190 100644 --- a/THIRD_PARTY_NOTICES.md +++ b/THIRD_PARTY_NOTICES.md @@ -15,4 +15,15 @@ OpenLab's Apache-2.0 license applies to OpenLab-authored material. Referenced or The npm lockfile records exact development dependencies and integrity hashes. Their license metadata is available in the installed packages. CI downloads actionlint (MIT) and Gitleaks (MIT) from their official releases; pinned versions, archive URLs, and SHA-256 digests are recorded in [the tool manifest](scripts/tools.json). These executables are cached locally and are not included in the source release. -GitHub Actions used by the workflows retain their upstream licenses and are pinned to immutable commit SHAs. OpenCode is an architectural runtime selection, not a bundled dependency in v0.0.1. Any future application distribution must include an updated dependency and license inventory. +GitHub Actions used by the workflows retain their upstream licenses and are pinned to immutable commit SHAs. Any future application distribution must include an updated dependency and license inventory. + +## Planned application components and design references + +- [assistant-ui](https://github.com/assistant-ui/assistant-ui) is the planned conversation foundation, with its [official AG-UI adapter](https://www.assistant-ui.com/docs/runtimes/ag-ui/overview). +- [AG-UI](https://docs.ag-ui.com/introduction) is the selected frontend interaction protocol. OpenLab retains its own research archive and runtime contracts. +- [shadcn/ui AI Elements](https://ui.shadcn.com/docs/ai-elements) provides supporting UI composition patterns; copied component code must retain applicable source and license records. +- [CopilotKit](https://github.com/CopilotKit/CopilotKit) is an interaction-pattern reference; no SDK or hosted service is selected for the first release. +- OpenCode was the original first-runtime selection in ADR 0001. [ADR 0002](docs/decisions/0002-workspace-and-harness.md) selects self-developed OpenLab Harness and retains OpenCode as an optional future adapter. +- DeepSeek Harness is named in the supplied planning material as architectural inspiration. No upstream implementation or license has been independently established in this revision; no code is copied or bundled on that basis. + +These application components are not installed or bundled in v0.0.1. The referenced documentation was reviewed on 2026-10-24; exact dependency/component revisions, license terms and compatibility must be recorded before implementation distribution. A design reference does not imply upstream endorsement. diff --git a/assets/docs/architecture.svg b/assets/docs/architecture.svg index 59c0198..8387f77 100644 --- a/assets/docs/architecture.svg +++ b/assets/docs/architecture.svg @@ -1,13 +1,18 @@ - - OpenLab architecture direction - The browser connects to the local control plane, which owns project storage, the skill catalog and a replaceable runtime adapter. OpenCode connects controlled retrieval tools and user-selected model providers. This is a planned architecture. + + Planned OpenLab research platform architecture + A replaceable browser workspace combines project navigation, conversation with execution state, and live artifacts. OpenLab Platform owns the API, AG-UI gateway, conversations, execution records, sources, artifact revisions, credentials and skill configuration. RuntimeAdapter connects the default OpenLab Harness or future external runtimes to platform-managed tools and models. No application implementation is delivered by this diagram. diff --git a/docs/architecture.md b/docs/architecture.md index 4ab2325..d510e52 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,31 +1,81 @@ # Architecture and research contracts -Status: accepted design for implementation. No application service, database, runtime adapter, or sandbox ships in v0.0.1. See [product behavior](product.md) and the [decision record](decisions/0001-foundation.md). +Status: accepted design for implementation, updated 2026-10-24. No application service, database, runtime adapter, or sandbox ships in v0.0.1. See [product behavior](product.md), [workspace](workspace.md), [Harness](harness.md), and the current [decision record](decisions/0002-workspace-and-harness.md). ## Deployment and component boundaries Use a modular local service that serves the browser UI and platform API from one loopback origin. Keep persistence and execution behind the service. Start with one process for the control plane and a separately supervised agent runtime; do not introduce a distributed scheduler or message broker. -The intended implementation stack is TypeScript on Node.js 24 LTS, a React browser client, SQLite metadata, and ordinary project files. This is a design decision, not a list of installed product dependencies. A runtime adapter is the only module allowed to use OpenCode-specific contracts. Existing runtime licensing and redistribution requirements must be checked before packaging. +The intended implementation stack is TypeScript on Node.js 24 LTS, a React browser client, SQLite metadata, and ordinary project files. This is a design decision, not a list of installed product dependencies. OpenLab Harness is the first runtime; only its adapter may use Harness-specific contracts. Future external runtimes use the same boundary. Record exact dependency versions, licenses and compatibility before packaging. + +The execution path is browser workspace → OpenLab API and AG-UI gateway → RuntimeAdapter → OpenLab Harness. The Platform provides authorized model, tool and artifact access through host services. Neither the browser nor the generic Harness loop owns the research archive. The [architecture diagram](../assets/docs/architecture.svg) depicts this planned arrangement. | Component | Owns | | --- | --- | -| Browser workspace | Navigation, forms, artifact preview, task events, user decisions | -| Local control plane | Project and integration metadata, credentials references, task state, policy, API authentication, exports | +| Browser workspace | Project navigation, assistant-ui conversation, execution views, artifact/source previews, user decisions | +| Local control plane | Projects, conversations, canonical research records, credentials references, task state, policy, API authentication, exports | +| AG-UI gateway | Projection of persisted events into UI messages, tools, steps and shared state; read-only replay and subscription | | Integration catalog and installer | Sources, immutable revisions, manifests, compatibility and license declarations | -| Runtime adapter | Runtime process health, sessions, event translation, permissions, abort, result collection | +| Runtime adapter | Runtime process health, execution sessions, event translation, user answers, permissions, abort, result collection | +| OpenLab Harness | Single-agent loop, replaceable model/tool/context implementations, pinned skill loading, controlled dispatch and runtime events | | Retrieval tools | Provider queries, normalized source metadata, accessed content and verification evidence | | Project store | Files, artifacts, sources, immutable run snapshots, checksums, export manifests | -The browser does not call the runtime or model providers directly. The runtime's database and session history are useful execution aids, not the canonical research archive. +The browser accesses runtime actions, models, tools and artifacts through the Platform. Runtime history is an execution aid, not the canonical research archive. Model adapters, scientific tools and UI components can change without changing project or export schemas. Harness remains usable with standalone host implementations of its interfaces. ## Local API and state -The planned API prefix is `/api/v1`; it offers project CRUD/archive/export, integration inspection/install/remove, provider configuration/testing, run creation/confirmation/cancellation, permission responses, artifact access, and a run event stream. Publish an OpenAPI definition with the first implementation. Opaque IDs identify objects; clients do not provide arbitrary server filesystem paths. +The planned API prefix is `/api/v1`; it offers project CRUD/archive/export, conversation/message access, integration inspection/install/remove, provider configuration/testing, run creation/confirmation/cancellation, interaction responses, artifact revision access, source access and a run event stream. Publish an OpenAPI definition with the first implementation. Platform-generated opaque IDs identify objects; clients do not provide arbitrary server filesystem paths. + +State transitions are persisted before notifying the UI. Run states are `queued`, `awaiting_confirmation`, `running`, `awaiting_input`, `awaiting_permission`, `cancelling`, `succeeded`, `failed`, `cancelled`, and `interrupted`. A queued run enters `running` with a planning phase and no research tool access, then reaches `awaiting_confirmation`. Confirming the current plan returns to `running` with the approved tool scope; scoped permissions and structured answers resume the same run. First release permits one nonterminal run per conversation. Follow-ups after termination create a new run; retries also record `parentRunId`. + +An interaction response identifies the persisted interaction and its version. Accept a valid answer once; an identical repeat returns the recorded decision, while contradictory, stale or terminal-run responses fail without dispatch. Confirmation binds the reviewed plan version and policy. Changed scope requires a new confirmation. A permission denial never authorizes the requested action. A denied request returns to the loop for an authorized alternative or a recorded failure. + +Events have a platform-generated sequence per run, timestamp, kind and sanitized payload. Persist events and corresponding metadata transitions together before publishing them. Finalize artifact bytes and checksum before exposing a committed revision; storage failure stops new dispatch. Runtime sequence/session identifiers remain adapter metadata. The browser reconnects using a Platform cursor, and the service replays records without rerunning tools. + +A restart reconciles runtime health before classifying a lost nonterminal execution as `interrupted`. It never automatically replays a task. Cancellation first records `cancelling`, stops new dispatch and aborts execution. Only confirmed termination records `cancelled`; an already committed completion wins a cancellation race. Closing a subscription does not request cancellation. + +## AG-UI gateway contract + +Use [AG-UI](https://docs.ag-ui.com/introduction) for frontend interaction, with HTTP SSE as the initial transport. The [official event reference](https://docs.ag-ui.com/concepts/events) supplies lifecycle, message, tool, step, state and custom event shapes. The Platform archive remains a versioned domain format, and RuntimeAdapter does not import protocol or UI types. -State transitions are persisted before notifying the UI. Run states are `queued`, `awaiting_confirmation`, `running`, `awaiting_permission`, `cancelling`, `succeeded`, `failed`, `cancelled`, and `interrupted`. Permission decisions resume the same run; retries after a terminal state create a new run with a `parentRunId`. A restart reconciles runtime health before classifying any nonterminal run as interrupted. It never automatically replays a task. +The following endpoint shapes are planned public contracts, not implemented routes: -Events have a platform-generated sequence number per run, timestamp, kind, and sanitized payload. The browser reconnects using the last sequence; the service replays persisted events without rerunning tools. Store runtime sequence/session identifiers as adapter metadata, not public object IDs. +| Operation | Contract | +| --- | --- | +| `POST /api/v1/conversations/{conversationId}/runs` | Persist the submitted message, selected configuration and new run; a client request key makes retried creation return the same run rather than duplicate model work | +| `GET /api/v1/conversations/{conversationId}` | Return persisted messages and run references for history/offline viewing | +| `GET /api/v1/runs/{runId}` | Return current run state, plan version, interactions, steps and artifact/source references | +| `POST /api/v1/runs/{runId}/confirm` | Confirm the reviewed plan version and capability policy | +| `POST /api/v1/runs/{runId}/interactions/{interactionId}/response` | Validate and persist a question answer or scoped permission decision before delivering it | +| `POST /api/v1/runs/{runId}/cancel` | Request cancellation independently of any browser subscription | +| `POST /api/v1/runs/{runId}/ag-ui` | Accept AG-UI `RunAgentInput` and attach to the existing run; return replay/live AG-UI events, never create or restart execution | +| `GET /api/v1/artifacts/{artifactId}/draft` | Read latest saved draft content and metadata, explicitly labeled mutable/incomplete with its saved version | +| `GET /api/v1/artifacts/{artifactId}/revisions/{revisionId}` | Read exact immutable content, checksum and provenance for the selected revision | +| `GET /api/v1/sources/{sourceId}` | Return source metadata, permitted supporting locations and linked runs/steps | + +The frontend integration creates runs through the Platform command API, then connects the assistant-ui AG-UI adapter to the run endpoint. Set AG-UI `threadId` to the platform conversation ID and `runId` to the platform run ID; validate both against the route. Client messages, tool definitions, context and state in `RunAgentInput` cannot override the already persisted run, tool allowlist or policy. Repeated attach requests are read-only. Client answers travel through the interaction API, and tool execution stays server-side. + +| Persisted fact | AG-UI projection and Platform meaning | +| --- | --- | +| Execution begins | `RUN_STARTED`; the scientific task is not yet complete or confirmed | +| Message text | `TEXT_MESSAGE_START`, `TEXT_MESSAGE_CONTENT`, `TEXT_MESSAGE_END` with stable message IDs | +| Tool activity and results | `TOOL_CALL_*` with stable tool-call IDs; argument streaming ending does not establish tool completion | +| Execution stages | `STEP_STARTED` / `STEP_FINISHED`; stable step ID maps to `stepName`, with a separate display label | +| Run state and pending interactions | `STATE_SNAPSHOT` / `STATE_DELTA`; nonterminal states remain nonterminal in the UI | +| Saved draft, committed revision or source update | Versioned OpenLab `CUSTOM` event with references to Platform objects | +| `succeeded` after result collection and persistence | `RUN_FINISHED`; execution success alone does not verify research claims | +| `failed`, `cancelled`, `interrupted` | `RUN_ERROR` with distinct `OPENLAB_FAILED`, `OPENLAB_CANCELLED`, or `OPENLAB_INTERRUPTED` code; display the recorded state rather than a generic failure label | +| Waiting for plan confirmation, an answer or permission | State update, no terminal lifecycle event; response continues the same logical run | +| HTTP EOF or connection loss | Transport status only; query/reconnect to discover the recorded run state | + +This first gateway profile keeps a logical run open across human waits and uses Platform response commands. It does not require draft or extended AG-UI interrupt/resume lifecycle fields. Exactly one terminal lifecycle outcome follows persisted termination. Native gateway waiting and reconnect behavior must be verified against pinned client packages; a library's loading flag cannot replace the Platform state. + +Research extensions use AG-UI `CUSTOM` with names `openlab.artifact.draft.updated.v1`, `openlab.artifact.revision.committed.v1` and `openlab.source.updated.v1`. Values carry `schemaVersion: 1`, platform sequence, project/run IDs, entity ID and applicable step/revision IDs. Draft updates also identify the saved draft version. Include only authorized summary metadata and references; fetch complete files through the artifact API. Ignore unsupported optional extensions without failing the message stream, and show unsupported content through its metadata/download path. + +For reconnection, supply `forwardedProps.openlab.afterCursor` on the attach request; omission requests replay from the beginning. A cursor identifies the projection version, platform sequence and derived-event index, so one domain event may safely produce several protocol events. Assign SSE event IDs from that cursor. Persist the last applied cursor and discard duplicate projected events before applying text or artifact changes. This cursor is an OpenLab extension, not an AG-UI guarantee. + +A surviving client resumes into its retained parser state. A fresh client loads earlier conversation history, clears the selected run's derived view and replays that run from the beginning to reconstruct open message/tool/step state; it must not append replay to an already materialized copy. A cursor from another run, a sequence gap or an unsupported projection version triggers a clean read-only replay. Bind replay and live subscription at a durable high-water mark so no events are missed between them. Full snapshot-and-suffix hydration can be optimized later once equivalent reconstruction is tested. ## Platform-owned objects @@ -34,14 +84,21 @@ All exported records carry a `schemaVersion`. Timestamps are UTC ISO 8601 values | Object | Minimum persisted contract | | --- | --- | | Project | ID, title, question, discipline and method tags, timestamps, archive state, relative storage layout | -| Run | ID, project ID, parent run, confirmed brief, state, integration revision, adapter/runtime version, model/provider identifiers, parameters without secrets, input hashes, policy snapshot, events, errors, artifact/source references | -| Artifact | ID, project/run IDs, media type, relative path, SHA-256, creation time, description, source and producing-step references | +| Conversation | ID, project ID, title, timestamps and ordered message/run references; independent of UI-library threads | +| Message | ID, conversation ID, originating run when applicable, role, ordered typed content parts, timestamps, saved streaming/completion state, attachment/source/artifact references | +| Run | ID, project/conversation IDs, parent run, proposed/confirmed brief and plan version, state, integration revision, adapter/runtime version, model/provider identifiers, parameters without secrets, input hashes, policy snapshot, events, errors, artifact/source references | +| RunStep | Stable ID, run ID, display label, order, state, timestamps, tool-call and resulting source/artifact references | +| PendingInteraction | ID, run/step IDs, version, kind (plan confirmation, question or permission), prompt and allowed response schema/scope, state, recorded response and decision time | +| Artifact | ID, project ID, media type, description and draft/revision references; draft identifies producing run/step, saved version and incomplete status | +| ArtifactRevision | Immutable ID, artifact ID, project/run/step IDs, relative content path, SHA-256, creation time and source/claim associations | | Source | ID, canonical URL/DOI or provider ID, bibliographic metadata, retrieval query/time/provider, content availability/hash, verification level, verifier and supporting excerpt/location when permitted | | Integration | ID, category, upstream URL, author, revision, full source tree location, license declarations, dependencies, required capabilities, installation state, platform-specific maturity evidence | Verification levels are `unverified`, `metadata_verified`, and `content_verified`. Source existence does not verify a claim. Claim-to-source associations also record whether the relationship is model-proposed or checked, who checked it, and where the supporting content was found. Hypotheses, model inference, observations, and checked claims remain separate artifact annotations. -Store global catalog/configuration metadata under the user's application-data directory. Store projects in a user-selected data root with platform-managed subdirectories: `materials/`, `runs/`, `artifacts/`, and `sources/`. Keep SQLite metadata exportable into a versioned JSON manifest. Exports include selected source files, hashes and provenance, and exclude credentials, global configuration, caches and runtime internals. Import verifies hashes and confines all paths to the destination root. Schema migrations require a backup and round-trip compatibility test before a new application release. +An artifact can have revisions produced by different runs. Every committed revision links to its producing run and step; message citations and step/source links resolve by stable IDs, not UI text positions. Drafts remain explicitly mutable and their latest saved bytes remain available after failure or cancellation. Committing a revision freezes its bytes and provenance. Existing revision links never silently resolve to a newer version. + +Store global catalog/configuration metadata under the user's application-data directory. Store projects in a user-selected data root with platform-managed subdirectories: `materials/`, `runs/`, `artifacts/`, and `sources/`. Keep SQLite metadata exportable into a versioned JSON manifest. Exports include conversations, messages, steps, interaction decisions, selected sources, saved drafts, immutable revisions, hashes and provenance; exclude credentials, global configuration, caches and runtime internals. Imported decisions are historical and cannot authorize a new run. Import verifies hashes and confines paths to the destination root. Schema migrations require a backup and round-trip compatibility test before an application release. This specification changes no existing persisted data because no application schema has shipped. ## Replaceable runtime adapter @@ -52,17 +109,18 @@ interface RuntimeAdapter { capabilities(): Promise; start(request: RunRequest): Promise<{ executionId: string }>; events(executionId: string, cursor?: string): AsyncIterable; + replyInput(executionId: string, answer: InputAnswer): Promise; replyPermission(executionId: string, decision: PermissionDecision): Promise; cancel(executionId: string): Promise; collect(executionId: string): Promise; } ``` -`RunRequest` contains the platform run ID, resolved workspace, immutable skill reference, brief, selected model, approved tool set and policy. `RuntimeCapabilities` reports available tools, permissions, abort, event streaming, and checkpoint support rather than assuming them. `ExecutionResult` lists produced files, sources, usage when available, and terminal status. `RuntimeEvent` translates progress, tool activity, user questions, permission requests, usage and errors. Cancellation acknowledgement alone is not terminal completion. +`RunRequest` contains the platform run/conversation IDs, resolved workspace, immutable skill reference, task/brief, selected model, tool definitions and scoped host access. The initial policy permits planning without research tools. `InputAnswer` identifies a persisted interaction and version with a typed response; plan-confirmation input carries the approved plan/policy reference. `PermissionDecision` identifies the exact request and approved/denied scope. The Platform validates and persists both before delivery. -OpenCode is the default implementation, using its [headless HTTP server and event interfaces](https://opencode.ai/docs/server/) and [skill loading](https://opencode.ai/docs/skills/). Generate the concrete client against the pinned runtime's published API rather than copying unversioned endpoint assumptions into platform contracts. The adapter translates upstream events and uses its permission and session-abort interfaces. +`RuntimeCapabilities` reports available tools, structured input, permissions, abort, event streaming and checkpoint support rather than assuming them. First Harness declares cross-restart checkpoints unavailable. `ExecutionResult` lists submitted files, source references, usage when available and terminal status; Platform validation/persistence precedes publication. `RuntimeEvent` translates messages, steps, tool activity, user questions, permission requests, usage, partial products and errors. Cancellation acknowledgement alone is not terminal completion. -The official [Windows documentation](https://opencode.ai/docs/windows-wsl/) says native Windows is supported and recommends WSL for a better experience. Native Windows remains the initial validation target; WSL is an explicit optional compatibility mode, with separate path mapping and configuration. Do not silently install WSL or claim native compatibility without the feasibility tests in the product specification. +The default implementation wraps [OpenLab Harness](harness.md). OpenCode and other runtimes are future optional adapters, subject to version-specific feasibility and licensing checks. Neither a direct assistant-ui runtime integration nor an upstream session store may bypass the Platform boundary. Native Windows is the validation target; WSL is an explicit optional compatibility mode with separate path mapping and configuration. Do not silently install WSL or claim native compatibility without the product feasibility tests. ## Integration and retrieval @@ -74,11 +132,11 @@ Initial retrieval adapters target public scholarly metadata APIs (Crossref and O ## Trust and compatibility -- Bind the platform and runtime to loopback. Use a per-launch authentication handshake, same-origin requests, origin/host validation, and CSRF protection for state changes; do not expose the runtime credential to the browser. +- Bind the platform and any runtime HTTP listener to loopback. Use a per-launch authentication handshake, same-origin requests, origin/host validation, and CSRF protection for state changes; do not expose worker/provider credentials to the browser. - Store model credentials using Windows user-scoped credential protection. Pass only the selected provider credential to an isolated runtime configuration; redact runtime errors and keep raw secrets out of run manifests. - Prevent global user skills, hooks and configuration from leaking into a managed execution. Validate this behavior against the pinned runtime before declaring the integration executable. - Confine project file operations through platform tools; disable arbitrary shell access in the literature release. Inspect resolved paths and links before reading, writing, or exporting files. - Treat retrieved text as evidence, not authority to change policy. Tool permissions come from the platform/user, not a downloaded Skill or paper. -- Project files and research records remain usable if the runtime is removed. Export/import tests and a second adapter test double verify that guarantee. +- Project files and research records must remain usable if the runtime or UI library is removed. Export/import tests, a second runtime test double, a substitute model and an independent AG-UI consumer are required evidence for that guarantee; none has been implemented yet. Runtime log and research-record retention follow the separate [logging and provenance specification](logging.md). These application guarantees require implementation tests before being presented as shipped behavior. diff --git a/docs/decisions/0001-foundation.md b/docs/decisions/0001-foundation.md index a188022..56f968a 100644 --- a/docs/decisions/0001-foundation.md +++ b/docs/decisions/0001-foundation.md @@ -2,6 +2,8 @@ Date: 2026-10-24. Status: accepted design; repository governance implemented in v0.0.1, application decisions await implementation. +Historical decision record: [ADR 0002](0002-workspace-and-harness.md) supersedes decision 5's OpenCode-first selection, the OpenCode-specific feasibility gate, and the deferred-internal-runtime alternative below. OpenLab Harness is now the planned first runtime; other foundation decisions remain in force. The original decisions are retained here for traceability. + ## Context OpenLab begins with an empty public repository and a long-term cross-disciplinary research vision. The first user-facing value is a traceable literature task using existing research skills. The project needs reliable contribution and release practices before claiming runtime capabilities. diff --git a/docs/decisions/0002-workspace-and-harness.md b/docs/decisions/0002-workspace-and-harness.md new file mode 100644 index 0000000..e7c4018 --- /dev/null +++ b/docs/decisions/0002-workspace-and-harness.md @@ -0,0 +1,36 @@ +# ADR 0002: research workspace, AG-UI and OpenLab Harness + +Date: 2026-10-24. Status: accepted design, not implemented application functionality. Supersedes the OpenCode-first selection in decision 5, its runtime-specific feasibility gate, and the deferred-internal-runtime alternative in [ADR 0001](0001-foundation.md). Other foundation decisions remain in force. + +## Context + +Researchers need to see conversation, execution state and developing results together. Projects, conversations, evidence and artifacts must remain usable when any model, runtime, scientific tool or interface changes. The repository currently contains governance, tooling and design documents; selecting these components does not make an application available. + +The approved direction chooses a minimal self-developed OpenLab Harness for the first literature release and formally adopts AG-UI for frontend interaction. It changes the previous first-runtime choice while retaining a replaceable execution boundary. + +## Decisions + +1. Use a three-region research workspace: project/history/tools navigation, conversation with execution and human interaction, and live artifacts with evidence navigation. Provide collapsed panels and narrow-screen drawers. Specify behavior in [workspace](../workspace.md). +2. Use assistant-ui as the conversation foundation and prefer its official AG-UI adapter. Use shadcn/ui and AI Elements for supporting presentation. Refer to CopilotKit's shared-state and human-interaction patterns without adding its SDK or cloud service. +3. Adopt AG-UI at the Platform gateway. Keep canonical research objects, persisted events and RuntimeAdapter contracts owned by OpenLab. A stream disconnect or end is not sufficient evidence of scientific task success. +4. Build OpenLab Harness as the default first runtime behind RuntimeAdapter. Begin with one agent, replaceable model/tool/loop/context/storage interfaces and static registration. Research-specific retrieval and artifact behavior belongs to an extension. See [Harness](../harness.md). +5. Keep model credentials and tool policy under Platform control. Require confirmation before research tools run, persist human decisions and partial results, support confirmed cancellation and explicit retry after interruption, and preserve separate evidence verification levels. +6. Retain TypeScript/Node.js 24, React, SQLite, ordinary project files, a loopback control plane and a separately supervised runtime worker. Keep native Windows first; WSL is optional. Defer arbitrary code execution, multi-agent scheduling, remote compute and teams. +7. Keep OpenCode as an optional future adapter. Neither OpenCode nor Harness internals may become the canonical archive or leak into browser contracts. Prove the boundary with a second runtime test double, a substitute model and an independent UI consumer. + +## Consequences and gates + +Self-development adds ownership of the model/tool loop, cancellation, input validation and recovery behavior. Limit the first runtime to the literature workflow before expanding the plugin system. No dynamic plugin loader, general dependency resolver or distributed infrastructure is required at this milestone. + +Before implementation proceeds beyond feasibility, record exact runtime and client versions/licenses and validate the native Windows gates in the [Harness specification](../harness.md#implementation-gates). Verify assistant-ui/AG-UI history, human interaction and reconnect behavior against pinned packages. Current documentation supplies a preferred integration, not proof that a particular package combination passes those gates. + +First-release acceptance requires the [product scenarios](../product.md#acceptance-and-roadmap), including no tool execution before confirmation, permissions, cancellation, restart handling, source verification and archive portability. A model or runtime substitution must not change project or export schemas. No application packages, runtime code or migration are delivered by this documentation revision. + +## Alternatives considered + +- OpenCode first would reuse an existing execution loop; the approved direction instead prioritizes control of the minimal Harness while retaining OpenCode as a later option. +- A complete plugin kernel before a research task would broaden dependency and lifecycle work; start with explicit interfaces and static registration. +- A custom frontend protocol would duplicate existing event conventions; adopt AG-UI and document OpenLab's research extensions. +- Combining assistant-ui and CopilotKit as conversation owners would add overlapping state management; use one conversation layer and borrow interaction patterns. + +The supplied DeepSeek Harness reference is a source of architectural ideas, not verified evidence of upstream implementation behavior or permission to reuse code. diff --git a/docs/harness.md b/docs/harness.md new file mode 100644 index 0000000..3616b37 --- /dev/null +++ b/docs/harness.md @@ -0,0 +1,70 @@ +# OpenLab Harness: first runtime specification + +Status: accepted implementation design, updated 2026-10-24. The repository contains no implemented Harness, SDK or runtime security boundary. [ADR 0002](decisions/0002-workspace-and-harness.md) selects this first runtime and supersedes the earlier OpenCode-first decision. + +## Responsibility and first milestone + +OpenLab Harness is the default, independently reusable agent execution component. It receives a task, assembles context, calls a selected model, dispatches authorized tools and reports execution events. OpenLab Platform owns projects, conversations, research records, credentials policy, sources and artifacts. A standalone host supplies equivalent interfaces without importing the Platform database or browser UI. + +The first milestone is a single-agent literature task: question, proposed plan, confirmation, retrieval and reading, evidence organization, report generation, review and export. Research-specific tools and evidence policies live in a research extension. The generic execution loop does not contain scholarly-provider logic or a report schema. + +Keep the execution core small. Register compatible implementations explicitly at startup and resolve a run's configuration before execution. Model, tool, loop, context and event storage implementations have separate interfaces. The first version does not need a dynamic plugin loader, hot reload, dependency resolver, distributed scheduler or general plugin marketplace. + +## Modules and host interfaces + +The names below describe design contracts; they are not published SDK symbols. + +| Module | Contract and first implementation | +| --- | --- | +| Kernel and registry | Register implementations by category and version; validate required capabilities; coordinate lifecycle, cancellation and event delivery; reject missing or duplicate registrations before a run starts | +| Agent loop | Stream model output, validate proposed tool calls, await authorized results, update context and continue within limits; begin with one sequential agent and sequential tool dispatch | +| Model provider | Accept normalized messages, tool schemas, model settings and an abort signal; stream text, structured tool calls, usage when reported, and normalized errors; first live provider uses a configurable OpenAI-compatible endpoint with required streaming/tool-call capability checks | +| Tool executor | Discover approved named tools, validate input against their schemas, request policy decisions, invoke with scoped host capabilities and an abort signal, and emit results/errors; expose no arbitrary shell | +| Skill loader | Read a pinned skill tree and referenced resources from a host-provided installation; preserve upstream files and provenance; installation/loading does not execute scripts | +| Context strategy | Assemble task instructions, skill resources, material references and selected history within the model limit; record any trimming or summarization without modifying the archive | +| Event sink and state | Append ordered execution events and preserve pending interactions through host interfaces; Platform provides durable storage, while standalone/test hosts may supply a file-backed or in-memory implementation | +| Research extension | Provide retrieval/read tools, normalized sources, claim evidence associations, report draft publication and artifact submission through Platform services | + +A run configuration selects exact registered implementations and versions, model/provider identifiers, pinned skill, available tools, context strategy and limits. No model or tool may switch itself to another provider or broader policy. The provider interface is independent of the loop; a second provider test double must exercise it without changing the loop or platform schema. An OpenAI-compatible label alone does not establish tool or streaming compatibility. + +Limits include maximum model turns, per-call timeout and run duration, plus the user's available usage budget. Reaching a limit stops new dispatch and records why the run ended, preserving partial work. Unknown provider usage remains unknown. Do not promise a provider-independent hard billing cap. Bound retry counts, honor provider retry guidance and never automatically repeat a tool with uncertain side effects. + +## Platform adapter and execution flow + +Platform invokes the Harness through the same [RuntimeAdapter](architecture.md#replaceable-runtime-adapter) used for later external runtimes. This keeps Harness-specific objects out of projects, public APIs and exports. A separately supervised local worker hosts the first Harness; the control plane retains ownership of persistence and authorized service access. A worker process alone is not a sandbox. + +1. Platform creates a run and immutable configuration snapshot, validates skill/model/tool requirements, and supplies selected host capabilities. Harness emits planning messages without research tool access. +2. Harness proposes a brief and plan and waits. Platform persists `awaiting_confirmation`; only a confirmed brief and policy enable research tools. Changes to requested scope return to confirmation. +3. For each model-requested tool call, validate its name and input, check the approved scope, and persist intent before dispatch. Routine in-scope retrieval proceeds without another prompt. Additional sensitive access requires a scoped permission request. +4. Retrieval and reading tools report actual evidence and failures. The research extension saves source records and report drafts through Platform, linking them to the producing step. Model statements do not upgrade verification status. +5. A structured question or permission request stops new model/tool dispatch until answered. Platform records the interaction and decision before delivering it to Harness. The waiting process may continue the same run; this does not promise a checkpoint that survives a lost process. +6. On completion, Platform collects results, validates referenced files, commits final artifact revisions and records terminal state before reporting success. Export and research review remain Platform functions. + +Questions have a stable interaction ID, prompt, input kind (`text`, `single_choice`, or `multiple_choice`), permitted options when relevant, and any required constraint. Answers reference that ID. Permission requests additionally identify the tool/action and exact capability scope. Validate responses against the persisted request, accept each once, and reject stale or contradictory duplicates. A permission denial is delivered as a denial; the loop may use an authorized alternative or terminate with an explanation. + +Events identify the platform run and step, preserve tool-call/message/interaction IDs, and carry sanitized payloads. Runtime sequence identifiers are adapter metadata; Platform assigns the canonical sequence. AG-UI translation occurs in the Platform gateway. Harness does not import assistant-ui, CopilotKit or an AG-UI client. + +## Cancellation, recovery and trust + +Cancellation stops new dispatch, propagates abort to model/tool requests and asks the worker to terminate. Platform first records `cancelling`, then records `cancelled` only when termination is confirmed. A completion that won the race remains completed; a cancellation request alone is not proof that work stopped. If the worker cannot confirm termination, the supervisor reconciles or terminates it before allowing a retry that could overlap. Partial artifacts and source records remain available. + +If the control plane restarts, reconcile worker health and persisted state before classifying a nonterminal run. A lost execution becomes `interrupted`; a user retry creates a new run linked by `parentRunId`. Replaying events restores the interface only. It never invokes a model, replays an approval, republishes an artifact or reruns a tool. Cross-restart checkpoint recovery is deferred and must be advertised as unavailable by the first adapter. + +Platform manages model credentials and tool configuration. Supply only the selected provider credential through an ephemeral worker configuration and only the authorized project/tool capabilities. Redact secrets from events and errors, disable ambient global skills/hooks/provider settings, and confine file operations to platform-managed paths. Do not expose a general filesystem, shell or arbitrary HTTP tool in the literature release. Retrieved documents, skills and model text cannot alter policy or grant access. + +The first registry loads trusted application modules only. Untrusted executable plugins and arbitrary scientific computation need a separately verified isolation design. Tool approval prompts and a process boundary do not provide that isolation. + +## Evolution and reference material + +Later phases may add MCP adapters, additional model protocols, configurable loop strategies, checkpoint recovery, isolated scientific computation, multi-agent orchestration, remote environments and independently distributed plugins. Add them through measured requirements and capability declarations. OpenCode and other complete runtimes remain optional future RuntimeAdapter implementations; they need not adopt Harness internals. + +The supplied Harness planning document motivates replaceable capabilities, event-driven execution, append-only records and configuration composition. Its references to DeepSeek Harness are architectural inspiration supplied by the project owner. No DeepSeek implementation, upstream API or license has been independently established here, and no upstream code is copied or bundled. Direct reuse requires separately verified source and license records. + +## Implementation gates + +- Validate native Windows execution, including Unicode and space-containing paths, isolated configuration, pinned skill resources, event ordering, questions, permissions, cancellation and worker loss. WSL remains an explicit optional mode, not an automatic installation step. +- Run a real literature task with the pinned model client and controlled retrieval tools. Record exact dependency versions/licenses, model capability checks, available usage, failures and the test date before claiming compatibility. +- Exercise a second generic skill fixture and resolve Supervisor-Skills licensing before distributing its contents. Installation must preserve resources without upstream-name special cases. +- Test the loop with substitute model, tool, context and event-sink implementations. Test a second RuntimeAdapter and independent AG-UI consumer against the Platform archive. +- Verify denied tool access, invalid tool arguments, malformed model output, bounded retries/limits, no tools before plan confirmation, stale answers, cancel races, persistence failures and explicit restart retry. Storage failure must stop new work rather than silently lose the research record. +- Meet the economics, humanities, language, evidence, offline and export/import cases in the [product](product.md) and [workspace](workspace.md) specifications. These gates require application implementation; repository checks do not establish them. diff --git a/docs/logging.md b/docs/logging.md index 271e28a..8eeedec 100644 --- a/docs/logging.md +++ b/docs/logging.md @@ -7,7 +7,7 @@ Status: implementation specification. v0.0.1 supplies repository and CI logs; ap | Record | Purpose | Default contents | | --- | --- | --- | | Operational log | Diagnose platform health | Structured events, sanitized errors, timing and correlation IDs | -| Research execution record | Understand and review a research result | Confirmed brief, versions, tools, sources, artifacts, policy decisions and limitations | +| Research execution record | Understand and review a research result | Conversations, plan/confirmation, versions, steps/tools, human decisions, sources, artifact drafts/revisions and limitations | | CI and release log | Verify a repository change | Check results, workflow run and commit, release validation and publication outcome | Operational logs must not become a duplicate research archive. A failed or negative scientific result remains in the research record rather than disappearing with log rotation. @@ -36,7 +36,13 @@ Defaults: rotate at 10 MiB per file, retain the active file plus at most five ar ## Research provenance -For each run preserve the confirmed brief, integration revision and hash, runtime/adapter versions, model/provider identifiers, non-secret parameters, available usage, input hashes, tool calls with appropriate redaction, source evidence, artifacts and hashes, decisions, terminal state, errors and limitations. Mark unavailable values as unknown rather than reconstructing them from memory. +For each run preserve the proposed and confirmed brief/plan version, conversation and message IDs/content, integration revision and hash, runtime/adapter versions, model/provider identifiers, non-secret parameters, available usage, input hashes, ordered steps/tool calls with appropriate redaction, source evidence, saved artifact drafts, immutable revisions and hashes, decisions, terminal state, errors and limitations. Mark unavailable values as unknown rather than reconstructing them from memory. Research conversations are project content and must not be duplicated into operational logs. + +Preserve question/permission prompts, scoped requests, interaction versions, accepted responses, denial/cancellation decisions and their timestamps. A user-facing activity summary may be recorded; hidden model reasoning is not required research evidence. Imported or replayed decisions are historical and cannot grant new access. Runtime identity and session pointers are diagnostic metadata, not the identifiers of Platform research objects. + +The canonical event sequence is append-only per run. Persist state transitions and events before projecting them through AG-UI. Retain the projection version for cursor interpretation; replay reconstructs views without invoking tools or models. HTTP closure, a pending question and confirmed execution termination must remain distinguishable. A requested cancellation and its confirmed result are separate records. + +Every artifact revision preserves producing run/step IDs, source and claim associations, relative content path and SHA-256. Keep immutable revisions even when a later run produces a replacement. Save streaming content as an explicitly mutable draft with its saved version/sequence, and retain the latest saved partial draft after failure, cancellation or interruption. Artifact/source events refer to these objects rather than embedding whole files. Exports snapshot draft bytes with a checksum and incomplete label; this does not make the live draft a committed revision. Source records distinguish metadata existence from content verification. Claim associations identify a checked supporting location or explicitly remain unverified/model-proposed. Preserve conflicting evidence, failed retrieval, insignificant results and abandoned hypotheses. A model's self-attestation is recorded as such; it does not upgrade a source or claim to verified. @@ -50,4 +56,6 @@ Build the bundle from allowlisted fields, run a second secret-pattern check, and ## Implementation verification -Test log rotation and age cleanup, disabled/debug logging, malformed provider errors, nested token fields, URLs containing credentials, Unicode paths, disk-full behavior, and diagnostic exclusion of a synthetic credential and private document. Verify that cleanup leaves research records intact and that a failed run retains sources and partial artifacts. Match the [research contracts](architecture.md) in export/import tests. +Test log rotation and age cleanup, disabled/debug logging, malformed provider errors, nested token fields, URLs containing credentials, Unicode paths, disk-full behavior, and diagnostic exclusion of a synthetic credential and private document. Verify that cleanup leaves research records intact and that a failed run retains sources and partial artifacts. Match the [research contracts](architecture.md) in export/import tests, including messages, steps, decision history, draft labels and revision hashes. + +Test event ordering and deduplication on reconnect, a storage error before publication, question/permission response races, cancellation versus completion, and restart reconciliation. Confirm that replay/import does not execute calls or apply historical approvals, and that an independent reader can inspect the archive after removing the original runtime and UI library. These checks require future application code; the current repository checks validate documentation and tooling only. diff --git a/docs/product.md b/docs/product.md index 640f55f..e35a56e 100644 --- a/docs/product.md +++ b/docs/product.md @@ -6,7 +6,7 @@ Status: accepted design, not shipped application functionality. Updated 2026-10- Serve public users across disciplines, including researchers who do not administer agent frameworks. Start with literature investigation, research-idea evaluation, and organizing evidence. Prioritize Windows, a locally started service, and a browser UI. No platform account or OpenLab-hosted model service is required. -Success means a user can create a project, configure their model and retrieval access, install a versioned skill, execute a real literature task, inspect its sources and failures, and export the result with an understandable research record. A polished report alone does not establish research quality. +Success means a user can create a project, configure their model and retrieval access, install a versioned skill, execute a real literature task, inspect its sources and failures, and export the result with an understandable research record. Conversation, execution state and developing artifacts stay visible together. OpenLab owns the records independently of the selected runtime, model, tools and UI. A polished report alone does not establish research quality. ## User journey and screens @@ -16,26 +16,28 @@ Success means a user can create a project, configure their model and retrieval a | Projects | Create, rename, reopen, archive, and export projects; record questions, discipline, and method independently | | Skill catalog | Show source, author, license declarations, pinned revision, dependencies, platform compatibility, and verified maturity | | Model and retrieval settings | Add, test, select, and remove user-managed providers; credentials stay server-side | -| Project workspace | Attach local material by copying it into the project; choose a skill and model; inspect the proposed research brief and required capabilities | -| Run detail | Confirm the plan, see task progress and source/tool events, answer runtime questions, approve scoped requests, and cancel | -| Artifacts and sources | Preview Markdown and source metadata; identify claim verification level, failed retrieval, limitations, and originating run; export files and machine-readable records | +| Project workspace | Project/conversation/run and tool/skill navigation on the left; assistant-ui conversation with execution state in the center; live artifacts on the right; copy attached material into the project and choose a skill/model | +| Run detail | Confirm the plan, see measured progress and source/tool events, answer structured questions, approve or deny scoped requests, and cancel; distinguish connection state from execution state | +| Artifacts and sources | Preview saved Markdown drafts, immutable report revisions, source records and supported attachments; follow citations and producing-step links; export files and machine-readable records | -English and Chinese are the initial application languages. Research output follows the user's requested language; retain original publication titles and identifiers. Keyboard operation, accessible form labels, readable error messages, and visible progress are first-release requirements. UI visual design is a later implementation task, not an asset delivered by v0.0.1. +English and Chinese are the initial application languages. Research output follows the user's requested language; retain original publication titles and identifiers. Keyboard operation, accessible form labels, readable error messages, and visible progress are first-release requirements. Desktop supports collapsing navigation and resizing the artifact pane; narrow screens use project and artifact drawers. The [workspace specification](workspace.md) defines states, interactions, previews and navigation. No runnable UI or rendered application screenshot is delivered by this documentation revision. ## Research execution 1. The researcher defines a question, intended audience, discipline, and available material. 2. The platform checks the selected skill's actual requirements. A literature survey cannot start without retrieval. -3. The agent proposes a brief and plan. The user confirms it before research tool execution begins. +3. OpenLab Harness proposes a brief and plan using the selected model. Planning may use model tokens; the user confirms the current plan before research tool execution begins. 4. Execution runs within the approved project and capability policy. Additional access requests appear in the run detail. -5. The platform persists tool events, source metadata, verification status, artifacts, and failure information as execution proceeds. +5. The platform persists conversation messages, tool/step events, human decisions, source evidence, saved artifact drafts/revisions, and failures as execution proceeds. AG-UI projects these records into the workspace. 6. The user reviews and exports the result. Unverified statements remain distinguishable from retrieved and checked evidence. Ordinary in-scope retrieval does not request confirmation on every call. Scope changes, additional sensitive access, and a higher user-defined spending limit require an explicit decision. Show reported model usage when available, mark unknown usage as unknown, and stop new model calls at the configured budget; do not claim a provider-independent hard billing cap. ## Scope and integration maturity -The first application release includes projects, a small curated catalog, generic Skill repository installation, one OpenCode adapter, provider configuration, retrieval, execution records, and export. It supports selecting a tool directly and confirming an agent-proposed research plan. Visual workflow editing, scheduled discovery, arbitrary code execution, Python environment management, full research engines, remote compute, multi-user access, and institutional deployment follow later. +The first application release includes projects and conversations, a small curated catalog, generic Skill repository installation, the minimal self-developed OpenLab Harness behind RuntimeAdapter, provider configuration, retrieval, execution records and export. It supports selecting a tool directly and confirming an agent-proposed research plan. Harness starts with a single agent, replaceable model/tool/loop/context/storage interfaces, static registration, structured human input and cancellation. The first live model adapter targets a capability-checked OpenAI-compatible endpoint; other providers can implement the same interface. See [Harness](harness.md) and [ADR 0002](decisions/0002-workspace-and-harness.md). + +First-release artifacts are Markdown reports, structured source records and supported attachment previews/downloads. Scientific charts, experiment code execution, Notebook rendering, visual workflow editing, scheduled discovery, arbitrary code execution, Python environment management, full research engines, multi-agent scheduling, remote compute, multi-user access and institutional deployment follow later. OpenCode becomes an optional future adapter. Dynamic plugin loading, hot reload and general dependency resolution are also deferred. Use the five maturity levels from the vision: L0 discoverable, L1 installable, L2 executable, L3 composable, L4 reproducible. A successful test on one platform does not establish universal compatibility. Display the tested platform, runtime and integration versions, task, and date. Record repeatable inputs and execution conditions without promising deterministic model output. @@ -46,8 +48,11 @@ Supervisor-Skills is the initial reference case. Preserve its original directory - Missing credentials or tools: stop before research execution and provide setup instructions. - Retrieval unavailable or blocked: preserve partial work and failed requests; allow an explicitly labeled material-only task, but do not call it a verified literature survey. - Metadata found without full-text access: record metadata verification only. Do not infer that a paper supports a claim from its title or existence. -- Runtime crash or computer restart: keep completed artifacts, mark the run interrupted, and offer a new linked retry. Do not silently replay potentially billable or side-effectful calls. +- Runtime crash or computer restart: reconcile worker health, retain messages, sources, saved drafts and revisions, mark a lost run interrupted, and offer a new linked retry. Do not silently replay potentially billable or side-effectful calls. - Cancellation: stop dispatching new work, abort the runtime session, and distinguish a requested cancellation from confirmed termination. +- Waiting for input or permission: persist the request; apply a validated response once to the same run. Denial does not execute the requested action. Expired or terminal-run decisions cannot resume execution. +- Lost connection or closed page: execution continues independently. Reconnect by replaying persisted events without starting new work or duplicating text/results; never infer success from stream closure. +- Persistence failure: stop new dispatch and show the storage error; do not publish a committed revision whose bytes or provenance have not been saved. - Provider limits: record the error, honor provider retry guidance within a bounded attempt count, and avoid duplicate artifact publication. ## Acceptance and roadmap @@ -55,10 +60,12 @@ Supervisor-Skills is the initial reference case. Preserve its original directory | Milestone | Exit criteria | | --- | --- | | v0.0.1 foundation | Governance files, live GitHub settings, checks, specifications, and traceable source release | -| Runtime feasibility | On native Windows, validate skill loading, scoped tools, permission response, source events, cancellation, Unicode/space-containing paths, and process restart; document any WSL-only capability | +| Runtime feasibility | On native Windows, validate Harness skill loading, model/tool interfaces, isolated configuration, plan confirmation, scoped tools, questions/permissions, source events, cancellation, Unicode/space-containing paths, persistence and process restart; document any WSL-only capability | | v0.1.0-alpha.1 research loop | A new user completes setup and the full journey; real retrieval and artifact export pass the cases below | | Capability interconnection | Multiple adapters exchange structured research objects with recorded compatibility | | Research infrastructure | Long-running compute, environment capture, provenance, and tested reproduction workflows | | Open ecosystem | Contributor-maintained integrations, discipline packs, benchmarks, and independent registries | -The application acceptance suite must cover an economics question and a humanities/text-research question, an empty retrieval result, contradictory evidence, an inaccessible full text, invalid credentials, a cancelled run, restart after interruption, offline project viewing, export/import integrity, and a second runtime test double proving the adapter boundary. Check both Chinese and English interactions. Use controlled fixtures for repeatable automation and a separately recorded live retrieval smoke test. +The application acceptance suite must cover an economics question and a humanities/text-research question, an empty retrieval result, contradictory evidence, an inaccessible full text, invalid credentials, a cancelled run, restart after interruption, offline project viewing and export/import integrity. Check both Chinese and English interactions. Use controlled fixtures for repeatable automation and a separately recorded live retrieval smoke test. + +Also cover live artifact updates, exact-revision and citation/step navigation, structured answers, denied permissions, stale/duplicate decisions, cancellation races, connection replay without duplicate work, and keyboard-accessible desktop/drawer layouts. Prove the adapter boundary with a second runtime test double, a substitute model provider and an independent AG-UI consumer. Archives must remain readable/exportable without the original runtime or assistant-ui. Detailed outcomes are in the [workspace acceptance matrix](workspace.md#application-acceptance-scenarios); all remain unimplemented application gates. diff --git a/docs/verification.md b/docs/verification.md index 8f1188b..70549d0 100644 --- a/docs/verification.md +++ b/docs/verification.md @@ -12,6 +12,14 @@ The online merge and release evidence is retained in the foundation PR, push wor GitHub page inspection confirmed the README mark, navigation and license display. The initial remote Mermaid renderer failed in that inspection, so both READMEs now use a repository-owned SVG architecture diagram that loads without a diagram rendering service. The Windows/Linux PR checks and the main push checks passed for the foundation merge; subsequent workflow runs record the rendering fix and release gate outcomes. +## Workspace and Harness documentation validation, 2026-10-24 + +This revision adds workspace and minimal Harness specifications, ADR 0002, and coordinated updates to product, architecture, provenance, third-party references, bilingual README, changelog and the SVG architecture diagram. It supplies no application code or runtime packages. ADR 0001 retains the superseded OpenCode-first decision as history; current specifications select OpenLab Harness and AG-UI. + +On native Windows with Node.js 24.19.0, `npm run check` passed Markdown lint, repository/link validation and all nine existing tooling tests. `git diff --check` passed. The SVG was rendered locally for layout inspection; this verifies a documentation diagram, not an implemented research workspace. The application acceptance matrices in [workspace](workspace.md#application-acceptance-scenarios) and [Harness](harness.md#implementation-gates) remain unexecuted implementation gates. + +The Chinese vision is byte-identical to the committed file at the start of this revision. Both have SHA-256 `4a1089d837bfaea988418ceffec5b395e9c39fbd2c85c42cdabe69a31fab191f`. This differs from the historical source hash recorded above; this revision verifies preservation against Git, not equality to the original external source. No vision content or line endings were changed. + ## Baseline checks - `npm ci`: install development dependencies from the committed lockfile. @@ -31,4 +39,4 @@ The implementation is accepted when the foundation PR passes required checks and Static validation checks local document links, YAML structure and Issue Form fields. GitHub's rendering and form behavior should also be inspected on the published default branch. Badges and remote resources depend on their services and are not fetched during PR lint. -No application, OpenCode execution, scientific result, sandbox, research export, or diagnostic bundle has been implemented or tested by this foundation release. Native Windows runtime feasibility, full-text verification, retrieval reliability, and Supervisor-Skills licensing resolution remain explicit application gates in the [product](product.md), [architecture](architecture.md), and [third-party record](../THIRD_PARTY_NOTICES.md). +No application, OpenLab Harness or external-runtime execution, scientific result, sandbox, research export, or diagnostic bundle has been implemented or tested by this foundation release or the documentation revision above. Native Windows runtime feasibility, assistant-ui/AG-UI compatibility, full-text verification, retrieval reliability, and Supervisor-Skills licensing resolution remain explicit application gates in the [product](product.md), [architecture](architecture.md), [Harness](harness.md), and [third-party record](../THIRD_PARTY_NOTICES.md). diff --git a/docs/workspace.md b/docs/workspace.md new file mode 100644 index 0000000..fae38c2 --- /dev/null +++ b/docs/workspace.md @@ -0,0 +1,94 @@ +# Research workspace specification + +Status: accepted implementation design, updated 2026-10-24. No workspace application ships in v0.0.1. This document defines the first UI against the [product specification](product.md), [platform contracts](architecture.md), and [Harness specification](harness.md). + +## Research work stays visible + +The workspace combines conversation, agent execution state, and live research artifacts. A researcher should be able to ask a question, understand what is happening, inspect the evidence, and keep using the result after changing a runtime or model. OpenLab is an open research platform, not a wrapper around a single agent framework. + +The supplied OpenLab layout is the structural reference: a project sidebar, a central conversation with execution progress, and an artifact pane. Its example performance chart is illustrative and does not establish an experiment capability. Use OpenLab's existing vector brand assets. + +| Region | First-release contents and actions | +| --- | --- | +| Left: workspace | New research, project selection, conversations and run history within the selected project, tools and Skills, settings | +| Center: conversation and execution | Question and attachments, selected model and skill, proposed brief and plan, streaming messages, current stage, tool activity, pending questions and permission requests, cancellation | +| Right: research artifacts | Artifact list, selected revision preview, report citations, source metadata and verification status, originating run and step, export | + +A project can contain multiple conversations; a conversation can contain multiple runs. Selecting an old run shows its own state and products without relabeling them as the latest run. First release allows one active run per conversation; a follow-up during execution is saved as an unsent composer draft. Answers to a pending question use its dedicated form. Starting another run requires the active run to finish or cancellation to be confirmed. + +Desktop shows all three regions, with a collapsible left sidebar and a keyboard-adjustable divider for the artifact pane. On narrow screens the conversation is the main view; projects and artifacts open in labeled drawers. Preserve the selected project, run, artifact revision, and composer draft across layout changes. Opening a citation on a narrow screen opens the artifact drawer at that source. + +## Component responsibilities + +| Technology | OpenLab use | Boundary | +| --- | --- | --- | +| [assistant-ui](https://github.com/assistant-ui/assistant-ui) | Conversation primitives, composer, streaming text, tool-call presentation, attachment controls | Its view models are derived from platform-owned messages; no hosted conversation service is required | +| [assistant-ui AG-UI adapter](https://www.assistant-ui.com/docs/runtimes/ag-ui/overview) | Preferred `@assistant-ui/react-ag-ui` adapter with the AG-UI client | Connect only to OpenLab's gateway; validate history, reconnect and cancel integration before release | +| [AG-UI](https://docs.ag-ui.com/introduction) | Frontend event protocol for messages, tools, steps and shared view state | Does not define the research archive or Harness internals | +| [CopilotKit](https://github.com/CopilotKit/CopilotKit) | Reference for shared state, tool result UI and human interaction patterns | No CopilotKit SDK or service dependency in the first release | +| [shadcn/ui AI Elements](https://ui.shadcn.com/docs/ai-elements) | Composed plan, task, confirmation and source/citation views | Reuse presentation patterns without introducing a second conversation store | + +The official assistant-ui adapter accepts an AG-UI agent client. shadcn/ui documents AI Elements as compositions copied into a project. These references were reviewed on 2026-10-24; no application package is installed by this specification. Pin exact packages, component source revisions, licenses and compatibility evidence when implementation begins. + +The platform is authoritative for messages, run state, pending interactions, artifact revisions and sources. The UI keeps only presentation state such as selection, drawer visibility and unsent text. Shared state is a projection of authorized platform data. A client-side patch cannot grant permissions, change a verification level or mark a run successful. + +## Research interaction + +1. Create or reopen a project, select a conversation, and describe the question. Copy attached local material into project storage. +2. Select a versioned skill, model and retrieval configuration. Show missing requirements before execution. +3. Generate a brief and plan using the selected model. Show the proposed method, intended sources, requested capabilities and known limits. Model use for planning may incur usage; research tools remain blocked until confirmation. +4. Confirm the plan. Show the current phase, actual tool calls, available usage and newly saved artifacts as execution proceeds. +5. Answer structured questions or decide scoped permission requests inline. Show the exact scope, reason and affected action. Keep the request accessible in the run detail until resolved. +6. Review the report, follow citations to evidence, inspect failures and limitations, then export files with the platform research record. + +Progress comes from recorded steps and tool events. Show a phase or indeterminate activity indicator when the amount of work is unknown. A percentage is allowed only for a defined measured total, with its unit visible. Display user-facing activity summaries rather than hidden model reasoning. Missing provider usage stays unknown. + +Plan confirmation, question answers and permission decisions are separate operations. Rejecting a permission prevents that action; the runtime may continue with an already authorized alternative or explain that the task cannot proceed. The UI must not turn rejection into approval or cancellation into success. A plan revision that changes scope requires another confirmation before the new work begins. + +## Visible states + +| State | What the researcher sees and can do | +| --- | --- | +| Empty project | Start with a question or attach material; artifact pane explains where results will appear | +| `queued` | Waiting to start; cancel is available | +| `awaiting_confirmation` | Proposed plan/version with confirm and cancel actions; further research tool dispatch waits for confirmation | +| `running` | Current stage, tool activity, streaming reply and saved draft artifacts; cancel is available | +| `awaiting_input` | A labeled question with text or choice input; submit an answer or cancel | +| `awaiting_permission` | Requested action and scope with approve, deny and cancel controls | +| `cancelling` | Cancellation requested, waiting for confirmed termination; existing products remain visible | +| `succeeded` | Execution completed; review evidence and limitations before treating any claim as checked | +| `failed` | Actionable error, partial products and failed requests; retry creates a linked new run | +| `cancelled` | Termination confirmed; retain partial products and the cancellation record | +| `interrupted` | Runtime lost after reconciliation; retain history and offer an explicit linked retry | +| Disconnected | Connection status shown separately from the last known run state; reconnect without starting new work | + +Terminal states close outstanding interactions without applying unanswered approvals. Late or repeated decisions cannot resume a terminated run. Disable decision submission while disconnected and preserve entered answers as drafts until the server can acknowledge them. Closing a tab, switching projects or losing the event stream does not request cancellation. Explicit cancel uses the platform operation even if the UI adapter also aborts its local subscription. + +## Artifacts and evidence + +First release provides live Markdown report previews, structured source records, and attachment metadata/download. Preview copied text, Markdown, PNG and JPEG attachments; unsupported formats remain downloadable with an explicit preview-unavailable message. Do not execute uploaded code, active HTML, embedded scripts or report HTML. PDF rendering, scientific charts, experiment execution and Notebook rendering are later capabilities. Illustrative fixtures must say that their data is synthetic. + +Show a saved streaming report as a draft, including its producing run, last saved sequence and incomplete status when applicable. Artifact change events carry identifiers and revision information; obtain file contents through the platform artifact API. Committed revisions are immutable, hashed and individually selectable. Do not silently replace the revision the user is reading; show a newer-revision indicator with a switch action. Cancellation or failure does not remove saved drafts or committed revisions. + +Links use platform identifiers rather than positions in chat text. A message citation opens the source and supporting location when available; a producing-step link opens that step in its run; an artifact link opens the exact revision. Source details link back to the runs and steps that retrieved or used it. Missing full text is stated explicitly. Distinguish metadata verification, content verification and a checked claim-to-source association. Preserve contradictory evidence and failed retrieval alongside successful sources. + +All core controls require keyboard operation and accessible labels. Restore focus when drawers or dialogs close, announce stage changes without announcing each streamed token, and keep scroll position while a researcher reads earlier messages. Check both English and Chinese text, including long publication titles and narrow-screen layouts. + +## Application acceptance scenarios + +These are future implementation gates, not tests passed by this documentation change. + +| Scenario | Required outcome | +| --- | --- | +| Economics and humanities research, in English and Chinese | Complete setup, confirmed plan, real retrieval, evidence review and export; retain original titles and identifiers | +| Live report and source updates | Conversation, activity and artifact pane update from the same persisted run; drafts and immutable revisions are distinguishable | +| Citation and history navigation | Resolve message-to-source, artifact-to-step and source-to-run links, including old runs and revisions | +| Human input and permission denial | Answer resumes the same run once; denied work never executes; stale/repeated submissions do not duplicate continuation | +| Cancel and completion race | Requested cancellation is distinct from termination; recorded terminal outcome is authoritative and partial products remain | +| Disconnect and tab close | Execution continues; reconnect restores ordered events without duplicate text, artifacts, tool calls or billing | +| Process restart | Completed products remain readable; lost execution becomes interrupted after reconciliation, with explicit linked retry | +| Retrieval limits | Empty results, inaccessible full text and conflicting evidence retain their recorded limitations | +| Responsive and offline viewing | Keyboard-accessible three-pane and drawer layouts; local service can show saved projects without provider/network access | +| Replaceable components | A second runtime test double, substitute model provider and independent AG-UI consumer use the contracts; export/import works without assistant-ui or runtime history | + +Use controlled event and retrieval fixtures for automation, plus a separately recorded live retrieval smoke test. The [product acceptance criteria](product.md#acceptance-and-roadmap) remain the release gate.