@roll-agent/core 0.17.0 → 0.19.0

package/dist/config/application-service.d.ts

@@ -0,0 +1,90 @@
+import { YamlConfigDocumentStore, type ConfigPatch, type ConfigPath, type ConfigRevision } from "./document-store.ts";
+import { type LoadConfigOptions } from "./loader.ts";
+export declare const CONFIG_UI_SECRET_SENTINEL: "__ROLL_UI_KEEP_EXISTING_SECRET__";
+export declare const CONFIG_ACTIVATION_KINDS: readonly ["next-command", "next-chat", "restart-agent", "manual"];
+export type ConfigActivationKind = (typeof CONFIG_ACTIVATION_KINDS)[number];
+export interface ConfigActivationEffect {
+    readonly kind: ConfigActivationKind;
+    readonly paths: readonly ConfigPath[];
+    readonly title: string;
+    readonly description: string;
+    readonly agentName?: string;
+    readonly requiresConfirmation: boolean;
+}
+export interface ConfigValidationIssue {
+    readonly path: string;
+    readonly message: string;
+}
+export interface ConfigDiffLine {
+    readonly kind: "context" | "add" | "remove";
+    readonly text: string;
+}
+export interface ConfigApplicationSnapshot {
+    readonly configPath: string;
+    readonly existed: boolean;
+    readonly revision: ConfigRevision;
+    readonly persisted: Readonly<Record<string, unknown>>;
+    readonly yaml: string;
+    readonly configuredSecretPaths: readonly ConfigPath[];
+}
+export interface ConfigApplicationPreview {
+    readonly snapshot: ConfigApplicationSnapshot;
+    readonly changed: boolean;
+    readonly changedPaths: readonly ConfigPath[];
+    readonly effects: readonly ConfigActivationEffect[];
+    readonly diff: readonly ConfigDiffLine[];
+}
+export interface ConfigApplicationSaveResult extends ConfigApplicationPreview {
+    readonly backupPath?: string;
+}
+export interface ConfigApplicationRecoverySaveResult {
+    readonly snapshot: ConfigApplicationSnapshot;
+    readonly changed: boolean;
+    readonly backupPath?: string;
+}
+export interface ConfigApplicationServiceOptions extends LoadConfigOptions {
+    /** Extra Agent env names declared as secret in their env.yaml contract. */
+    readonly secretEnvNames?: readonly string[];
+    /** Exact Agent env visibility derived from registered env.yaml declarations. */
+    readonly agentEnvFields?: readonly ConfigAgentEnvFieldPolicy[];
+    /** Fail closed for undeclared Agent env fields, including newly added candidate values. */
+    readonly redactUnknownAgentEnv?: boolean;
+}
+export interface ConfigAgentEnvFieldPolicy {
+    readonly agentName: string;
+    readonly name: string;
+    readonly secret: boolean;
+}
+export declare class ConfigApplicationValidationError extends Error {
+    readonly code: "config_validation_failed";
+    readonly issues: readonly ConfigValidationIssue[];
+    constructor(error: unknown);
+}
+export declare class ConfigApplicationService {
+    readonly configPath: string;
+    readonly store: YamlConfigDocumentStore;
+    private readonly isSecretPath;
+    constructor(options?: ConfigApplicationServiceOptions);
+    read(): ConfigApplicationSnapshot;
+    /** Load syntactically valid persisted data so a focused CLI setup can repair schema errors. */
+    readForRepair(): ConfigApplicationSnapshot;
+    previewPatches(patches: readonly ConfigPatch[], expectedRevision?: ConfigRevision): ConfigApplicationPreview;
+    savePatches(patches: readonly ConfigPatch[], expectedRevision?: ConfigRevision): ConfigApplicationSaveResult;
+    previewStructured(persisted: unknown, expectedRevision?: ConfigRevision): ConfigApplicationPreview;
+    saveStructured(persisted: unknown, expectedRevision?: ConfigRevision): ConfigApplicationSaveResult;
+    previewYaml(yaml: string, expectedRevision?: ConfigRevision): ConfigApplicationPreview;
+    saveYaml(yaml: string, expectedRevision?: ConfigRevision): ConfigApplicationSaveResult;
+    /**
+     * Recover an invalid existing file during an explicitly confirmed `roll config init` overwrite.
+     * The generated candidate is fully validated, but the old document is never parsed or returned
+     * to a browser. UI and ordinary CLI edits must continue to use preview/save methods above.
+     */
+    replaceYamlForInit(yaml: string, expectedRevision: ConfigRevision): ConfigApplicationRecoverySaveResult;
+    private preparePatches;
+    private prepareStructured;
+    private prepareYaml;
+    private prepareDocumentPreview;
+    private commitPrepared;
+}
+export declare function planConfigActivation(changedPaths: readonly ConfigPath[]): readonly ConfigActivationEffect[];
+export declare function createConfigPatches(before: unknown, after: unknown, path?: ConfigPath): readonly ConfigPatch[];

package/dist/config/application-service.js

