@xfey/tutti 0.1.0

package/README.md

@@ -0,0 +1,50 @@
+# server
+
+## 作用
+
+`apps/server` 是 Tutti 的项目 host service。
+
+它负责：
+
+- `tutti launch` 后的项目绑定、恢复和接管入口
+- Fastify API、SSE、packaged static Web 产物服务和 server 生命周期
+- SQLite store、migrations、repository 与协作真相读写
+- `control-plane`、scheduler、`procedure-engine`、`run-engine`、`workspace-ops` 与 OpenAI provider 接入
+- host 到 Relay 的连接与工作区加入协作
+
+## 结构
+
+- `src/`：server 代码根目录。
+- `prompts/`：大模型 prompt、指令模板和 Codex 执行模板的统一保存目录。
+- `migrations/`：本地 `tutti.sqlite` 的 SQL migrations。
+- `cli-package.mjs`：生成临时 staging `@xfey/tutti` package artifact 的脚本。
+- `prepare-package-assets.mjs`：把 Web build output 和内部 runtime package 复制到 staging package 所需位置。
+- `pack-dry-run.mjs`：构建 staging package 并执行 `npm pack --dry-run --json` 文件列表校验。
+- `smoke-packed-cli.mjs`：安装并验证 packed CLI tarball 的本地 smoke。
+
+## 当前状态
+
+- 已具备 Fastify host shell、CLI launch、Dev Runner、Host Project API、SSE、SQLite store、collaboration-state、workspace read-state、project timeline observability helper、Control Plane、Procedure / Run、workspace-ops、checks、Relay staged upload finalize、user skills 文件服务、artifacts 可视化产物查看层和 OpenAI / Codex provider 接入。
+- Host server 支持在显式 `webStatic.root` 或 packaged `web/` 存在时服务 Web 静态产物；`/api/*`、SSE、health 和 host-local control 不被 SPA fallback 吞掉。
+- Root `pack:dry-run` 会先清理 build output、重新构建，再复制 `apps/web/dist` 到 package-local `web/`，生成临时 staging `@xfey/tutti` artifact，并校验 npm pack 文件列表包含 CLI、migrations、prompts、Web index 和 bundled `@tutti/shared` / `@tutti/relay-client`，同时排除源码、source map、日志、SQLite、`.env`、`.tutti-dev` 与测试产物。
+- Root `smoke:packed-cli` 同样从干净 build output 生成 staging `@xfey/tutti` tarball、在临时目录安装，并验证 SQLite native binding、`tutti --help` / `tutti launch --help`、migrations、prompts、Web static index 与 bundled internal dependencies；该 smoke 不需要 Tutti source repo 存在。
+- `prompts/` 是所有模型-facing prompt、指令模板和 Codex 执行模板的统一落点；长 prompt 不内联在 TypeScript 中。
+- Host Project API 只信任 Relay tunnel metadata 注入的 `relay_session_context`；direct loopback 缺少可信 context 时不作为浏览器工作区入口。
+- 详细模块落点见 `src/README.md`；logger redaction、command idempotency、schema、provider 与 Codex 边界以 `docs/system/` 对应 canonical 文档为准。
+
+## 约定
+
+- 默认运行在 macOS / Linux host 上。
+- 项目 truth 只在 host server 与正式 repo 中，不进入 Relay。
+- SQLite driver 默认使用 `better-sqlite3`，只有 store adapter 可以直接依赖 driver。
+- 真实仓库任务的正式 adapter 使用 Codex app-server；普通结构化判断走 OpenAI SDK。两者共享同一份 OpenAI provider config。
+- 所有模型-facing prompt 和长指令模板都必须放在 `prompts/`，不得在 TypeScript 中内联长 prompt；模板规范见 [../../docs/system/prompt-template-management.md](../../docs/system/prompt-template-management.md)。
+- 不实现绕过 Relay 的单人工作区路径。
+- packaged / production `tutti launch` 默认连接 `https://tutti.now`；`TUTTI_RELAY_URL` 可覆盖 Relay URL，本地开发 dev runner 默认使用 `http://127.0.0.1:4370`。
+- host 注册使用 machine-local `host_registration_secret`；该 secret 明文只可写入受限权限的 machine-local secret store，不写入目标项目 repo、Git local config 项目身份、SQLite 协作真相或日志，`binding.json` 只保存引用。
+- Relay registration 成功后只把 `relay_project_ref` 写回 machine-local binding；join URL 只在 host 本机终端或当前 host-local control 内存状态中展示，不写入 binding、runtime endpoint、SQLite 协作真相或日志。
+- Reference 和 Skills 上传的最终写入由 Host Project API 完成；Host 只通过 Relay host-control resolve 获取短期 R2 URL 下载 staged object，不接收浏览器 base64 文件正文，也不持久化 presigned URL。
+- Host Project API command 的 browser session context 只信任 Relay tunnel metadata 中的 `relay_session_context`；route handler 不读取浏览器身份 header，也不接受 payload 内身份字段。
+- Fastify request log、debug log、SSE payload、activity event 和 run result 都必须经过 redaction，不得泄露 provider secret、host registration secret、host connection token、join token、cookie、host 绝对路径或 run workspace path。
+- Repo Viewer path policy 已以可测试 helper 落地并接入 Phase 6 Viewer / Reference Files API；Phase 7 checks executor 已以 safe npm script discovery、结构化 `spawn`、timeout、stdout / stderr redaction 与 no-shell 执行为首批命令安全边界。
+- 当前源码 package root 仍是 `apps/server`；对外 npm 名由 staging artifact 使用 `@xfey/tutti`，internal workspace dependency bundling 和 packed CLI install smoke 已接通。

