@rynx-ai/plugin-channel-lark 0.1.10 → 0.1.11-beta.3

package/.rynx-plugin/plugin.json

@@ -0,0 +1,37 @@
+{
+  "schemaVersion": 1,
+  "id": "lark",
+  "version": "0.1.11",
+  "displayName": "Lark",
+  "description": "Lark and Feishu channel integration managed by the plugin.",
+  "apiRange": "^1.0.0",
+  "capabilities": [
+    "conversation.run",
+    "agent.catalog.read",
+    "runtime.catalog.read",
+    "session.cancel",
+    "session.fork",
+    "session.goal.read",
+    "session.goal.write",
+    "session.meta.read",
+    "session.meta.title.write",
+    "session.provision"
+  ],
+  "runtime": {
+    "entry": "./dist/runtime.js"
+  },
+  "channels": [
+    {
+      "id": "lark",
+      "displayName": "Lark"
+    }
+  ],
+  "settings": {
+    "ui": {
+      "entry": "./ui/index.html"
+    },
+    "background": {
+      "entry": "./dist/settings.js"
+    }
+  }
+}

package/dist/cli-mirror/mirror-index.d.ts

@@ -1,4 +1,4 @@
-import type { CodexSessionStore, ConversationSessionStore } from "@rynx-ai/core";
+import type { CodexSessionStore, ConversationSessionStore, SessionRegistry } from "@rynx-ai/core";
 import type { LarkConversationDirectory } from "../lark-conversation-directory.js";
 /**
  * Resolves a Codex thread id (the rollout-file UUID) back to the Feishu
@@ -32,10 +32,12 @@ export declare class CodexMirrorIndex {
     private readonly codexSessionStore;
     private readonly conversationSessionStore;
     private readonly conversationDirectory;
-    constructor({ codexSessionStore, conversationSessionStore, conversationDirectory, }: {
+    private readonly sessionRegistry;
+    constructor({ codexSessionStore, conversationSessionStore, conversationDirectory, sessionRegistry, }: {
         codexSessionStore: Pick<CodexSessionStore, "listAll" | "findByCodexSessionId">;
         conversationSessionStore: Pick<ConversationSessionStore, "findKeyBySessionId">;
         conversationDirectory: Pick<LarkConversationDirectory, "get">;
+        sessionRegistry: Pick<SessionRegistry, "get">;
     });
     /** codexSessionId → the full send target, or null when the thread isn't
      *  bound, its session isn't routed, or the conversation was never recorded. */

package/dist/cli-mirror/mirror-index.js