@@ -0,0 +1 @@
+import{homedir as t}from"node:os";import{resolve as e}from"node:path";import{stringify as r}from"yaml";import{DEFAULT_CONFIG as n}from"./defaults.js";import{ConfigRevisionConflictError as i,YamlConfigDocumentStore as o,applyPatchesToYamlText as s}from"./document-store.js";import{CONFIG_KEY_CODEC as a,decodeFromYaml as c,encodePathToYaml as p,encodeToYaml as h,kebabToCamel as u}from"./key-codec.js";import{parseConfigDocument as f,resolveConfigPath as l,validateConfigText as d}from"./loader.js";import{detectKnownConfigMigrations as g,formatConfigMigrationError as m}from"./migration.js";import{isRollConfigSecretPath as w,isSecretConfigValue as v}from"./secret-policy.js";export const CONFIG_UI_SECRET_SENTINEL="__ROLL_UI_KEEP_EXISTING_SECRET__";export const CONFIG_ACTIVATION_KINDS=["next-command","next-chat","restart-agent","manual"];export class ConfigApplicationValidationError extends Error{code="config_validation_failed";issues;constructor(t){const e=t instanceof Error?t:new Error(String(t));super(e.message,{cause:e}),this.name="ConfigApplicationValidationError",this.issues=D(e.message)}}export class ConfigApplicationService{configPath;store;isSecretPath;constructor(r={}){this.configPath=l(r)??e(t(),"roll.config.yaml"),this.store=new o(this.configPath,Y());const n=new Set(r.secretEnvNames??[]),i=new Map((r.agentEnvFields??[]).map(t=>[F(t.agentName,t.name),t.secret]));this.isSecretPath=t=>V(t,n,i,r.redactUnknownAgentEnv??!1)}read(){const t=this.store.read();return y(t.raw,t.configPath),P(t,this.isSecretPath)}readForRepair(){const t=this.store.read(),e=f(t.raw,t.configPath),r=g(e);if(r.needsMigration)throw new ConfigApplicationValidationError(new Error(m(t.configPath,r)));return P(t,this.isSecretPath)}previewPatches(t,e){return this.preparePatches(t,e).publicPreview}savePatches(t,e){return this.commitPrepared(this.preparePatches(t,e))}previewStructured(t,e){return this.prepareStructured(t,e).publicPreview}saveStructured(t,e){return this.commitPrepared(this.prepareStructured(t,e))}previewYaml(t,e){return this.prepareYaml(t,e).publicPreview}saveYaml(t,e){return this.commitPrepared(this.prepareYaml(t,e))}replaceYamlForInit(t,e){y(t,this.configPath);const r=this.store.replaceRawForRecovery(t,e);return{snapshot:P(r,this.isSecretPath),changed:r.changed,...void 0!==r.backupPath?{backupPath:r.backupPath}:{}}}preparePatches(t,e){const r=t.map(S),n=this.store.previewPatches(r,e);return this.prepareDocumentPreview(n)}prepareStructured(t,e){if(!M(t))throw new ConfigApplicationValidationError(new Error("配置内容必须是一个 JSON/YAML object。"));const r=this.store.read();if(void 0!==e&&e!==r.revision)throw new i(e,r.revision);const n=O(t,A(r.persisted),[],this.isSecretPath),o=h(n);if(!M(o))throw new ConfigApplicationValidationError(new Error("编码后的配置必须是 object。"));const s=this.store.previewObject(o,r.revision);return this.prepareDocumentPreview(s)}prepareYaml(t,e){const r=this.store.read();if(void 0!==e&&e!==r.revision)throw new i(e,r.revision);let n,o=t;try{n=f(o,this.configPath)}catch(t){throw new ConfigApplicationValidationError(t)}const c=[];let p;j(n,A(r.persisted),[],[],c,this.isSecretPath,a),c.length>0&&(o=s(o,this.configPath,c));try{p=this.store.previewRaw(o,r.revision)}catch(t){throw new ConfigApplicationValidationError(t)}return this.prepareDocumentPreview(p)}prepareDocumentPreview(t){y(t.raw,this.configPath);const e=_(A(f(t.previousRaw,this.configPath)),A(t.persisted)),r=P(t,this.isSecretPath),n=f(t.previousRaw,this.configPath),i=P({configPath:t.configPath,existed:t.existed,raw:t.previousRaw,revision:t.previousRevision,persisted:n},this.isSecretPath);return{documentPreview:t,publicPreview:{snapshot:r,changed:t.changed,changedPaths:e,effects:planConfigActivation(e),diff:U(i.yaml,r.yaml)}}}commitPrepared(t){const e=this.store.commit(t.documentPreview,{backup:!0}),r=P(e,this.isSecretPath);return{...t.publicPreview,snapshot:r,...void 0!==e.backupPath?{backupPath:e.backupPath}:{}}}}export function planConfigActivation(t){const e=new Map;for(const r of t){const t=E(r),n=`${t.kind}:${t.agentName??""}:${t.title}`,i=e.get(n);void 0!==i?i.paths.push(r):e.set(n,{...t,paths:[r]})}return[...e.values()].map(t=>({...t,paths:t.paths}))}export function createConfigPatches(t,e,r=[]){if(M(t)&&M(e)){const n=[],i=new Set([...Object.keys(t),...Object.keys(e)]);for(const o of i)o in e?o in t?n.push(...createConfigPatches(t[o],e[o],[...r,o])):n.push({op:"set",path:[...r,o],value:e[o]}):n.push({op:"delete",path:[...r,o]});return n}if(q(t,e))return[];if(0===r.length)throw new ConfigApplicationValidationError(new Error("配置根节点必须保持为 object。"));return[{op:"set",path:r,value:e}]}function E(t){const[e,r,n]=t;return"agents"===e&&"dataDir"===r?{kind:"manual",title:"Agent 数据目录需要人工迁移",description:"保存不会搬迁旧 PID、日志或注册数据；请先停止 Agent，再人工迁移目录。",requiresConfirmation:!0}:"agents"===e&&"env"===r&&"string"==typeof n?{kind:"restart-agent",title:`重启 ${n}`,description:"运行中的 core-managed Agent 需要重启；已停止的 Agent 保持停止。",agentName:n,requiresConfirmation:!0}:"browser"===e?{kind:"restart-agent",title:"重启 browser-use-agent",description:"浏览器实例声明在 Agent 启动时注入；重启 Agent 后 Chrome 仍会在首次工具调用时懒启动。",agentName:"browser-use-agent",requiresConfirmation:!0}:"runtime"===e||"skills"===e?{kind:"next-chat",title:"新会话生效",description:"当前 roll chat 会话保持原配置，新会话会重新加载。",requiresConfirmation:!1}:{kind:"next-command",title:"后续命令生效",description:"后续 Roll 命令会重新加载该配置。",requiresConfirmation:!1}}function P(t,e){const r=A(t.persisted),n=N(t.persisted,[],[],e,a),i=n.map(t=>t.path),o=new Set(i.map(L)),c=I(r,[],o);if(!M(c))throw new ConfigApplicationValidationError(new Error("脱敏后的配置必须是 object。"));const p=n.filter(t=>{const e=G(r,t.path);return!("string"==typeof e&&$(e))}).map(t=>({op:"set",path:t.persistedPath,value:CONFIG_UI_SECRET_SENTINEL})),h=0===p.length?t.raw:s(t.raw,t.configPath,p);return{configPath:t.configPath,existed:t.existed,revision:t.revision,persisted:c,yaml:h,configuredSecretPaths:i}}function y(t,e){try{d(t,e)}catch(t){throw new ConfigApplicationValidationError(t)}}function A(t){const e=c(t);if(!M(e))throw new ConfigApplicationValidationError(new Error("持久化配置必须是 object。"));return e}function S(t){const e=C(t.path);return"set"===t.op?{op:"set",path:e,value:k(t.value,t.path)}:{op:"delete",path:e}}function C(t){return p(t.map(String)).map((e,r)=>"number"==typeof t[r]?t[r]:e)}function k(t,e){if(!M(t)&&!Array.isArray(t))return t;const r=b({},e,t),n=h(r);return M(n)?G(n,C(e)):t}function b(t,e,r){let n=t;for(const[t,i]of e.entries()){const o=String(i);if(t===e.length-1){n[o]=r;break}const s={};n[o]=s,n=s}return t}function _(t,e,r=[]){const n=[],i=new Set([...Object.keys(t),...Object.keys(e)]);for(const o of i){const i=t[o],s=e[o],a=[...r,o];M(i)||M(s)?n.push(..._(M(i)?i:{},M(s)?s:{},a)):q(i,s)||n.push(a)}return n}function N(t,e,r,n,i){const o=[];if(Array.isArray(t)){const s="array"===i?.kind?i.item:i;return t.forEach((t,i)=>{const a=[...e,i],c=[...r,i],p=R(t,s);v(a,p,n)?o.push({path:a,persistedPath:c}):(Array.isArray(t)||M(t))&&o.push(...N(t,a,c,n,s))}),o}if(!M(t))return o;for(const[s,a]of Object.entries(t)){const t=x(s,a,i),c=[...e,t.key],p=[...r,s];v(c,t.value,n)?o.push({path:c,persistedPath:p}):(Array.isArray(a)||M(a))&&o.push(...N(a,c,p,n,t.node))}return o}function I(t,e,r){return r.has(L(e))?"string"==typeof t&&$(t)?t:CONFIG_UI_SECRET_SENTINEL:"string"==typeof t?t:Array.isArray(t)?t.map((t,n)=>I(t,[...e,n],r)):M(t)?Object.fromEntries(Object.entries(t).map(([t,n])=>[t,I(n,[...e,t],r)])):t}function O(t,e,r,n){if(t===CONFIG_UI_SECRET_SENTINEL)return T(e,r,n),e;if(Array.isArray(t)){const i=Array.isArray(e)?e:[];return t.map((t,e)=>O(t,i[e],[...r,e],n))}if(!M(t))return t;const i=M(e)?e:{};return Object.fromEntries(Object.entries(t).map(([t,e])=>[t,O(e,i[t],[...r,t],n)]))}function j(t,e,r,n,i,o,s){if(Array.isArray(t)){const a="array"===s?.kind?s.item:s;return void t.forEach((t,s)=>{const c=[...r,s],p=[...n,s],h=G(e,c);if(t===CONFIG_UI_SECRET_SENTINEL)return T(h,c,o),void i.push({op:"set",path:p,value:h});j(t,e,c,p,i,o,a)})}if(M(t))for(const[a,c]of Object.entries(t)){const t=x(a,c,s),p=[...r,t.key],h=[...n,a],u=G(e,p);c!==CONFIG_UI_SECRET_SENTINEL?j(c,e,p,h,i,o,t.node):(T(u,p,o),i.push({op:"set",path:h,value:u}))}}function x(t,e,r){if("object"===r?.kind){const n=u(t),i=r.fields[n];return{key:n,value:R(e,i),node:i}}return"record"===r?.kind?{key:t,value:R(e,r.value),node:r.value}:{key:t,value:e,node:void 0}}function R(t,e){return void 0===e||"leaf"===e.kind?t:c(t,e)}function T(t,e,r){if(void 0===t||t===CONFIG_UI_SECRET_SENTINEL||!v(e,t,r))throw new ConfigApplicationValidationError(new Error(`无法在原路径恢复敏感配置: ${K(e)}`))}function V(t,e=new Set,r=new Map,n=!1){if(w(t))return!0;if(4===t.length&&"agents"===t[0]&&"env"===t[1]){const i=t[2],o=t[3];if("string"!=typeof i||"string"!=typeof o)return!1;const s=F(i,o);return r.has(s)?!0===r.get(s):!(!e.has(o)&&!n)||(/(?:^|_)(?:TOKEN|API_KEY|SECRET|PASSWORD|PRIVATE_KEY)(?:_|$)/u.test(o)||o.endsWith("_WEBHOOK"))}return!1}function F(t,e){return`${t}\0${e}`}function $(t){return/^\$\{[^{}]+\}$/u.test(t)}function L(t){return JSON.stringify(t)}function G(t,e){let r=t;for(const t of e)if(Array.isArray(r)&&"number"==typeof t)r=r[t];else{if(!M(r))return;r=r[String(t)]}return r}function U(t,e){if(t===e)return t.split("\n").map(t=>({kind:"context",text:t}));const r=t.split("\n"),n=e.split("\n");let i=0;for(;i<r.length&&i<n.length&&r[i]===n[i];)i+=1;let o=0;for(;o<r.length-i&&o<n.length-i&&r[r.length-o-1]===n[n.length-o-1];)o+=1;return[...r.slice(0,i).map(t=>({kind:"context",text:t})),...r.slice(i,r.length-o).map(t=>({kind:"remove",text:t})),...n.slice(i,n.length-o).map(t=>({kind:"add",text:t})),...r.slice(r.length-o).map(t=>({kind:"context",text:t}))]}function Y(){const t={llm:n.llm,ask:n.ask,agents:n.agents};return r(h(t),{lineWidth:0})}function D(t){const e=t.split("\n").map(t=>t.match(/^\s*-\s+([^:]+):\s*(.+)$/u)).filter(t=>null!==t).map(e=>({path:e[1]??"",message:e[2]??t}));return e.length>0?e:[{path:"",message:t}]}function K(t){return t.map(String).join(" / ")}function q(t,e){if(Object.is(t,e))return!0;if(Array.isArray(t)&&Array.isArray(e))return t.length===e.length&&t.every((t,r)=>q(t,e[r]));if(!M(t)||!M(e))return!1;const r=Object.keys(t),n=Object.keys(e);return r.length===n.length&&r.every(r=>r in e&&q(t[r],e[r]))}function M(t){return"object"==typeof t&&null!==t&&!Array.isArray(t)}