package/dist/approvals/index.d.ts

@@ -0,0 +1,3 @@
+export { ApprovalRequestManager, type ApprovalDecisionActor, type ApprovalRequestManagerOptions, type AwaitApprovalInput, type DecideApprovalInput, } from "./manager.js";
+export { buildApprovalProjection, type ApprovalAppServerResponse, type ApprovalDecisionRuntime, type ApprovalProjectionBuildResult, type ApprovalProjectionContext, } from "./projections.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/approvals/index.js

@@ -0,0 +1,3 @@
+export { ApprovalRequestManager, } from "./manager.js";
+export { buildApprovalProjection, } from "./projections.js";
+//# sourceMappingURL=index.js.map

package/dist/approvals/manager.d.ts

@@ -0,0 +1,47 @@
+import type { ApprovalRequestId, IdempotencyKey } from "@tutti/shared/ids";
+import type { ActiveApprovalProjection, DecideApprovalDisposition, DecideApprovalPayload, DecideApprovalResult } from "@tutti/shared/schemas/api";
+import type { CodexAppServerJsonRpcServerRequest } from "../providers/openai/app-server/json-rpc.js";
+import type { WorkspaceEventBus } from "../server-shell/http/workspace-events.js";
+import { type ApprovalProjectionContext, type ApprovalAppServerResponse } from "./projections.js";
+export type ApprovalDecisionActor = {
+    account_ref: string;
+    display_name: string;
+};
+export type ApprovalRequestManagerOptions = {
+    events?: WorkspaceEventBus;
+    now?: () => Date;
+    resolvedTtlMs?: number;
+};
+export type AwaitApprovalInput = {
+    request: CodexAppServerJsonRpcServerRequest;
+    context?: Partial<Omit<ApprovalProjectionContext, "requestedAt">>;
+    timeoutMs: number;
+};
+export type DecideApprovalInput = {
+    approvalId: ApprovalRequestId;
+    payload: DecideApprovalPayload;
+    commandId?: IdempotencyKey;
+    actor?: ApprovalDecisionActor;
+};
+export declare class ApprovalRequestManager {
+    private readonly events;
+    private readonly now;
+    private readonly resolvedTtlMs;
+    private active;
+    private resolved;
+    private resolvedTimer;
+    constructor(options?: ApprovalRequestManagerOptions);
+    getActiveApproval(): ActiveApprovalProjection;
+    awaitApproval(input: AwaitApprovalInput): Promise<ApprovalAppServerResponse>;
+    decide(input: DecideApprovalInput): {
+        disposition: DecideApprovalDisposition;
+        result?: DecideApprovalResult;
+    };
+    clearPending(response?: ApprovalAppServerResponse): void;
+    dispose(): void;
+    private resolveActive;
+    private clearResolvedAfterTtl;
+    private clearResolved;
+    private publish;
+}
+//# sourceMappingURL=manager.d.ts.map

package/dist/approvals/manager.js

