@xfey/tutti 0.1.0

package/migrations/0004_read_state.sql

@@ -0,0 +1,109 @@
+CREATE TABLE IF NOT EXISTS read_notification_events (
+  event_cursor INTEGER PRIMARY KEY,
+  scope TEXT NOT NULL CHECK (scope IN ('chat', 'worklist')),
+  source_kind TEXT NOT NULL CHECK (length(source_kind) > 0),
+  source_ref TEXT NOT NULL CHECK (length(source_ref) > 0),
+  actor_kind TEXT CHECK (
+    actor_kind IS NULL OR actor_kind IN ('human', 'system', 'agent')
+  ),
+  actor_ref TEXT,
+  occurred_at TEXT NOT NULL,
+  created_at TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_read_notification_events_scope_cursor
+  ON read_notification_events (scope, event_cursor);
+
+CREATE INDEX IF NOT EXISTS idx_read_notification_events_scope_occurred
+  ON read_notification_events (scope, occurred_at, event_cursor);
+
+CREATE TABLE IF NOT EXISTS read_state_cursors (
+  account_ref TEXT NOT NULL,
+  scope TEXT NOT NULL CHECK (scope IN ('chat', 'worklist')),
+  read_event_cursor INTEGER NOT NULL DEFAULT 0 CHECK (read_event_cursor >= 0),
+  read_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  PRIMARY KEY (account_ref, scope)
+);
+
+CREATE INDEX IF NOT EXISTS idx_read_state_cursors_account
+  ON read_state_cursors (account_ref);
+
+INSERT INTO read_notification_events (
+  scope,
+  source_kind,
+  source_ref,
+  actor_kind,
+  actor_ref,
+  occurred_at,
+  created_at
+)
+SELECT
+  'chat',
+  'message',
+  id,
+  author_kind,
+  author_ref,
+  created_at,
+  created_at
+FROM messages;
+
+INSERT INTO read_notification_events (
+  scope,
+  source_kind,
+  source_ref,
+  occurred_at,
+  created_at
+)
+SELECT
+  'worklist',
+  'task_module',
+  id,
+  COALESCE(updated_at, created_at),
+  COALESCE(updated_at, created_at)
+FROM task_modules;
+
+INSERT INTO read_notification_events (
+  scope,
+  source_kind,
+  source_ref,
+  occurred_at,
+  created_at
+)
+SELECT
+  'worklist',
+  'task',
+  id,
+  updated_at,
+  updated_at
+FROM tasks;
+
+INSERT INTO read_notification_events (
+  scope,
+  source_kind,
+  source_ref,
+  occurred_at,
+  created_at
+)
+SELECT
+  'worklist',
+  'task_detail',
+  task_id,
+  updated_at,
+  updated_at
+FROM task_details;
+
+INSERT INTO read_notification_events (
+  scope,
+  source_kind,
+  source_ref,
+  occurred_at,
+  created_at
+)
+SELECT
+  'worklist',
+  'run_result',
+  id,
+  created_at,
+  created_at
+FROM run_results;

package/migrations/0005_provider_usage.sql

@@ -0,0 +1,15 @@
+CREATE TABLE IF NOT EXISTS provider_usage_events (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  provider TEXT NOT NULL CHECK (provider IN ('openai')),
+  source TEXT NOT NULL CHECK (length(source) > 0),
+  model TEXT,
+  input_tokens INTEGER NOT NULL DEFAULT 0 CHECK (input_tokens >= 0),
+  cached_input_tokens INTEGER NOT NULL DEFAULT 0 CHECK (cached_input_tokens >= 0),
+  output_tokens INTEGER NOT NULL DEFAULT 0 CHECK (output_tokens >= 0),
+  reasoning_output_tokens INTEGER NOT NULL DEFAULT 0 CHECK (reasoning_output_tokens >= 0),
+  total_tokens INTEGER NOT NULL CHECK (total_tokens >= 0),
+  recorded_at TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_provider_usage_events_recorded_at
+  ON provider_usage_events (recorded_at, id);

package/migrations/0006_scratchpad_source_state.sql

@@ -0,0 +1,29 @@
+CREATE TABLE IF NOT EXISTS scratchpad_source_state (
+  id TEXT PRIMARY KEY CHECK (id = 'current'),
+  main_chat_cursor_created_at TEXT,
+  main_chat_cursor_message_id TEXT,
+  task_compile_cursor_submitted_at TEXT,
+  task_compile_cursor_round_id TEXT,
+  dirty_since TEXT,
+  in_flight_activity_ref TEXT,
+  in_flight_started_at TEXT,
+  last_completed_at TEXT,
+  last_failed_at TEXT,
+  backoff_until TEXT,
+  updated_at TEXT NOT NULL,
+  CHECK (
+    (main_chat_cursor_created_at IS NULL AND main_chat_cursor_message_id IS NULL)
+    OR (main_chat_cursor_created_at IS NOT NULL AND main_chat_cursor_message_id IS NOT NULL)
+  ),
+  CHECK (
+    (task_compile_cursor_submitted_at IS NULL AND task_compile_cursor_round_id IS NULL)
+    OR (
+      task_compile_cursor_submitted_at IS NOT NULL
+      AND task_compile_cursor_round_id IS NOT NULL
+    )
+  ),
+  CHECK (
+    (in_flight_activity_ref IS NULL AND in_flight_started_at IS NULL)
+    OR (in_flight_activity_ref IS NOT NULL AND in_flight_started_at IS NOT NULL)
+  )
+);

package/migrations/0007_workspace_signal_read_state_scopes.sql

@@ -0,0 +1,74 @@
+ALTER TABLE read_notification_events RENAME TO read_notification_events_old;
+
+CREATE TABLE read_notification_events (
+  event_cursor INTEGER PRIMARY KEY,
+  scope TEXT NOT NULL CHECK (scope IN ('chat', 'worklist', 'references', 'skills')),
+  source_kind TEXT NOT NULL CHECK (length(source_kind) > 0),
+  source_ref TEXT NOT NULL CHECK (length(source_ref) > 0),
+  actor_kind TEXT CHECK (
+    actor_kind IS NULL OR actor_kind IN ('human', 'system', 'agent')
+  ),
+  actor_ref TEXT,
+  occurred_at TEXT NOT NULL,
+  created_at TEXT NOT NULL
+);
+
+INSERT INTO read_notification_events (
+  event_cursor,
+  scope,
+  source_kind,
+  source_ref,
+  actor_kind,
+  actor_ref,
+  occurred_at,
+  created_at
+)
+SELECT
+  event_cursor,
+  scope,
+  source_kind,
+  source_ref,
+  actor_kind,
+  actor_ref,
+  occurred_at,
+  created_at
+FROM read_notification_events_old;
+
+DROP TABLE read_notification_events_old;
+
+CREATE INDEX idx_read_notification_events_scope_cursor
+  ON read_notification_events (scope, event_cursor);
+
+CREATE INDEX idx_read_notification_events_scope_occurred
+  ON read_notification_events (scope, occurred_at, event_cursor);
+
+ALTER TABLE read_state_cursors RENAME TO read_state_cursors_old;
+
+CREATE TABLE read_state_cursors (
+  account_ref TEXT NOT NULL,
+  scope TEXT NOT NULL CHECK (scope IN ('chat', 'worklist', 'references', 'skills')),
+  read_event_cursor INTEGER NOT NULL DEFAULT 0 CHECK (read_event_cursor >= 0),
+  read_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  PRIMARY KEY (account_ref, scope)
+);
+
+INSERT INTO read_state_cursors (
+  account_ref,
+  scope,
+  read_event_cursor,
+  read_at,
+  updated_at
+)
+SELECT
+  account_ref,
+  scope,
+  read_event_cursor,
+  read_at,
+  updated_at
+FROM read_state_cursors_old;
+
+DROP TABLE read_state_cursors_old;
+
+CREATE INDEX idx_read_state_cursors_account
+  ON read_state_cursors (account_ref);

package/migrations/0008_provider_usage_anchors.sql

@@ -0,0 +1,32 @@
+ALTER TABLE provider_usage_events
+  ADD COLUMN activity_ref TEXT;
+
+ALTER TABLE provider_usage_events
+  ADD COLUMN workflow_ref TEXT;
+
+ALTER TABLE provider_usage_events
+  ADD COLUMN task_id TEXT;
+
+ALTER TABLE provider_usage_events
+  ADD COLUMN run_result_id TEXT;
+
+ALTER TABLE provider_usage_events
+  ADD COLUMN run_lineage_kind TEXT CHECK (
+    run_lineage_kind IS NULL OR run_lineage_kind IN ('initial', 'continuation', 'retry')
+  );
+
+CREATE INDEX IF NOT EXISTS idx_provider_usage_events_activity_ref
+  ON provider_usage_events (activity_ref, recorded_at, id)
+  WHERE activity_ref IS NOT NULL;
+
+CREATE INDEX IF NOT EXISTS idx_provider_usage_events_workflow_ref
+  ON provider_usage_events (workflow_ref, recorded_at, id)
+  WHERE workflow_ref IS NOT NULL;
+
+CREATE INDEX IF NOT EXISTS idx_provider_usage_events_task_id
+  ON provider_usage_events (task_id, recorded_at, id)
+  WHERE task_id IS NOT NULL;
+
+CREATE INDEX IF NOT EXISTS idx_provider_usage_events_run_result_id
+  ON provider_usage_events (run_result_id, recorded_at, id)
+  WHERE run_result_id IS NOT NULL;

package/migrations/0009_project_timeline_events.sql

@@ -0,0 +1,33 @@
+CREATE TABLE IF NOT EXISTS project_timeline_events (
+  id TEXT PRIMARY KEY,
+  event_kind TEXT NOT NULL CHECK (
+    event_kind IN ('context_sync', 'reference_summary', 'promotion_reconcile')
+  ),
+  status TEXT NOT NULL CHECK (
+    status IN ('running', 'completed', 'failed', 'needs_human', 'skipped')
+  ),
+  summary TEXT,
+  activity_ref TEXT,
+  workflow_ref TEXT,
+  task_id TEXT,
+  commit_oid TEXT,
+  meta_json TEXT NOT NULL DEFAULT '[]' CHECK (
+    json_valid(meta_json) AND json_type(meta_json) = 'array'
+  ),
+  occurred_at TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_project_timeline_events_order
+  ON project_timeline_events (occurred_at, id);
+
+CREATE INDEX IF NOT EXISTS idx_project_timeline_events_activity_ref
+  ON project_timeline_events (activity_ref, occurred_at, id)
+  WHERE activity_ref IS NOT NULL;
+
+CREATE INDEX IF NOT EXISTS idx_project_timeline_events_workflow_ref
+  ON project_timeline_events (workflow_ref, occurred_at, id)
+  WHERE workflow_ref IS NOT NULL;
+
+CREATE INDEX IF NOT EXISTS idx_project_timeline_events_task_id
+  ON project_timeline_events (task_id, occurred_at, id)
+  WHERE task_id IS NOT NULL;

package/migrations/0010_project_brief.sql

@@ -0,0 +1,13 @@
+CREATE TABLE IF NOT EXISTS project_brief (
+  id TEXT PRIMARY KEY CHECK (id = 'current'),
+  product_summary TEXT NOT NULL,
+  tech_summary TEXT NOT NULL,
+  structure_summary TEXT NOT NULL,
+  principles_summary TEXT NOT NULL,
+  source_docs_json TEXT NOT NULL CHECK (
+    json_valid(source_docs_json) AND json_type(source_docs_json) = 'array'
+  ),
+  updated_by_activity_ref TEXT,
+  updated_by_workflow_ref TEXT,
+  updated_at TEXT NOT NULL
+);

package/migrations/0011_message_author_avatar.sql

@@ -0,0 +1,5 @@
+ALTER TABLE messages
+  ADD COLUMN author_avatar_json TEXT CHECK (
+    author_avatar_json IS NULL
+    OR (json_valid(author_avatar_json) AND json_type(author_avatar_json) = 'object')
+  );

package/migrations/README.md

@@ -0,0 +1,44 @@
+# migrations
+
+## 作用
+
+这里保存 `apps/server` 本地 SQLite store 的 numbered SQL migrations。
+
+## 约定
+
+- migration 文件命名使用 `0001_init.sql`、`0002_<name>.sql` 形式。
+- migration 归 host server 所有，不放入 `packages/shared`。
+- `schema_migrations` 记录已应用版本、checksum 和应用时间。
+- SQLite adapter 初始化必须先开启 foreign keys、WAL 和合理 busy timeout；这些 PRAGMA 不放进 numbered migration 文件。
+
+## 当前 migrations
+
+- `0001_init.sql`：初始化本地 `tutti.sqlite`，包含协作 truth records、store metadata、command idempotency、clarification replay hint、索引和关键 trigger。
+- `0002_allow_sealed_round_successor_note.sql`：允许 Control Plane 在 sealed clarification round 内追加只读 Tutti successor 结论消息，同时继续禁止人类补充消息写入 sealed round。
+- `0003_drop_scratchpad_source_message_refs.sql`：从 Scratchpad 持久化中移除不再暴露给模型、API 或 UI 的来源消息追溯字段。
+- `0004_read_state.sql`：为 Chat / Worklist 未读摘要新增 read notification events 与 per-account read-state cursor，并从已有消息、任务、任务详情和 run result 回填初始事件。
+- `0005_provider_usage.sql`：新增 provider token usage append-only ledger，用于 Timeline token overview projection。
+- `0006_scratchpad_source_state.sql`：新增自动 Scratchpad refresh 的本机 source cursor / dirty / in-flight / backoff 状态表。
+- `0007_workspace_signal_read_state_scopes.sql`：扩展 read-state scope，允许 References 与 Skills 写入模块更新通知事件。
+- `0008_provider_usage_anchors.sql`：为 provider usage ledger 增加可空 activity / workflow / task / run result anchor 字段，供 Timeline 尽力把 token usage 挂到可证明的历史节点。
+- `0009_project_timeline_events.sql`：新增 Timeline 专用 append-only durable event 表，用于记录缺少其他稳定 record 的 context sync、reference summary 与 promotion reconcile 轻量可观测性节点。
+- `0010_project_brief.sql`：新增 host-local Project Brief projection 表，用于保存四个 baseline Project Docs 的短摘要和 source fingerprint。
+- `0011_message_author_avatar.sql`：为消息作者增加可选 Relay account avatar 快照，保证跨浏览器查看历史消息时不依赖当前 viewer profile 或 presence sample。
+
+## 当前实现状态
+
+- `0001_init.sql`、`0002_allow_sealed_round_successor_note.sql`、`0003_drop_scratchpad_source_message_refs.sql`、`0004_read_state.sql`、`0005_provider_usage.sql`、`0006_scratchpad_source_state.sql`、`0007_workspace_signal_read_state_scopes.sql`、`0008_provider_usage_anchors.sql`、`0009_project_timeline_events.sql`、`0010_project_brief.sql` 与 `0011_message_author_avatar.sql` 已存在，代表当前 host project SQLite schema contract。
+- SQLite adapter、migration runner、checksum 校验、store metadata 初始化、transaction helper 与 command recovery scan helper 已实现。
+- 协作 repository 与 Control Plane 已实现第一批业务读写；Phase 7 首批已复用 `0001_init.sql` 中的 `tasks.latest_run_result_id`、`task_details.result_json` 与 `run_results` 表完成 Run result / checks / promotion 摘要持久化。Control Plane recovery resolver 与 task-bound continuation / retry 复用现有 schema；deterministic promotion reconcile 的业务 truth 仍写入最终 Run result / task detail result，Timeline 轻量节点写入 `project_timeline_events`，merge workspace 不进入 SQLite truth。`provider_usage_events` 只保存 token 计数、调用来源、模型名、记录时间和可空 anchor，不保存 provider secret、prompt 或 raw response。store 基础设施本身已经可以创建并迁移 `tutti.sqlite`。
+
+## PRAGMA 边界
+
+`PRAGMA foreign_keys = ON`、`PRAGMA journal_mode = WAL` 与 `PRAGMA busy_timeout = 5000` 属于 SQLite connection / adapter 初始化步骤。
+
+原因：
+
+- `journal_mode = WAL` 不能安全放进事务包裹的 migration runner。
+- numbered migration 应只包含 schema 变更，便于统一 checksum、事务执行和回滚解释。
+- store adapter 每次打开连接都应显式设置 `foreign_keys` 与 `busy_timeout`。
+
+schema 设计说明见 [../../../docs/system/sqlite-store-schema.md](../../../docs/system/sqlite-store-schema.md)。

package/node_modules/@tutti/relay-client/dist/host-control.d.ts

@@ -0,0 +1,164 @@
+import { type HostConnectionRef, type IdempotencyKey, type ProjectId, type RelayProjectRef, type RelayUploadRef } from "@tutti/shared/ids";
+import type { RelayUploadPurpose, Sha256Digest } from "@tutti/shared/schemas/api";
+export type RelayHostControlFetch = (input: string | URL, init?: RequestInit) => Promise<Response>;
+export type RelayProjectProjection = {
+    relay_project_ref: RelayProjectRef;
+    display_name: string;
+    host_status: "online" | "offline" | "unknown";
+};
+export type HostConnectionProjection = {
+    host_connection_ref: HostConnectionRef;
+    relay_project_ref: RelayProjectRef;
+    status: "registered" | "online" | "replaced";
+    heartbeat_interval_ms: number;
+    tunnel_url: string;
+    connected_at: string;
+};
+export type JoinTokenProjection = {
+    join_url?: string;
+    expires_at: string;
+    reusable: true;
+    state: "active" | "expired" | "revoked";
+    visibility: "visible_once" | "not_recoverable";
+};
+export type RegisterRelayHostConnectionPayload = {
+    project_identity: {
+        source: "git_config";
+        project_id: ProjectId;
+    };
+    host_auth: {
+        kind: "host_registration_secret_v1";
+        secret: string;
+    };
+    display_name: string;
+    host: {
+        server_version: string;
+        host_project_api_base_path: "/api/v1";
+        capabilities: {
+            sse: boolean;
+            provider_config_query: boolean;
+            browser_secret_write: false;
+            repo_viewer: boolean;
+        };
+    };
+    join_token?: {
+        mode: "reuse_active" | "rotate";
+        ttl_seconds?: number;
+    };
+};
+export type RegisterRelayHostConnectionResult = {
+    relay_project: RelayProjectProjection;
+    host_connection: HostConnectionProjection;
+    join_token: JoinTokenProjection;
+    host_connection_token: string;
+};
+export type RegisterRelayHostConnectionResponse = {
+    command_id: IdempotencyKey;
+    disposition: {
+        kind: "registered";
+    } | {
+        kind: "interrupted";
+        retry_with_new_command_id: true;
+    };
+    result?: RegisterRelayHostConnectionResult;
+};
+export type RefreshRelayJoinTokenPayload = {
+    project_identity: {
+        source: "git_config";
+        project_id: ProjectId;
+    };
+    host_auth: {
+        kind: "host_registration_secret_v1";
+        secret: string;
+    };
+    relay_project_ref: RelayProjectRef;
+    host_connection_ref: HostConnectionRef;
+    join_token?: {
+        mode: "reuse_active" | "rotate";
+        ttl_seconds?: number;
+    };
+};
+export type RefreshRelayJoinTokenResponse = {
+    join_token: JoinTokenProjection;
+};
+export type RelayUploadProjection = {
+    upload_id: RelayUploadRef;
+    relay_project_ref: RelayProjectRef;
+    purpose: RelayUploadPurpose;
+    file_name: string;
+    size_bytes: number;
+    sha256: Sha256Digest;
+    media_type?: string;
+    expires_at: string;
+};
+export type RelayUploadSignedRequest = {
+    method: "GET" | "DELETE";
+    url: string;
+};
+export type ResolveRelayUploadResponse = {
+    upload: RelayUploadProjection;
+    get: RelayUploadSignedRequest & {
+        method: "GET";
+    };
+    delete: RelayUploadSignedRequest & {
+        method: "DELETE";
+    };
+};
+export type CompleteRelayUploadResponse = {
+    upload: RelayUploadProjection;
+};
+export type RegisterRelayHostConnectionOptions = {
+    relayUrl: string;
+    projectId: ProjectId;
+    hostRegistrationSecret: string;
+    displayName: string;
+    serverVersion: string;
+    commandId?: IdempotencyKey;
+    issuedAt?: Date;
+    joinToken?: {
+        mode: "reuse_active" | "rotate";
+        ttlSeconds?: number;
+    };
+    capabilities?: Partial<RegisterRelayHostConnectionPayload["host"]["capabilities"]>;
+    fetch?: RelayHostControlFetch;
+    timeoutMs?: number;
+};
+export type RefreshRelayJoinTokenOptions = {
+    relayUrl: string;
+    projectId: ProjectId;
+    relayProjectRef: RelayProjectRef;
+    hostConnectionRef: HostConnectionRef;
+    hostRegistrationSecret: string;
+    joinToken?: {
+        mode: "reuse_active" | "rotate";
+        ttlSeconds?: number;
+    };
+    fetch?: RelayHostControlFetch;
+    timeoutMs?: number;
+};
+export type ResolveRelayUploadOptions = {
+    relayUrl: string;
+    projectId: ProjectId;
+    relayProjectRef: RelayProjectRef;
+    hostConnectionRef: HostConnectionRef;
+    hostRegistrationSecret: string;
+    uploadId: RelayUploadRef;
+    fetch?: RelayHostControlFetch;
+    timeoutMs?: number;
+};
+export type CompleteRelayUploadOptions = ResolveRelayUploadOptions & {
+    status: "completed" | "aborted";
+};
+export type RelayHostControlClientErrorCode = "relay_unavailable" | "relay_registration_failed";
+export declare class RelayHostControlClientError extends Error {
+    readonly code: RelayHostControlClientErrorCode;
+    readonly retryable: boolean;
+    readonly statusCode?: number | undefined;
+    readonly relayErrorCode?: string | undefined;
+    constructor(code: RelayHostControlClientErrorCode, message: string, retryable: boolean, statusCode?: number | undefined, relayErrorCode?: string | undefined);
+}
+export declare function registerRelayHostConnection(options: RegisterRelayHostConnectionOptions): Promise<RegisterRelayHostConnectionResponse>;
+export declare function refreshRelayJoinToken(options: RefreshRelayJoinTokenOptions): Promise<RefreshRelayJoinTokenResponse>;
+export declare function resolveRelayUpload(options: ResolveRelayUploadOptions): Promise<ResolveRelayUploadResponse>;
+export declare function completeRelayUpload(options: CompleteRelayUploadOptions): Promise<CompleteRelayUploadResponse>;
+//# sourceMappingURL=host-control.d.ts.map