package/dist/config/catalog.d.ts

@@ -0,0 +1,76 @@
+import type { RegisteredAgent } from "../types/agent.ts";
+export declare const CONFIG_CATALOG_NODE_KINDS: readonly ["object", "record", "array", "string", "number", "boolean", "enum", "unknown"];
+export type ConfigCatalogNodeKind = (typeof CONFIG_CATALOG_NODE_KINDS)[number];
+export declare const CONFIG_FIELD_WIDGETS: readonly ["text", "password", "url", "path", "textarea", "number", "duration", "switch", "select", "string-list", "record", "object"];
+export type ConfigFieldWidget = (typeof CONFIG_FIELD_WIDGETS)[number];
+interface ConfigCatalogNodeBase {
+    readonly kind: ConfigCatalogNodeKind;
+    readonly path: readonly string[];
+    readonly title: string;
+    readonly description?: string;
+    readonly defaultBehavior?: string;
+    readonly example?: string;
+    readonly setupCommand?: string;
+    readonly effectiveRequired: boolean;
+    readonly persistedRequired: boolean;
+    readonly defaultValue?: unknown;
+    readonly widget: ConfigFieldWidget;
+    readonly secret: boolean;
+}
+export interface ConfigNumberConstraints {
+    readonly minimum?: number;
+    readonly maximum?: number;
+    readonly exclusiveMinimum: boolean;
+    readonly exclusiveMaximum: boolean;
+    readonly integer: boolean;
+}
+export interface ConfigObjectCatalogNode extends ConfigCatalogNodeBase {
+    readonly kind: "object";
+    readonly fields: Readonly<Record<string, ConfigCatalogNode>>;
+}
+export interface ConfigRecordCatalogNode extends ConfigCatalogNodeBase {
+    readonly kind: "record";
+    readonly value: ConfigCatalogNode;
+}
+export interface ConfigArrayCatalogNode extends ConfigCatalogNodeBase {
+    readonly kind: "array";
+    readonly item: ConfigCatalogNode;
+}
+export interface ConfigEnumCatalogNode extends ConfigCatalogNodeBase {
+    readonly kind: "enum";
+    readonly options: readonly string[];
+}
+export interface ConfigLeafCatalogNode extends ConfigCatalogNodeBase {
+    readonly kind: "string" | "boolean" | "unknown";
+}
+export interface ConfigNumberCatalogNode extends ConfigCatalogNodeBase {
+    readonly kind: "number";
+    readonly constraints: ConfigNumberConstraints;
+}
+export type ConfigCatalogNode = ConfigObjectCatalogNode | ConfigRecordCatalogNode | ConfigArrayCatalogNode | ConfigEnumCatalogNode | ConfigNumberCatalogNode | ConfigLeafCatalogNode;
+export interface AgentEnvCatalogField {
+    readonly name: string;
+    readonly title: string;
+    readonly description?: string;
+    readonly example?: string;
+    readonly defaultValue?: string;
+    readonly required: boolean;
+    readonly type: "string" | "boolean" | "number" | "json" | "url";
+    readonly widget: "text" | "password" | "url" | "number" | "switch" | "textarea";
+    readonly secret: boolean;
+    readonly configurable: boolean;
+    readonly sourcePath?: readonly string[];
+}
+export interface AgentConfigCatalog {
+    readonly name: string;
+    readonly description: string;
+    readonly ownership: RegisteredAgent["runtime"]["ownership"];
+    readonly fields: readonly AgentEnvCatalogField[];
+}
+export interface RollConfigCatalog {
+    readonly schemaVersion: 1;
+    readonly root: ConfigObjectCatalogNode;
+    readonly agents: readonly AgentConfigCatalog[];
+}
+export declare function buildRollConfigCatalog(agents?: readonly RegisteredAgent[]): RollConfigCatalog;
+export {};