@@ -2,10 +2,12 @@ export class CodexMirrorIndex {
     codexSessionStore;
     conversationSessionStore;
     conversationDirectory;
-    constructor({ codexSessionStore, conversationSessionStore, conversationDirectory, }) {
+    sessionRegistry;
+    constructor({ codexSessionStore, conversationSessionStore, conversationDirectory, sessionRegistry, }) {
         this.codexSessionStore = codexSessionStore;
         this.conversationSessionStore = conversationSessionStore;
         this.conversationDirectory = conversationDirectory;
+        this.sessionRegistry = sessionRegistry;
     }
     /** codexSessionId → the full send target, or null when the thread isn't
      *  bound, its session isn't routed, or the conversation was never recorded. */
@@ -22,6 +24,10 @@ export class CodexMirrorIndex {
         if (!directory) {
             return null;
         }
+        const session = this.sessionRegistry.get(record.localThreadId);
+        if (!session) {
+            return null;
+        }
         return {
             codexSessionId,
             localThreadId: record.localThreadId,
@@ -29,7 +35,7 @@ export class CodexMirrorIndex {
             chatId: directory.chatId,
             threadId: directory.threadId,
             participants: directory.participants ?? [],
-            model: record.model,
+            model: session.execution.model,
         };
     }
     /** All Codex threads currently bound to a Feishu conversation (those whose

package/dist/host-adapters.d.ts

@@ -1,7 +1,14 @@
-import { type AgentCapabilities, type AgentRuntimeId, type CapabilityResult, type ConversationRuntime, type ConversationStreamRequest, type ModelListResponse, type SessionEvent, type ThreadGoal } from "@rynx-ai/core";
+import { type AgentCapabilities, type AgentRuntimeId, type CapabilityResult, type ConversationSessionRecord, type ConversationStreamRequest, type ModelListResponse, type SessionExecution, type SessionEvent, type ThreadGoal } from "@rynx-ai/core";
 import type { PluginAgentSummary, PluginHostClient, PluginResolvedSessionExecution, PluginSessionExecutionSnapshot } from "@rynx-ai/plugin-sdk";
 import { FileLarkActiveSessionStore } from "./lark-session-store.js";
-type LarkConversationRuntime = Pick<ConversationRuntime, "runLive">;
+import type { LarkConversationRuntime } from "./lark.js";
+interface HostSessionLaunchMeta {
+    sourceSessionId?: string;
+    agent?: string;
+    provider?: AgentRuntimeId;
+    model?: string;
+    reasoningEffort?: string;
+}
 /** Slow consumers fail the run instead of retaining an unbounded event stream. */
 export declare const LARK_RUN_EVENT_QUEUE_MAX_ITEMS = 256;
 export declare const LARK_RUN_EVENT_QUEUE_MAX_BYTES: number;
@@ -21,7 +28,7 @@ export declare class HostConversationRuntime implements LarkConversationRuntime
         generator: AsyncGenerator<SessionEvent, any, any>;
     }>;
 }
-/** Agent command adapter used by /models, /goal, and /fork. */
+/** Agent command adapter used by /models and /goal. Session fork is a Core RPC. */
 export declare class HostAgentCapabilities implements AgentCapabilities {
     private readonly host;
     constructor(host: PluginHostClient);
@@ -29,7 +36,6 @@ export declare class HostAgentCapabilities implements AgentCapabilities {
     getGoal(sessionId: string): Promise<CapabilityResult<ThreadGoal | null>>;
     setGoal(sessionId: string, objective: string): Promise<CapabilityResult>;
     clearGoal(sessionId: string): Promise<CapabilityResult>;
-    forkSession(fromSessionId: string, toSessionId: string): Promise<CapabilityResult>;
 }
 /** Narrow agent catalog + first-turn execution resolver backed by Host RPC. */
 export declare class HostAgentCatalog {
@@ -46,10 +52,14 @@ export declare class HostAgentCatalog {
 export declare class HostSessionProvisioner {
     private readonly host;
     readonly instanceId: string;
+    private readonly resolvedExecutions;
     constructor(host: PluginHostClient, instanceId: string);
-    provision(operationId: string): Promise<string>;
+    provision(operationId: string, session?: HostSessionLaunchMeta): Promise<string>;
+    takeExecution(sessionId: string): SessionExecution | undefined;
+    existingExecution(sessionId: string): Promise<SessionExecution | undefined>;
     allocationOperationId(sessionKey: string, previousSessionId?: string): string;
     forkOperationId(fromSessionId: string, newSessionKey: string): string;
+    fork(operationId: string, sourceSessionId: string, title?: string): Promise<string>;
     setTitle(sessionId: string, title: string): Promise<void>;
 }
 /**
@@ -61,6 +71,7 @@ export declare class HostSessionProvisioner {
 export declare class HostProvisionedLarkSessionStore extends FileLarkActiveSessionStore {
     private readonly operation;
     private mutationTail;
+    private readonly instanceDefaultAgent?;
     constructor(options: {
         filePath: string;
         provisioner: HostSessionProvisioner;
@@ -69,12 +80,14 @@ export declare class HostProvisionedLarkSessionStore extends FileLarkActiveSessi
     });
     private readonly provisioner;
     ensure(sessionKey: string): Promise<import("@rynx-ai/core").EnsureSessionResult>;
-    set(sessionKey: string, sessionId: string, cwd?: string): Promise<import("@rynx-ai/core").ConversationSessionRecord>;
+    set(sessionKey: string, sessionId: string, cwd?: string): Promise<ConversationSessionRecord>;
+    get(sessionKey: string): Promise<ConversationSessionRecord | null>;
     rotate(sessionKey: string): Promise<import("@rynx-ai/core").RotateSessionResult>;
-    bindCwd(sessionKey: string, cwd: string): Promise<import("@rynx-ai/core").ConversationSessionRecord>;
-    applySettings(sessionKey: string, settings: Parameters<FileLarkActiveSessionStore["applySettings"]>[1]): Promise<import("@rynx-ai/core").ConversationSessionRecord>;
-    setAgent(sessionKey: string, agentName: string): Promise<import("@rynx-ai/core").ConversationSessionRecord>;
-    freeze(sessionKey: string, execution: Parameters<FileLarkActiveSessionStore["freeze"]>[1]): Promise<import("@rynx-ai/core").ConversationSessionRecord>;
+    bindCwd(sessionKey: string, cwd: string): Promise<ConversationSessionRecord>;
+    applySettings(sessionKey: string, settings: Parameters<FileLarkActiveSessionStore["applySettings"]>[1]): Promise<ConversationSessionRecord>;
+    setAgent(sessionKey: string, agentName: string): Promise<ConversationSessionRecord>;
+    freeze(sessionKey: string, execution: Parameters<FileLarkActiveSessionStore["freeze"]>[1]): Promise<ConversationSessionRecord>;
+    private pinResolvedExecution;
     private withAllocation;
     private runMutation;
 }

package/dist/host-adapters.js

@@ -89,14 +89,6 @@ export class HostConversationRuntime {
             started = await this.host.call("session.run", {
                 sessionId: input.threadId,
                 message: input.message,
-                ...(input.provider ? { provider: input.provider } : {}),
-                ...(input.model ? { model: input.model } : {}),
-                ...(input.reasoningEffort ? { reasoningEffort: input.reasoningEffort } : {}),
-                ...(input.cwd ? { cwd: input.cwd } : {}),
-                ...(input.agentName ? { agent: input.agentName } : {}),
-                ...(input.developerInstructions
-                    ? { developerInstructions: input.developerInstructions }
-                    : {}),
             });
             runId = started.runId;
             if (earlyOverflow) {
@@ -142,7 +134,7 @@ export class HostConversationRuntime {
         };
     }
 }
-/** Agent command adapter used by /models, /goal, and /fork. */
+/** Agent command adapter used by /models and /goal. Session fork is a Core RPC. */
 export class HostAgentCapabilities {
     host;
     constructor(host) {
@@ -160,9 +152,6 @@ export class HostAgentCapabilities {
     clearGoal(sessionId) {
         return this.host.call("session.goal.clear", { sessionId });
     }
-    forkSession(fromSessionId, toSessionId) {
-        return this.host.call("session.fork", { fromSessionId, toSessionId });
-    }
 }
 /** Narrow agent catalog + first-turn execution resolver backed by Host RPC. */
 export class HostAgentCatalog {
@@ -184,26 +173,67 @@ export class HostAgentCatalog {
 export class HostSessionProvisioner {
     host;
     instanceId;
+    resolvedExecutions = new Map();
     constructor(host, instanceId) {
         this.host = host;
         this.instanceId = instanceId;
     }
-    async provision(operationId) {
+    async provision(operationId, session = {}) {
         const result = await this.host.call("session.ensure", {
             scopeId: this.instanceId,
             operationId,
-            session: {},
+            session,
         });
         if (!result?.sessionId)
             throw new Error("host did not return a provisioned session id");
+        this.resolvedExecutions.set(result.sessionId, {
+            runtime: result.execution.provider,
+            model: result.execution.model,
+            ...(result.execution.reasoningEffort
+                ? { reasoningEffort: result.execution.reasoningEffort }
+                : {}),
+            ...(session.agent ? { agent: session.agent } : {}),
+        });
         return result.sessionId;
     }
+    takeExecution(sessionId) {
+        const execution = this.resolvedExecutions.get(sessionId);
+        this.resolvedExecutions.delete(sessionId);
+        return execution;
+    }
+    async existingExecution(sessionId) {
+        try {
+            const session = await this.host.call("session.meta.get", { sessionId });
+            return {
+                runtime: session.execution.provider,
+                model: session.execution.model,
+                ...(session.execution.reasoningEffort
+                    ? { reasoningEffort: session.execution.reasoningEffort }
+                    : {}),
+            };
+        }
+        catch (error) {
+            if (hostErrorCode(error) === "SESSION_NOT_FOUND")
+                return undefined;
+            throw error;
+        }
+    }
     allocationOperationId(sessionKey, previousSessionId) {
         return stableOperationId("allocate", this.instanceId, sessionKey, previousSessionId ?? "initial");
     }
     forkOperationId(fromSessionId, newSessionKey) {
         return stableOperationId("fork", this.instanceId, fromSessionId, newSessionKey);
     }
+    async fork(operationId, sourceSessionId, title) {
+        const result = await this.host.call("session.fork", {
+            sourceSessionId,
+            operationId,
+            ...(title ? { title } : {}),
+        });
+        if (!result?.sessionId)
+            throw new Error("host did not return a forked session id");
+        return result.sessionId;
+    }
     async setTitle(sessionId, title) {
         await this.host.call("session.meta.setTitle", { sessionId, title });
     }
@@ -217,6 +247,7 @@ export class HostSessionProvisioner {
 export class HostProvisionedLarkSessionStore extends FileLarkActiveSessionStore {
     operation;
     mutationTail = Promise.resolve();
+    instanceDefaultAgent;
     constructor(options) {
         const operation = new AsyncLocalStorage();
         super({
@@ -224,52 +255,94 @@ export class HostProvisionedLarkSessionStore extends FileLarkActiveSessionStore
             defaultAgent: options.defaultAgent,
             now: options.now,
             createSessionId: async () => {
-                const operationId = operation.getStore();
-                if (!operationId)
+                const allocation = operation.getStore();
+                if (!allocation)
                     throw new Error("session allocation is missing its stable operation id");
-                return options.provisioner.provision(operationId);
+                return options.provisioner.provision(allocation.operationId, allocation.session);
             },
         });
         this.operation = operation;
         this.provisioner = options.provisioner;
+        this.instanceDefaultAgent = options.defaultAgent;
     }
     provisioner;
     async ensure(sessionKey) {
         return this.runMutation(async () => {
             const current = await super.get(sessionKey);
-            if (current)
-                return { ...current, source: "existing" };
-            return this.withAllocation(sessionKey, undefined, () => super.ensure(sessionKey));
+            const existingExecution = current
+                ? await this.provisioner.existingExecution(current.sessionId)
+                : undefined;
+            if (current && existingExecution) {
+                const pinned = current.runtime
+                    ? current
+                    : await super.freeze(sessionKey, existingExecution);
+                return { ...current, ...pinned, source: "existing" };
+            }
+            if (current) {
+                const replacement = await this.withAllocation(sessionKey, current.sessionId, launchMeta(current), () => super.rotate(sessionKey));
+                return {
+                    ...await this.pinResolvedExecution(sessionKey, replacement),
+                    source: "new",
+                };
+            }
+            const created = await this.withAllocation(sessionKey, undefined, this.instanceDefaultAgent ? { agent: this.instanceDefaultAgent } : {}, () => super.ensure(sessionKey));
+            return this.pinResolvedExecution(sessionKey, created);
         });
     }
     async set(sessionKey, sessionId, cwd) {
-        return this.runMutation(() => super.set(sessionKey, sessionId, cwd));
+        return this.runMutation(async () => this.pinResolvedExecution(sessionKey, await super.set(sessionKey, sessionId, cwd)));
     }
-    async rotate(sessionKey) {
+    async get(sessionKey) {
         return this.runMutation(async () => {
             const current = await super.get(sessionKey);
-            return this.withAllocation(sessionKey, current?.sessionId, () => super.rotate(sessionKey));
+            if (!current)
+                return current;
+            const existingExecution = await this.provisioner.existingExecution(current.sessionId);
+            if (existingExecution) {
+                return current.runtime ? current : super.freeze(sessionKey, existingExecution);
+            }
+            const replacement = await this.withAllocation(sessionKey, current.sessionId, launchMeta(current), () => super.rotate(sessionKey));
+            return this.pinResolvedExecution(sessionKey, replacement);
         });
     }
-    async bindCwd(sessionKey, cwd) {
+    async rotate(sessionKey) {
         return this.runMutation(async () => {
             const current = await super.get(sessionKey);
-            return this.withAllocation(sessionKey, current?.sessionId, () => super.bindCwd(sessionKey, cwd));
+            const rotated = await this.withAllocation(sessionKey, current?.sessionId, launchMeta(current), () => super.rotate(sessionKey));
+            return this.pinResolvedExecution(sessionKey, rotated);
         });
     }
+    async bindCwd(sessionKey, cwd) {
+        void sessionKey;
+        void cwd;
+        throw new Error("working directory is managed by the Session Project snapshot");
+    }
     async applySettings(sessionKey, settings) {
         return this.runMutation(async () => {
             if (!settings.rotate && (await super.get(sessionKey))) {
                 return super.applySettings(sessionKey, settings);
             }
             const current = await super.get(sessionKey);
-            return this.withAllocation(sessionKey, current?.sessionId, () => super.applySettings(sessionKey, settings));
+            const providerChanged = Boolean(settings.runtime && settings.runtime !== current?.runtime);
+            const updated = await this.withAllocation(sessionKey, current?.sessionId, launchMeta({
+                ...(providerChanged
+                    ? { provider: settings.runtime }
+                    : (current?.agent ?? this.instanceDefaultAgent)
+                        ? { agent: current?.agent ?? this.instanceDefaultAgent }
+                        : settings.runtime
+                            ? { provider: settings.runtime }
+                            : {}),
+                ...(settings.model ? { model: settings.model } : {}),
+                ...(settings.reasoningEffort ? { reasoningEffort: settings.reasoningEffort } : {}),
+            }), () => super.applySettings(sessionKey, settings));
+            return this.pinResolvedExecution(sessionKey, updated);
         });
     }
     async setAgent(sessionKey, agentName) {
         return this.runMutation(async () => {
             const current = await super.get(sessionKey);
-            return this.withAllocation(sessionKey, current?.sessionId, () => super.setAgent(sessionKey, agentName));
+            const updated = await this.withAllocation(sessionKey, current?.sessionId, { agent: agentName }, () => super.setAgent(sessionKey, agentName));
+            return this.pinResolvedExecution(sessionKey, updated);
         });
     }
     async freeze(sessionKey, execution) {
@@ -277,11 +350,22 @@ export class HostProvisionedLarkSessionStore extends FileLarkActiveSessionStore
             const current = await super.get(sessionKey);
             if (current)
                 return super.freeze(sessionKey, execution);
-            return this.withAllocation(sessionKey, undefined, () => super.freeze(sessionKey, execution));
+            const frozen = await this.withAllocation(sessionKey, undefined, launchMeta(execution), () => super.freeze(sessionKey, execution));
+            return this.pinResolvedExecution(sessionKey, frozen);
         });
     }
-    withAllocation(sessionKey, previousSessionId, run) {
-        return this.operation.run(this.provisioner.allocationOperationId(sessionKey, previousSessionId), run);
+    async pinResolvedExecution(sessionKey, record) {
+        const execution = this.provisioner.takeExecution(record.sessionId);
+        if (!execution)
+            return record;
+        const frozen = await super.freeze(sessionKey, execution);
+        return { ...record, ...frozen };
+    }
+    withAllocation(sessionKey, previousSessionId, session, run) {
+        return this.operation.run({
+            operationId: this.provisioner.allocationOperationId(sessionKey, previousSessionId),
+            session,
+        }, run);
     }
     async runMutation(run) {
         const previous = this.mutationTail;
@@ -298,6 +382,22 @@ export class HostProvisionedLarkSessionStore extends FileLarkActiveSessionStore
         }
     }
 }
+function launchMeta(input) {
+    if (!input)
+        return {};
+    return {
+        ...(input.agent ? { agent: input.agent } : {}),
+        ...(input.provider ? { provider: input.provider } : {}),
+        ...(input.model ? { model: input.model } : {}),
+        ...(input.reasoningEffort ? { reasoningEffort: input.reasoningEffort } : {}),
+    };
+}
+function hostErrorCode(error) {
+    return error && typeof error === "object" && "code" in error &&
+        typeof error.code === "string"
+        ? error.code
+        : undefined;
+}
 export function stableOperationId(kind, ...parts) {
     const digest = createHash("sha256").update(parts.join("\0")).digest("hex");
     return `${kind}-${digest}`;

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-/** Public Lark plugin API. The manifest executable is the self-contained
- * `dist/runtime.mjs`, loaded only by @rynx-ai/plugin-runner; this module exports
- * no legacy in-process `RynxPlugin` manifest or daemon Channel factory. */
+/** Public Lark plugin API. Rynx loads the manifest's self-contained runtime
+ * module; this package exports no in-process daemon Channel factory. */
 export { LocalLarkBotRuntime } from "./lark.js";
-export { authorizeLark, larkConfigSchema, LARK_BOT_SCOPES, LARK_BOT_EVENTS, } from "./lark-setup.js";
+export { authorizeLark, larkConfigSchema, LARK_BOT_SCOPES, LARK_BOT_EVENTS, type LarkAuthorizationMaterial, type LarkSetupField, } from "./lark-setup.js";
 export { activate, createLarkPluginRuntime, LARK_CHANNEL_ID, type LarkPluginRuntimeOptions, } from "./runtime.js";
+export { createLarkPluginSettings, type LarkPluginSettingsOptions, } from "./settings.js";
 export { HostAgentCapabilities, HostAgentCatalog, HostConversationRuntime, HostProvisionedLarkSessionStore, HostSessionProvisioner, stableOperationId, } from "./host-adapters.js";

package/dist/index.js

@@ -1,7 +1,7 @@
-/** Public Lark plugin API. The manifest executable is the self-contained
- * `dist/runtime.mjs`, loaded only by @rynx-ai/plugin-runner; this module exports
- * no legacy in-process `RynxPlugin` manifest or daemon Channel factory. */
+/** Public Lark plugin API. Rynx loads the manifest's self-contained runtime
+ * module; this package exports no in-process daemon Channel factory. */
 export { LocalLarkBotRuntime } from "./lark.js";
 export { authorizeLark, larkConfigSchema, LARK_BOT_SCOPES, LARK_BOT_EVENTS, } from "./lark-setup.js";
 export { activate, createLarkPluginRuntime, LARK_CHANNEL_ID, } from "./runtime.js";
+export { createLarkPluginSettings, } from "./settings.js";
 export { HostAgentCapabilities, HostAgentCatalog, HostConversationRuntime, HostProvisionedLarkSessionStore, HostSessionProvisioner, stableOperationId, } from "./host-adapters.js";

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

@@ -0,0 +1,30 @@
+import type { PluginExecutionDefaults } from "@rynx-ai/plugin-sdk";
+export interface LarkInstanceConfig {
+    id: string;
+    name: string;
+    enabled: boolean;
+    appId: string;
+    appSecret: string;
+    defaultAgent?: string;
+    executionDefaults: PluginExecutionDefaults;
+}
+export declare class LarkConfigStore {
+    private readonly file;
+    constructor(dataDir: string);
+    list(): LarkInstanceConfig[];
+    get(id: string): LarkInstanceConfig | undefined;
+    upsert(input: {
+        id?: string;
+        name: string;
+        enabled: boolean;
+        appId: string;
+        appSecret?: string;
+        defaultAgent?: string | null;
+        runtime?: PluginExecutionDefaults["runtime"];
+        allowedRoots?: string[];
+    }): LarkInstanceConfig;
+    remove(id: string): boolean;
+    setEnabled(id: string, enabled: boolean): LarkInstanceConfig;
+    private read;
+    private write;
+}

package/dist/lark-config-store.js

@@ -0,0 +1,135 @@
+import { randomUUID } from "node:crypto";
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import path from "node:path";
+const INSTANCE_ID_PATTERN = /^[a-z][a-z0-9-]{0,62}$/;
+export class LarkConfigStore {
+    file;
+    constructor(dataDir) {
+        mkdirSync(dataDir, { recursive: true, mode: 0o700 });
+        this.file = path.join(dataDir, "lark-config.json");
+    }
+    list() {
+        return structuredClone(this.read().instances);
+    }
+    get(id) {
+        return this.list().find((instance) => instance.id === id);
+    }
+    upsert(input) {
+        const state = this.read();
+        const id = input.id ?? `instance-${randomUUID().slice(0, 8)}`;
+        if (!INSTANCE_ID_PATTERN.test(id))
+            throw new Error("Lark instance id is invalid");
+        const existing = state.instances.find((instance) => instance.id === id);
+        const secret = input.appSecret?.trim() || existing?.appSecret;
+        if (!secret)
+            throw new Error("App Secret is required");
+        const appId = input.appId.trim();
+        const name = input.name.trim();
+        if (!appId)
+            throw new Error("App ID is required");
+        if (!name)
+            throw new Error("instance name is required");
+        const defaultAgent = input.defaultAgent === undefined
+            ? existing?.defaultAgent
+            : input.defaultAgent?.trim() || undefined;
+        const roots = input.allowedRoots ?? existing?.executionDefaults.allowedRoots ?? [];
+        if (!Array.isArray(roots) || roots.some((root) => typeof root !== "string" || !path.isAbsolute(root))) {
+            throw new Error("allowed roots must be absolute paths");
+        }
+        const instance = {
+            id,
+            name,
+            enabled: input.enabled,
+            appId,
+            appSecret: secret,
+            ...(defaultAgent ? { defaultAgent } : {}),
+            executionDefaults: {
+                runtime: input.runtime ?? existing?.executionDefaults.runtime ?? "codex",
+                allowedRoots: [...new Set(roots.map((root) => path.resolve(root)))],
+                ...(defaultAgent ? { defaultAgent } : {}),
+            },
+        };
+        const index = state.instances.findIndex((item) => item.id === id);
+        if (index >= 0)
+            state.instances[index] = instance;
+        else
+            state.instances.push(instance);
+        this.write(state);
+        return structuredClone(instance);
+    }
+    remove(id) {
+        const state = this.read();
+        const filtered = state.instances.filter((instance) => instance.id !== id);
+        if (filtered.length === state.instances.length)
+            return false;
+        this.write({ ...state, instances: filtered });
+        return true;
+    }
+    setEnabled(id, enabled) {
+        const state = this.read();
+        const instance = state.instances.find((item) => item.id === id);
+        if (!instance)
+            throw new Error(`Lark instance "${id}" not found`);
+        instance.enabled = enabled;
+        this.write(state);
+        return structuredClone(instance);
+    }
+    read() {
+        if (!existsSync(this.file))
+            return { schemaVersion: 1, instances: [] };
+        const info = lstatSync(this.file);
+        if (!info.isFile() || info.isSymbolicLink() || info.size > 1024 * 1024) {
+            throw new Error("Lark plugin configuration is invalid");
+        }
+        return parseState(JSON.parse(readFileSync(this.file, "utf8")));
+    }
+    write(state) {
+        const temporary = `${this.file}.tmp-${randomUUID()}`;
+        try {
+            writeFileSync(temporary, `${JSON.stringify(state, null, 2)}\n`, {
+                encoding: "utf8",
+                mode: 0o600,
+                flag: "wx",
+            });
+            chmodSync(temporary, 0o600);
+            renameSync(temporary, this.file);
+        }
+        finally {
+            rmSync(temporary, { force: true });
+        }
+    }
+}
+function parseState(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error("Lark plugin configuration must be an object");
+    }
+    const record = value;
+    if (record.schemaVersion !== 1 || !Array.isArray(record.instances)) {
+        throw new Error("Lark plugin configuration schema is invalid");
+    }
+    const ids = new Set();
+    const instances = record.instances.map((value) => {
+        if (typeof value !== "object" || value === null || Array.isArray(value)) {
+            throw new Error("Lark instance configuration is invalid");
+        }
+        const instance = value;
+        if (!INSTANCE_ID_PATTERN.test(instance.id) ||
+            typeof instance.name !== "string" || !instance.name ||
+            typeof instance.enabled !== "boolean" ||
+            typeof instance.appId !== "string" || !instance.appId ||
+            typeof instance.appSecret !== "string" || !instance.appSecret ||
+            (instance.defaultAgent !== undefined &&
+                (typeof instance.defaultAgent !== "string" || !instance.defaultAgent.trim())) ||
+            !instance.executionDefaults ||
+            !["codex", "traex", "claude"].includes(instance.executionDefaults.runtime) ||
+            !Array.isArray(instance.executionDefaults.allowedRoots) ||
+            !instance.executionDefaults.allowedRoots.every((root) => typeof root === "string" && path.isAbsolute(root))) {
+            throw new Error("Lark instance configuration is invalid");
+        }
+        if (ids.has(instance.id))
+            throw new Error(`duplicate Lark instance id "${instance.id}"`);
+        ids.add(instance.id);
+        return structuredClone(instance);
+    });
+    return { schemaVersion: 1, instances };
+}

package/dist/lark-runtime-state-store.d.ts

@@ -0,0 +1,18 @@
+import type { PluginHealth } from "@rynx-ai/plugin-sdk";
+export interface LarkRuntimeInstanceState {
+    state: "starting" | "running" | "failed" | "stopping" | "stopped";
+    connected: boolean;
+    lastError: string | null;
+    lastEventAt: string | null;
+}
+export interface LarkRuntimeState {
+    active: boolean;
+    health: PluginHealth;
+    instances: Record<string, LarkRuntimeInstanceState>;
+}
+export declare class LarkRuntimeStateStore {
+    private readonly file;
+    constructor(dataDir: string);
+    read(): LarkRuntimeState;
+    write(state: LarkRuntimeState): void;
+}