@@ -0,0 +1,180 @@
+import { buildApprovalProjection, } from "./projections.js";
+const DEFAULT_RESOLVED_TTL_MS = 3000;
+function approvalInvalidates() {
+    return [
+        { kind: "approval" },
+        { kind: "execution_status" },
+        { kind: "bootstrap" },
+    ];
+}
+function timeoutError() {
+    return {
+        code: "approval_timeout",
+        message: "Approval request timed out.",
+    };
+}
+function cancelledError() {
+    return {
+        code: "approval_cancelled",
+        message: "Approval request was cancelled.",
+    };
+}
+export class ApprovalRequestManager {
+    events;
+    now;
+    resolvedTtlMs;
+    active = null;
+    resolved = null;
+    resolvedTimer;
+    constructor(options = {}) {
+        this.events = options.events;
+        this.now = options.now ?? (() => new Date());
+        this.resolvedTtlMs = options.resolvedTtlMs ?? DEFAULT_RESOLVED_TTL_MS;
+    }
+    getActiveApproval() {
+        if (this.active !== null) {
+            return this.active.projection;
+        }
+        if (this.resolved !== null) {
+            return this.resolved;
+        }
+        return { state: "none" };
+    }
+    async awaitApproval(input) {
+        if (this.active !== null) {
+            return {
+                kind: "error",
+                error: {
+                    code: "approval_already_pending",
+                    message: "Another approval request is already pending.",
+                },
+            };
+        }
+        this.clearResolved(false);
+        const requestedAt = this.now();
+        const expiresAt = new Date(requestedAt.getTime() + input.timeoutMs);
+        const build = buildApprovalProjection(input.request, {
+            ...input.context,
+            requestedAt: requestedAt.toISOString(),
+            expiresAt: expiresAt.toISOString(),
+        });
+        if (build === null) {
+            return {
+                kind: "error",
+                error: {
+                    code: "unsupported_approval_request",
+                    message: `Unsupported approval request: ${input.request.method}`,
+                },
+            };
+        }
+        return await new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                if (this.active?.projection.request.approval_id !== build.request.approval_id) {
+                    return;
+                }
+                this.resolveActive({
+                    decisionId: "timeout",
+                    label: "Timed out",
+                    outcome: "expired",
+                    response: { kind: "error", error: timeoutError() },
+                });
+            }, input.timeoutMs);
+            this.active = {
+                projection: {
+                    state: "pending",
+                    request: build.request,
+                },
+                decisions: build.decisions,
+                resolve,
+                timer,
+            };
+            this.publish(this.active.projection);
+        });
+    }
+    decide(input) {
+        const active = this.active;
+        if (active === null || active.projection.request.approval_id !== input.approvalId) {
+            return {
+                disposition: { kind: "stale_approval" },
+                result: { approval: this.getActiveApproval() },
+            };
+        }
+        const decision = active.decisions.get(input.payload.decision_id);
+        if (decision === undefined) {
+            return {
+                disposition: { kind: "decision_unavailable" },
+                result: { approval: active.projection },
+            };
+        }
+        this.resolveActive(decision, input.actor);
+        return {
+            disposition: { kind: "accepted" },
+            result: { approval: this.getActiveApproval() },
+        };
+    }
+    clearPending(response = { kind: "error", error: cancelledError() }) {
+        const active = this.active;
+        if (active === null) {
+            return;
+        }
+        clearTimeout(active.timer);
+        this.active = null;
+        active.resolve(response);
+        this.publish(this.getActiveApproval());
+    }
+    dispose() {
+        this.clearPending();
+        this.clearResolved(false);
+    }
+    resolveActive(decision, actor) {
+        const active = this.active;
+        if (active === null) {
+            return;
+        }
+        clearTimeout(active.timer);
+        this.active = null;
+        this.resolved = {
+            state: "resolved",
+            request: active.projection.request,
+            resolution: {
+                decision_id: decision.decisionId,
+                label: decision.label,
+                outcome: decision.outcome,
+                decided_at: this.now().toISOString(),
+                ...(actor === undefined ? {} : { decided_by: actor }),
+            },
+        };
+        active.resolve(decision.response);
+        this.publish(this.resolved);
+        this.clearResolvedAfterTtl();
+    }
+    clearResolvedAfterTtl() {
+        if (this.resolvedTimer !== undefined) {
+            clearTimeout(this.resolvedTimer);
+        }
+        this.resolvedTimer = setTimeout(() => {
+            this.clearResolved(true);
+        }, this.resolvedTtlMs);
+    }
+    clearResolved(publish) {
+        if (this.resolvedTimer !== undefined) {
+            clearTimeout(this.resolvedTimer);
+            this.resolvedTimer = undefined;
+        }
+        if (this.resolved === null) {
+            return;
+        }
+        this.resolved = null;
+        if (publish) {
+            this.publish(this.getActiveApproval());
+        }
+    }
+    publish(approval) {
+        this.events?.publish({
+            event_type: "approval.changed",
+            payload: { approval },
+            invalidates: approvalInvalidates(),
+        });
+    }
+}
+//# sourceMappingURL=manager.js.map

package/dist/approvals/projections.d.ts

@@ -0,0 +1,34 @@
+import { type ActivityRef, type TaskId } from "@tutti/shared/ids";
+import type { ApprovalRequestProjection, ApprovalResolutionOutcome } from "@tutti/shared/schemas/api";
+import type { CodexAppServerJsonRpcError, CodexAppServerJsonRpcServerRequest } from "../providers/openai/app-server/json-rpc.js";
+export type ApprovalAppServerResponse = {
+    kind: "result";
+    result: unknown;
+} | {
+    kind: "error";
+    error: CodexAppServerJsonRpcError;
+};
+export type ApprovalDecisionRuntime = {
+    decisionId: string;
+    label: string;
+    outcome: ApprovalResolutionOutcome;
+    response: ApprovalAppServerResponse;
+};
+export type ApprovalProjectionBuildResult = {
+    request: ApprovalRequestProjection;
+    decisions: Map<string, ApprovalDecisionRuntime>;
+};
+export type ApprovalProjectionContext = {
+    taskId?: TaskId;
+    activityRef?: ActivityRef;
+    requestedAt: string;
+    expiresAt?: string;
+    workspaceRoot?: string;
+    runWorkspaceRoot?: string;
+    codexHome?: string;
+    tuttiHome?: string;
+    builtInSkillsRoot?: string;
+    sensitiveValues?: readonly string[];
+};
+export declare function buildApprovalProjection(request: CodexAppServerJsonRpcServerRequest, context: ApprovalProjectionContext): ApprovalProjectionBuildResult | null;
+//# sourceMappingURL=projections.d.ts.map