package/dist/config/catalog.js

@@ -0,0 +1 @@
+import{z as e}from"zod";import{listConfigGuidanceEntries as t}from"./guidance.js";import{DEFAULT_CONFIG as n}from"./defaults.js";import{normalizeUserPath as i}from"./key-codec.js";import{rollConfigSchema as o}from"./schema.js";import{isRollConfigSecretPath as r}from"./secret-policy.js";export const CONFIG_CATALOG_NODE_KINDS=["object","record","array","string","number","boolean","enum","unknown"];export const CONFIG_FIELD_WIDGETS=["text","password","url","path","textarea","number","duration","switch","select","string-list","record","object"];export function buildRollConfigCatalog(e=[]){const t=a(o,[],n);if("object"!==t.kind)throw new Error("rollConfigSchema root must be an object");return{schemaVersion:1,root:t,agents:e.map(l)}}function a(t,n,i){const o=!t.safeParse(void 0).success,r=d(t),c=v(n),l=u(t,n,i,o,c);if(r instanceof e.ZodObject){const t=b(i)?i:{},o=Object.fromEntries(Object.entries(r.shape).map(([i,o])=>{if(!(o instanceof e.ZodType))throw new Error(`Unsupported Zod object field at ${[...n,i].join(".")}`);return[i,a(o,[...n,i],t[i])]}));return{...l,kind:"object",widget:"object",fields:o}}return r instanceof e.ZodRecord?{...l,kind:"record",widget:"record",value:a(r.valueSchema,[...n,"*"],void 0)}:r instanceof e.ZodArray?{...l,kind:"array",widget:r.element instanceof e.ZodString?"string-list":"object",item:a(r.element,[...n,"*"],void 0)}:r instanceof e.ZodEnum?{...l,kind:"enum",widget:"select",options:r.options}:r instanceof e.ZodString?{...l,kind:"string",widget:p(n)}:r instanceof e.ZodNumber?{...l,kind:"number",widget:!0===n.at(-1)?.endsWith("Ms")?"duration":"number",constraints:s(r)}:r instanceof e.ZodBoolean?{...l,kind:"boolean",widget:"switch"}:{...l,kind:"unknown",widget:"textarea"}}function s(e){let t,n;for(const i of e._def.checks)"min"!==i.kind?"max"===i.kind&&(void 0===n||i.value<n.value||i.value===n.value&&!i.inclusive)&&(n={value:i.value,exclusive:!i.inclusive}):(void 0===t||i.value>t.value||i.value===t.value&&!i.inclusive)&&(t={value:i.value,exclusive:!i.inclusive});return{...void 0!==t?{minimum:t.value}:{},...void 0!==n?{maximum:n.value}:{},exclusiveMinimum:t?.exclusive??!1,exclusiveMaximum:n?.exclusive??!1,integer:e.isInt}}function u(e,t,n,i,o){const a=void 0!==n?{defaultValue:n}:c(e);return{kind:"unknown",path:t,title:o?.title??g(t.at(-1)??"Roll configuration"),...void 0!==o?.purpose?{description:o.purpose}:{},...void 0!==o?.defaultBehavior?{defaultBehavior:o.defaultBehavior}:{},...void 0!==o?.example?{example:o.example}:{},...void 0!==o?.setupCommand?{setupCommand:o.setupCommand}:{},effectiveRequired:i,persistedRequired:i&&!("defaultValue"in a),...a,widget:"text",secret:r(t)}}function c(e){const t=e.safeParse(void 0);return t.success&&void 0!==t.data?{defaultValue:t.data}:{}}function d(t){return t instanceof e.ZodOptional||t instanceof e.ZodNullable?d(t.unwrap()):t instanceof e.ZodDefault?d(t.removeDefault()):t instanceof e.ZodEffects?d(t.innerType()):t instanceof e.ZodCatch?d(t.removeCatch()):t instanceof e.ZodBranded?d(t.unwrap()):t}function l(e){const t=new Set((e.skill.env?.required??[]).map(e=>e.name)),n=[...e.skill.env?.required??[],...e.skill.env?.optional??[]];return{name:e.skill.name,description:e.skill.description,ownership:e.runtime.ownership,fields:n.map(e=>{const n=e.type??m(e.name),i=e.secret??!0,o=e.configurable??"BROWSER_INSTANCES_JSON"!==e.name,r=e.sourcePath??("BROWSER_INSTANCES_JSON"===e.name?["browser","instances"]:void 0);return{name:e.name,title:w(e.name),...void 0!==e.purpose?{description:e.purpose}:{},...void 0!==e.example?{example:e.example}:{},...void 0!==e.default?{defaultValue:e.default}:{},required:t.has(e.name),type:n,widget:f(n,i),secret:i,configurable:o,...void 0!==r?{sourcePath:r}:{}}})}}function m(e){return e.endsWith("_JSON")?"json":e.endsWith("_ENABLED")||e.startsWith("ENABLE_")?"boolean":e.endsWith("_MS")||e.endsWith("_TIMEOUT")?"number":e.endsWith("_URL")||e.endsWith("_URI")?"url":"string"}function f(e,t){if(t)return"password";switch(e){case"boolean":return"switch";case"number":return"number";case"json":return"textarea";case"url":return"url";case"string":return"text"}}function p(e){if(r(e))return"password";const t=e.at(-1)??"";return/(?:Url|Uri)$/u.test(t)?"url":/(?:Dir|Path)$/u.test(t)?"path":"text"}function v(e){return t().find(t=>{const n=h(t.path);return n.length===e.length&&n.every((t,n)=>"*"===t||t===e[n])})}function h(e){const t=e.split(".");return i(t).map(e=>e.startsWith("<")&&e.endsWith(">")?"*":e)}function g(e){return e.replace(/([a-z0-9])([A-Z])/gu,"$1 $2").replace(/[-_]/gu," ").replace(/^./u,e=>e.toUpperCase())}function w(e){return e.toLowerCase().split("_").map(e=>e.charAt(0).toUpperCase()+e.slice(1)).join(" ")}function b(e){return"object"==typeof e&&null!==e&&!Array.isArray(e)}

package/dist/config/defaults.d.ts

@@ -1,4 +1,4 @@
-import type { RollConfig } from "./schema.ts";
+import { type RollConfig } from "./schema.ts";
 export declare const LLM_PROVIDER_OPTIONS: readonly ["anthropic", "openai", "qwen", "deepseek"];
 export type LlmProviderOption = (typeof LLM_PROVIDER_OPTIONS)[number];
 export declare const DEFAULT_LLM_PROVIDER: LlmProviderOption;
@@ -8,7 +8,7 @@ export declare const DEFAULT_LLM_MODELS: {
     readonly qwen: "qwen3.6-plus";
     readonly deepseek: "deepseek-v4-flash";
 };
-/** 默认配置值 */
+/** 默认配置值；除上述必填 seed 外，全部由 rollConfigSchema 的默认值生成。 */
 export declare const DEFAULT_CONFIG: RollConfig;
 /** 配置文件查找顺序 */
 export declare const CONFIG_FILE_NAMES: readonly ["roll.config.yaml", "roll.config.yml"];

package/dist/config/defaults.js

@@ -1 +1 @@
-export const LLM_PROVIDER_OPTIONS=["anthropic","openai","qwen","deepseek"];export const DEFAULT_LLM_PROVIDER="anthropic";export const DEFAULT_LLM_MODELS={anthropic:"claude-sonnet-4-6",openai:"gpt-5.5",qwen:"qwen3.6-plus",deepseek:"deepseek-v4-flash"};export const DEFAULT_CONFIG={llm:{defaultProvider:"anthropic",defaultModel:DEFAULT_LLM_MODELS.anthropic,providers:{}},ask:{},runtime:{maxSteps:80,turnTimeoutMs:3e5,threadsDir:"~/.roll-agent/threads",thinkingLevel:"medium",approval:{default:"guarded",overrides:{}},compaction:{enabled:!0,strategy:"summarize",threshold:.75,keepRecentTurns:4,keepRecentTokens:32e3},shell:{enabled:!1,autoApproveSafe:!0,defaultTimeoutMs:1e4,maxTimeoutMs:6e5,maxCaptureBytes:1048576,maxModelOutputChars:16e3,session:{enabled:!1,maxSessions:8,defaultYieldMs:1e4,maxOutputTokens:1e4}}},skills:{dirs:[]},agents:{dataDir:"~/.roll-agent/agents"},install:{fetchRetries:3,preferOffline:!1,networkTimeoutMs:12e4},browser:{instances:{}}};export const CONFIG_FILE_NAMES=["roll.config.yaml","roll.config.yml"];
+import{rollConfigSchema as e}from"./schema.js";export const LLM_PROVIDER_OPTIONS=["anthropic","openai","qwen","deepseek"];export const DEFAULT_LLM_PROVIDER="anthropic";export const DEFAULT_LLM_MODELS={anthropic:"claude-sonnet-4-6",openai:"gpt-5.5",qwen:"qwen3.6-plus",deepseek:"deepseek-v4-flash"};const o={llm:{defaultProvider:"anthropic",defaultModel:DEFAULT_LLM_MODELS.anthropic,providers:{}},ask:{},agents:{dataDir:"~/.roll-agent/agents"}};export const DEFAULT_CONFIG=e.parse(o);export const CONFIG_FILE_NAMES=["roll.config.yaml","roll.config.yml"];

package/dist/config/document-store.d.ts

@@ -0,0 +1,70 @@
+declare const CONFIG_REVISION_BRAND: unique symbol;
+export type ConfigRevision = string & {
+    readonly [CONFIG_REVISION_BRAND]: true;
+};
+export type ConfigPath = readonly (string | number)[];
+export type ConfigPatch = {
+    readonly op: "set";
+    readonly path: ConfigPath;
+    readonly value: unknown;
+} | {
+    readonly op: "delete";
+    readonly path: ConfigPath;
+};
+export interface ConfigDocumentSnapshot {
+    readonly configPath: string;
+    readonly existed: boolean;
+    readonly raw: string;
+    readonly revision: ConfigRevision;
+    readonly persisted: Readonly<Record<string, unknown>>;
+}
+export interface ConfigDocumentPreview extends ConfigDocumentSnapshot {
+    readonly previousRaw: string;
+    readonly previousRevision: ConfigRevision;
+    readonly changed: boolean;
+}
+export interface ConfigDocumentWriteResult extends ConfigDocumentPreview {
+    readonly backupPath?: string;
+}
+export interface ConfigDocumentRecoveryWriteResult extends ConfigDocumentSnapshot {
+    readonly previousRaw: string;
+    readonly previousRevision: ConfigRevision;
+    readonly changed: boolean;
+    readonly backupPath?: string;
+}
+export declare class ConfigRevisionConflictError extends Error {
+    readonly code: "config_revision_conflict";
+    readonly expectedRevision: ConfigRevision;
+    readonly actualRevision: ConfigRevision;
+    constructor(expectedRevision: ConfigRevision, actualRevision: ConfigRevision);
+}
+export declare class ConfigWriteLockError extends Error {
+    readonly code: "config_write_locked";
+    constructor();
+}
+export declare class ConfigDocumentParseError extends Error {
+    readonly code: "config_document_parse_error";
+    constructor(configPath: string, message: string, cause?: Error);
+}
+export declare function createConfigRevision(raw: string): ConfigRevision;
+export declare class YamlConfigDocumentStore {
+    readonly configPath: string;
+    readonly fallbackRaw: string;
+    constructor(configPath: string, fallbackRaw: string);
+    read(): ConfigDocumentSnapshot;
+    previewPatches(patches: readonly ConfigPatch[], expectedRevision?: ConfigRevision): ConfigDocumentPreview;
+    previewObject(persisted: Readonly<Record<string, unknown>>, expectedRevision?: ConfigRevision): ConfigDocumentPreview;
+    previewRaw(raw: string, expectedRevision?: ConfigRevision): ConfigDocumentPreview;
+    commit(preview: ConfigDocumentPreview, options?: {
+        readonly backup?: boolean;
+    }): ConfigDocumentWriteResult;
+    /**
+     * Replace an existing, potentially unparseable document after an upper layer has validated the
+     * candidate. This intentionally bypasses read()/preview so `roll config init` can recover a
+     * malformed file after explicit confirmation; ordinary CLI/UI writes must keep using commit().
+     */
+    replaceRawForRecovery(raw: string, expectedRevision: ConfigRevision): ConfigDocumentRecoveryWriteResult;
+    private readRawSnapshot;
+}
+export declare function applyPatchesToYamlText(raw: string, configPath: string, patches: readonly ConfigPatch[]): string;
+export {};

package/dist/config/document-store.js

@@ -0,0 +1 @@
+import{createHash as e,randomUUID as t}from"node:crypto";import{closeSync as r,existsSync as i,fsyncSync as o,lstatSync as n,mkdirSync as s,openSync as c,readFileSync as a,realpathSync as f,renameSync as u,statSync as h,unlinkSync as d,writeFileSync as p}from"node:fs";import{basename as l,dirname as g,resolve as v}from"node:path";import{parseDocument as w}from"yaml";import{isProcessStartToken as m,readProcessStartToken as y}from"../registry/process-identity.js";const R=Symbol("ConfigRevision"),P=3e5;export class ConfigRevisionConflictError extends Error{code="config_revision_conflict";expectedRevision;actualRevision;constructor(e,t){super("配置文件已被其他进程修改，请刷新后重试。"),this.name="ConfigRevisionConflictError",this.expectedRevision=e,this.actualRevision=t}}export class ConfigWriteLockError extends Error{code="config_write_locked";constructor(){super("配置正在由另一个 Roll 进程写入，请稍后刷新并重试。"),this.name="ConfigWriteLockError"}}export class ConfigDocumentParseError extends Error{code="config_document_parse_error";constructor(e,t,r){super(`Invalid YAML syntax in config file: ${e}\n${t}`,{...void 0!==r?{cause:r}:{}}),this.name="ConfigDocumentParseError"}}export function createConfigRevision(t){return e("sha256").update(t).digest("hex")}export class YamlConfigDocumentStore{configPath;fallbackRaw;constructor(e,t){this.configPath=v(e),this.fallbackRaw=t}read(){const e=i(this.configPath),t=e?a(this.configPath,"utf-8"):this.fallbackRaw,r=b(t,this.configPath);return{configPath:this.configPath,existed:e,raw:t,revision:createConfigRevision(t),persisted:r}}previewPatches(e,t){const r=this.read();return x(r.revision,t),k(r,applyPatchesToYamlText(r.raw,this.configPath,e))}previewObject(e,t){const r=this.read();x(r.revision,t);const i=C(r.raw,this.configPath);return E(i,r.persisted,e,[]),k(r,i.toString({lineWidth:0}))}previewRaw(e,t){const r=this.read();return x(r.revision,t),b(e,this.configPath),k(r,A(e))}commit(e,t={}){if(!e.changed){return x(this.read().revision,e.previousRevision),{...e}}const r=$(this.configPath),i=M(r);try{const i=this.read();x(i.revision,e.previousRevision),N(this.configPath,r,e.previousRevision);const o=!1!==t.backup&&i.existed?T(r,i.raw):void 0;return j(r,e.raw,i.existed,()=>{J(this.configPath,this.fallbackRaw,r,i.existed,i.revision)}),{...e,existed:!0,...void 0!==o?{backupPath:o}:{}}}finally{i.release()}}replaceRawForRecovery(e,t){const r=A(e),i=b(r,this.configPath),o=$(this.configPath),n=M(o);try{const e=this.readRawSnapshot();x(e.revision,t),N(this.configPath,o,t);if(!(!e.existed||r!==e.raw))return{...e,persisted:i,previousRaw:e.raw,previousRevision:e.revision,changed:!1};const n=e.existed?T(o,e.raw):void 0;return j(o,r,e.existed,()=>{J(this.configPath,this.fallbackRaw,o,e.existed,e.revision)}),{configPath:this.configPath,existed:!0,raw:r,revision:createConfigRevision(r),persisted:i,previousRaw:e.raw,previousRevision:e.revision,changed:!0,...void 0!==n?{backupPath:n}:{}}}finally{n.release()}}readRawSnapshot(){const e=i(this.configPath),t=e?a(this.configPath,"utf-8"):this.fallbackRaw;return{configPath:this.configPath,existed:e,raw:t,revision:createConfigRevision(t)}}}export function applyPatchesToYamlText(e,t,r){const i=C(e,t);for(const e of r){if(0===e.path.length)throw new Error("配置 patch 路径不能为空");switch(e.op){case"set":i.setIn([...e.path],e.value);break;case"delete":i.deleteIn([...e.path])}}return i.toString({lineWidth:0})}function k(e,t){const r=A(t);return{configPath:e.configPath,existed:e.existed,raw:r,revision:createConfigRevision(r),persisted:b(r,e.configPath),previousRaw:e.raw,previousRevision:e.revision,changed:r!==e.raw}}function x(e,t){if(void 0!==t&&t!==e)throw new ConfigRevisionConflictError(t,e)}function C(e,t){const r=w(e,{keepSourceTokens:!0,prettyErrors:!0});if(r.errors.length>0){const[e]=r.errors,i=r.errors.map(e=>e.message).join("\n");throw new ConfigDocumentParseError(t,i,e)}return r}function b(e,t){const r=C(e,t).toJS();if(!X(r))throw new ConfigDocumentParseError(t,"expected YAML object");return r}function E(e,t,r,i){for(const o of Object.keys(t))o in r||e.deleteIn([...i,o]);for(const[o,n]of Object.entries(r)){const r=t[o],s=[...i,o];X(r)&&X(n)?E(e,r,n,s):S(r,n)||e.setIn(s,n)}}function S(e,t){if(Object.is(e,t))return!0;if(Array.isArray(e)&&Array.isArray(t))return e.length===t.length&&e.every((e,r)=>S(e,t[r]));if(!X(e)||!X(t))return!1;const r=Object.keys(e),i=Object.keys(t);return r.length===i.length&&r.every(r=>r in t&&S(e[r],t[r]))}function A(e){return e.endsWith("\n")?e:`${e}\n`}function $(e){return i(e)&&n(e).isSymbolicLink()?f(e):e}function T(e,r){const o=`${e}.bak.${(new Date).toISOString().replace(/[-:]/gu,"").replace("T","-").replace("Z","").replace(".","-")}`,n=i(o)?`${o}.${t().slice(0,8)}`:o;return p(n,r,{encoding:"utf-8",flag:"wx",mode:384}),n}function j(e,n,a,f){const w=g(e);s(w,{recursive:!0});const m=a?511&h(e).mode:384,y=v(w,`.${l(e)}.${String(process.pid)}.${t()}.tmp`);let R;try{R=c(y,"wx",m),p(R,n,"utf-8"),o(R),r(R),R=void 0,f?.(),u(y,e),F(w)}catch(e){throw void 0!==R&&r(R),i(y)&&d(y),e}}function M(e){s(g(e),{recursive:!0});const r=`${e}.roll-write.lock`,i=y(process.pid);if(void 0===i)throw new Error(`无法验证当前 Roll 进程 (PID: ${String(process.pid)}) 的 OS 启动身份，拒绝获取配置写锁。`);const o={pid:process.pid,processStartToken:i,token:t(),createdAtMs:Date.now()},n=`${JSON.stringify(o)}\n`;for(let e=0;e<2;e+=1)try{p(r,n,{encoding:"utf-8",flag:"wx",mode:384});let e=!1;return{release:()=>{e||(e=!0,O(r,o.token))}}}catch(t){if(!Y(t,"EEXIST"))throw t;if(0===e&&D(r))continue;throw new ConfigWriteLockError}throw new ConfigWriteLockError}function O(e,t){try{const r=I(e);r?.token===t&&d(e)}catch{}}function D(e){let t,r;try{t=a(e,"utf-8"),r=h(e).mtimeMs}catch{return!1}const i=L(t),o=Date.now()-(i?.createdAtMs??r);if(!(void 0===i?o>P:W(i)))return!1;try{return a(e,"utf-8")===t&&(d(e),!0)}catch{return!1}}function I(e){if(i(e))return L(a(e,"utf-8"))}function L(e){let t;try{t=JSON.parse(e)}catch{return}if(X(t)&&"number"==typeof t.pid&&Number.isInteger(t.pid)&&!(t.pid<=0)&&m(t.processStartToken)&&"string"==typeof t.token&&"number"==typeof t.createdAtMs&&Number.isFinite(t.createdAtMs))return{pid:t.pid,processStartToken:t.processStartToken,token:t.token,createdAtMs:t.createdAtMs}}function W(e){if(!_(e.pid))return!0;const t=y(e.pid);return void 0!==t&&t!==e.processStartToken}function _(e){try{return process.kill(e,0),!0}catch(e){return Y(e,"EPERM")}}function Y(e,t){return e instanceof Error&&"code"in e&&e.code===t}function N(e,t,r){if($(e)!==t)throw new ConfigRevisionConflictError(r,r)}function J(e,t,r,o,n){const s=i(e),c=createConfigRevision(s?a(e,"utf-8"):t);if(s!==o||c!==n||$(e)!==r)throw new ConfigRevisionConflictError(n,c)}function F(e){if("win32"===process.platform)return;let t;try{t=c(e,"r"),o(t)}finally{void 0!==t&&r(t)}}function X(e){return"object"==typeof e&&null!==e&&!Array.isArray(e)}