dsh-lark-bot 0.6.0 → 0.7.0

package/dist/plugin.d.ts

@@ -1,113 +1,700 @@
 import { Service, Context } from '@deepseek-ai/cordis';
+import { NormalizedMessage, createLarkChannel, LarkChannel } from '@larksuite/channel';
 
-interface AppPaths {
-    root: string;
-    configFile: string;
-    activeProfileFile: string;
-    profileDir: (profile: string) => string;
-    profilePath: (profile: string, ...parts: string[]) => string;
-    sessionsFile: (profile: string) => string;
-    sessionCatalogFile: (profile: string) => string;
-    archivesDir: (profile: string) => string;
-    workspacesFile: (profile: string) => string;
-    mediaDir: (profile: string) => string;
-    logsDir: (profile: string) => string;
-    serviceDir: string;
-    serviceEnvFile: string;
-    serviceMetadataFile: string;
-    serviceLogFile: (profile: string) => string;
-    registryFile: string;
-    locksDir: string;
-}
-
-type ServicePlatform = 'linux-systemd' | 'linux-portable' | 'darwin-launchd' | 'win32-task';
-type ServiceRuntimeState = 'running' | 'stopped' | 'error' | 'unknown';
-interface ServiceSpec {
-    serviceName: string;
-    label: string;
-    profile: string;
-    nodePath: string;
-    cliJsPath: string;
-    envFile: string;
-    logFile: string;
-    env: Record<string, string>;
+type AgentEvent = {
+    type: 'system';
+    sessionId: string | undefined;
+    cwd: string | undefined;
+    model: string | undefined;
+} | {
+    type: 'text';
+    delta: string;
+} | {
+    type: 'final_text';
+    content: string;
+} | {
+    type: 'thinking';
+    delta: string;
+} | {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: unknown;
+} | {
+    type: 'tool_result';
+    id: string;
+    output: string;
+    isError: boolean;
+} | {
+    type: 'usage';
+    inputTokens?: number;
+    outputTokens?: number;
+    costUsd?: number;
+} | {
+    type: 'done';
+    sessionId: string | undefined;
+    terminationReason: 'normal' | 'interrupted' | 'timeout';
+} | {
+    type: 'error';
+    message: string;
+    terminationReason: 'failed' | 'interrupted' | 'timeout';
+};
+type ApprovalOptionKind = 'allow_once' | 'allow_always' | 'reject_once' | 'reject_always';
+interface ApprovalOption {
+    optionId: string;
+    name: string;
+    kind: ApprovalOptionKind;
+}
+interface ApprovalRequest {
+    id: string;
+    sessionId: string | undefined;
+    toolName: string;
+    reason: string | undefined;
+    options: readonly ApprovalOption[];
+}
+type ApprovalOutcome = 'allowed-once' | 'rejected' | 'cancelled';
+interface AgentRunOptions {
+    runId: string;
+    prompt: string;
+    cwd: string | undefined;
+    sessionId: string | undefined;
+    model: string | undefined;
+    images: readonly string[] | undefined;
+    stopGraceMs: number | undefined;
+    /** ACP approval channel: invoked when the agent requests a one-shot permission. */
+    onApprovalRequest?: (request: ApprovalRequest) => Promise<ApprovalOutcome>;
+}
+interface AgentRun {
+    readonly runId: string;
+    readonly events: AsyncIterable<AgentEvent>;
+    stop(): Promise<void>;
+    waitForExit(timeoutMs: number): Promise<boolean>;
+}
+interface AgentAvailability {
+    ok: boolean;
+    error: string | undefined;
+    version: string | undefined;
 }
-interface ServiceStatus {
+interface AgentAdapter {
+    readonly id: string;
+    readonly displayName: string;
+    isAvailable(): Promise<boolean>;
+    checkAvailability(): Promise<AgentAvailability>;
+    run(options: AgentRunOptions): AgentRun;
+    /** Optional teardown hook called on bridge shutdown. */
+    dispose?(): Promise<void>;
+}
+
+type LarkTenant = 'feishu' | 'lark';
+type AdapterMode = 'sdk' | 'acp' | 'headless';
+interface RuntimeEnv {
+    home: string;
+    tenant: LarkTenant;
+    appId: string | undefined;
+    appSecret: string | undefined;
+    workspace: string | undefined;
+    dshCommand: string;
+    dshArgs: string[];
+    /** True when DSH_LARK_DSH_COMMAND / DSH_LARK_DSH_ARGS were set explicitly. */
+    dshExplicit: boolean;
+    adapterMode: AdapterMode;
+    provider: string;
+    model: string;
+    maxTokens: number | undefined;
+    runTimeoutMs: number;
+    stopGraceMs: number;
+    /** Max agent runs allowed concurrently per scope (default 2). */
+    scopeConcurrency: number;
+    /** Live messages kept per scope before overflow is archived (default 40). */
+    retentionMsgs: number;
+    /** Max archives retained per scope before pruning (default 50, 0 disables). */
+    archiveMax: number;
+    /** Archives older than this many days are pruned (default 90, 0 disables). */
+    archiveMaxAgeDays: number;
+    accessDefaultDeny: boolean;
+    eventFreshnessMs: number;
+}
+
+interface ActiveRunHandle {
+    runId: string;
+    stop(): Promise<void>;
+}
+/**
+ * Tracks every running agent run, keyed by scope. A scope can hold several
+ * concurrent runs (multi-agent collaboration); `interrupt` stops them all,
+ * while `interruptRun` targets one run by id.
+ */
+declare class ActiveRuns {
+    private readonly runs;
+    set(scope: string, handle: ActiveRunHandle): void;
+    /** First active run for the scope, if any (backward-compatible accessor). */
+    get(scope: string): ActiveRunHandle | undefined;
+    list(scope: string): ActiveRunHandle[];
+    count(scope: string): number;
+    has(scope: string): boolean;
+    delete(scope: string, runId: string): boolean;
+    /** Stop every active run in the scope. Returns how many were interrupted. */
+    interrupt(scope: string): Promise<number>;
+    /** Stop one run by id. Returns whether the run existed. */
+    interruptRun(scope: string, runId: string): Promise<boolean>;
+}
+
+/**
+ * Pending approval registry. Cards are rendered by the caller; this store
+ * correlates card button clicks with the ACP `request_permission` promise and
+ * guarantees every request is settled when a run ends or is disposed.
+ */
+declare class ApprovalRegistry {
+    private readonly pending;
+    register(scope: string, request: ApprovalRequest): Promise<ApprovalOutcome>;
+    resolve(scope: string, id: string, outcome: ApprovalOutcome): boolean;
+    /** Settle every pending approval for a scope (run end / dispose). */
+    settleAll(scope: string, outcome: ApprovalOutcome): number;
+    pendingCount(scope: string): number;
+}
+
+type CardDensity = 'compact' | 'standard' | 'detailed';
+
+/** Per-scope card density overrides on top of a default. */
+declare class DensityStore {
+    private readonly defaultDensity;
+    private readonly overrides;
+    constructor(defaultDensity?: CardDensity);
+    get(scope: string): CardDensity;
+    set(scope: string, density: CardDensity): void;
+    clear(scope: string): boolean;
+}
+
+/**
+ * Per-scope concurrent-run overrides. `undefined` means the profile /
+ * environment default applies. Mirrors `RunPolicyStore` semantics.
+ */
+declare class ConcurrencyStore {
+    private readonly limits;
+    get(scope: string): number | undefined;
+    set(scope: string, limit: number): void;
+    clear(scope: string): boolean;
+}
+
+declare class ModelStore {
+    private readonly overrides;
+    get(scope: string): string | undefined;
+    set(scope: string, model: string): void;
+    clear(scope: string): boolean;
+}
+
+type PendingFlush<T> = (scope: string, batch: T[]) => void | Promise<void>;
+/**
+ * Per-scope debounced message queue with bounded concurrency. A scope may run
+ * several flushes in parallel up to `concurrencyFor(scope)`; `block` stops
+ * NEW flushes from starting while already-running ones finish, and `unblock`
+ * resumes scheduling.
+ */
+declare class PendingQueue<T> {
+    private readonly quietMs;
+    private readonly onFlush;
+    private readonly concurrencyFor;
+    private readonly pending;
+    private readonly timers;
+    private readonly blocked;
+    private readonly flushingCount;
+    constructor(quietMs: number, onFlush: PendingFlush<T>, concurrencyFor?: (scope: string) => number);
+    push(scope: string, item: T): void;
+    block(scope: string): void;
+    unblock(scope: string): void;
+    flushNow(scope: string): Promise<void>;
+    hasPending(scope: string): boolean;
+    isBlocked(scope: string): boolean;
+    isFlushing(scope: string): boolean;
+    activeFlushes(scope: string): number;
+    private schedule;
+    private clearTimer;
+}
+
+type QuestionKind = 'single' | 'multi' | 'text';
+interface QuestionCardInput {
+    id: string;
+    kind: QuestionKind;
+    question: string;
+    options?: string[];
+    placeholder?: string;
+}
+
+/**
+ * Pending question-card registry. `/ask` registers a card; the card submit
+ * action resolves it, and the answer is recorded back into the session.
+ */
+declare class QuestionRegistry {
+    private readonly pending;
+    register(scope: string, input: Omit<QuestionCardInput, 'id'>): {
+        id: string;
+        promise: Promise<string | string[] | undefined>;
+    };
+    resolve(scope: string, id: string, answer: string | string[] | undefined): boolean;
+    settleAll(scope: string): number;
+    get(scope: string, id: string): QuestionCardInput | undefined;
+}
+
+/**
+ * Per-scope live-message retention overrides. `undefined` means the profile /
+ * environment default applies. Mirrors `RunPolicyStore` semantics.
+ */
+declare class RetentionStore {
+    private readonly retentions;
+    get(scope: string): number | undefined;
+    set(scope: string, retention: number): void;
+    clear(scope: string): boolean;
+}
+
+interface RoleDefinition {
+    id: string;
     name: string;
-    platform: ServicePlatform;
-    installed: boolean;
-    autostartEnabled: boolean;
-    state: ServiceRuntimeState;
-    pid: number | undefined;
-    detail: string;
-    restarts: number | undefined;
-}
-interface ServiceController {
-    readonly platform: ServicePlatform;
-    installAndStart(spec: ServiceSpec): Promise<void>;
-    stop(spec: ServiceSpec): Promise<void>;
-    restart(spec: ServiceSpec): Promise<void>;
-    status(spec: ServiceSpec): Promise<ServiceStatus>;
-}
-
-interface ServiceMetadata {
+    /** System-style persona/instructions applied to every run of this role. */
+    persona: string;
+    /** Optional model override for this role (below the per-scope /model use). */
+    model?: string;
+    /** Optional comma-separated tool guidance shown to the agent. */
+    tools?: string;
+    /** Optional role rules text injected like an AGENTS.md. */
+    agentsMd?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+interface RoleStoreInput {
+    id: string;
+    name: string;
+    persona: string;
+    model?: string;
+    tools?: string;
+    agentsMd?: string;
+}
+/**
+ * Persisted role registry: named agent roles (persona / model / tools guidance /
+ * role rules) plus per-scope role bindings. Stored per profile at
+ * `<profile>/roles.json` (0600). Memory of bindings survives restarts.
+ */
+declare class RoleStore {
+    private data;
+    private saving;
+    private readonly path;
+    constructor(path: string);
+    load(): Promise<void>;
+    list(): RoleDefinition[];
+    get(id: string): RoleDefinition | undefined;
+    upsert(input: RoleStoreInput): RoleDefinition;
+    remove(id: string): boolean;
+    roleForScope(scope: string): RoleDefinition | undefined;
+    setScopeRole(scope: string, roleId: string): boolean;
+    clearScopeRole(scope: string): boolean;
+    flush(): Promise<void>;
+    private schedulePersist;
+}
+
+declare class RunPolicyStore {
+    private readonly timeouts;
+    get(scope: string): number | undefined;
+    set(scope: string, runTimeoutMs: number): void;
+    clear(scope: string): boolean;
+}
+
+interface ProfileConfig {
     schemaVersion: 1;
-    serviceName: string;
-    profile: string;
-    platform: ServicePlatform;
-    version: string;
-    installedAt: string;
+    agentKind: 'dsh';
+    tenant: LarkTenant;
+    accounts: {
+        appId: string;
+        appSecret: string;
+    };
+    workspaces: {
+        default: string | undefined;
+    };
+    preferences: {
+        model: string | undefined;
+        stopGraceMs: number | undefined;
+        runTimeoutMs: number | undefined;
+    };
+    access: {
+        allowedUsers: string[];
+        allowedChats: string[];
+        admins: string[];
+    };
 }
-interface ServiceManagerDeps {
-    profile?: string;
+interface RootConfig {
+    schemaVersion: 1;
+    activeProfile: string;
+    profiles: Record<string, ProfileConfig>;
+}
+declare class ConfigStore {
+    private readonly path;
+    private data;
+    constructor(path: string);
+    load(): Promise<RootConfig>;
+    getActiveProfile(): ProfileConfig | undefined;
+    getProfile(name: string): ProfileConfig | undefined;
+    saveProfile(name: string, input: {
+        tenant: LarkTenant;
+        appId: string;
+        appSecret: string;
+        workspace?: string;
+        model?: string;
+        stopGraceMs?: number;
+        runTimeoutMs?: number;
+        operatorOpenId?: string;
+        access?: {
+            allowedUsers?: string[];
+            allowedChats?: string[];
+            admins?: string[];
+        };
+    }): Promise<void>;
+    private getData;
+    private persist;
+}
+
+interface AccessSnapshot {
+    allowedUsers: string[];
+    allowedChats: string[];
+    admins: string[];
+}
+declare class AccessManager {
+    private readonly store;
+    private readonly profileName;
+    constructor(store: ConfigStore, profileName: string);
+    snapshot(): AccessSnapshot;
+    isAdmin(openId: string | undefined): boolean;
+    addUser(id: string): Promise<void>;
+    addAdmin(id: string): Promise<void>;
+    addChat(chatId: string): Promise<void>;
+    removeUser(id: string): Promise<void>;
+    removeChat(chatId: string): Promise<void>;
+    private profile;
+    private persist;
+}
+
+interface DshModelEntry {
+    id: string;
+    name: string | undefined;
+    contextWindow: number | undefined;
+    maxTokens: number | undefined;
+}
+interface DshProviderSummary {
+    id: string;
+    displayName: string;
+    namespace: string;
+    configured: boolean;
+    credentialRef: string | undefined;
+    credentialReady: boolean;
+    models: DshModelEntry[];
+    /** Whether dsh-lark-bot can add/update/remove this provider via chat. */
+    managed: boolean;
+}
+interface DshProviderManagerOptions {
+    home?: string;
     env?: NodeJS.ProcessEnv;
-    paths?: AppPaths;
-    version?: string;
-    controller?: ServiceController;
-}
-declare class ServiceManager {
-    private readonly profile;
-    private readonly sourceEnv;
-    private readonly paths;
-    private readonly version;
-    private readonly controllerOverride;
-    constructor(deps?: ServiceManagerDeps);
-    private buildSpec;
-    resolveController(): Promise<ServiceController>;
-    private saveMetadata;
-    readMetadata(): Promise<ServiceMetadata | undefined>;
-    private prepareFiles;
-    start(): Promise<ServiceStatus>;
-    stop(): Promise<ServiceStatus>;
-    restart(): Promise<ServiceStatus>;
-    status(): Promise<ServiceStatus>;
+    settingsFile?: string;
+    credentialsFile?: string;
+}
+interface DshPiAiProviderInput {
+    id: string;
+    displayName?: string;
+    apiKeyEnv?: string;
+    api?: string;
+    baseURL?: string;
+    models?: DshModelEntry[];
+}
+declare class DshProviderManager {
+    private readonly home;
+    private readonly env;
+    private readonly settingsFile;
+    private readonly credentialsFile;
+    constructor(options?: DshProviderManagerOptions);
+    readSettings(): Promise<Record<string, unknown>>;
+    readCredentials(): Promise<Record<string, string>>;
+    hasCredential(ref: string): Promise<boolean>;
+    listCredentialRefs(): Promise<string[]>;
+    listProviders(): Promise<DshProviderSummary[]>;
+    private describeDeepseek;
+    private describePiAi;
+    defaultModel(): Promise<string | undefined>;
+    setDefaultModel(model: string): Promise<void>;
+    upsertDeepseekProvider(input: {
+        baseURL?: string;
+        apiKeyEnv?: string;
+        apiKey?: string;
+    }): Promise<void>;
+    removeDeepseekProvider(): Promise<void>;
+    addDeepseekModel(input: DshModelEntry): Promise<void>;
+    removeDeepseekModel(id: string): Promise<boolean>;
+    upsertPiAiProvider(input: DshPiAiProviderInput): Promise<void>;
+    removePiAiProvider(id: string): Promise<boolean>;
+    addPiAiModel(providerId: string, input: DshModelEntry): Promise<void>;
+    removePiAiModel(providerId: string, modelId: string): Promise<boolean>;
+    setCredential(ref: string, value: string): Promise<void>;
+    removeCredential(ref: string): Promise<boolean>;
+    private writeNamespace;
+    private deleteNamespace;
+}
+
+interface SessionRecord {
+    sessionId: string | undefined;
+    cwd: string;
+    messages: ChatMessage[];
+}
+interface ChatMessage {
+    role: 'user' | 'assistant';
+    content: string;
+}
+interface RecordExchangeOptions {
+    /** Max live messages kept for the scope (overflow is archived, then trimmed). */
+    retention?: number;
+    /** Called with the messages that fall outside the retention window. */
+    onArchive?: (overflow: ChatMessage[]) => void | Promise<void>;
+}
+declare class SessionStore {
+    private data;
+    private saving;
+    private pendingArchive;
+    private readonly path;
+    constructor(path: string);
+    load(): Promise<void>;
+    getRaw(scopeId: string): SessionRecord | undefined;
+    set(scopeId: string, sessionId: string | undefined, cwd: string): void;
+    historyFor(scopeId: string, cwd: string): ChatMessage[];
+    recordExchange(scopeId: string, cwd: string, userMessages: string[], assistantMessage: string | undefined, options?: RecordExchangeOptions): void;
+    /** Full live transcript for a scope (subject to the current retention window). */
+    fullHistoryFor(scopeId: string, cwd: string): ChatMessage[];
+    clear(scopeId: string): boolean;
+    fork(scopeId: string, newScopeId: string, cwd: string): boolean;
+    resumeFor(scopeId: string, cwd: string): string | undefined;
+    flush(): Promise<void>;
+    private schedulePersist;
+    private snapshot;
 }
 
+type ArchiveSource = 'manual' | 'retention';
+interface ArchiveRecord {
+    /** Stable archive id: `20260815T020000Z-<short hex>`. */
+    archiveId: string;
+    scope: string;
+    cwd: string | undefined;
+    source: ArchiveSource;
+    note: string | undefined;
+    messageCount: number;
+    archivedAt: string;
+    jsonlPath: string;
+    markdownPath: string;
+    gitCommit: string | undefined;
+}
+interface ArchiveInput {
+    scope: string;
+    cwd: string | undefined;
+    messages: readonly ChatMessage[];
+    source?: ArchiveSource;
+    note?: string;
+}
+interface ArchivePruneOptions {
+    /** Keep at most this many archives per scope (oldest removed first). */
+    maxArchives?: number;
+    /** Remove archives older than this many milliseconds. */
+    maxAgeMs?: number;
+}
+/**
+ * Durable session/task archival: every archive is written as a human-readable
+ * Markdown transcript plus a machine-readable JSONL payload under
+ * `<profile>/archives/<scope-slug>/`. When `git` is available, the archive
+ * root is lazily initialized as its own Git repository and each archive is
+ * committed, giving an auditable, replayable history that survives local
+ * retention trimming.
+ */
+declare class SessionArchive {
+    private readonly archiveDir;
+    private readonly runGit;
+    private gitInitialized;
+    constructor(archiveDir: string, runGit?: (args: string[], cwd: string) => Promise<string>);
+    archive(input: ArchiveInput): Promise<ArchiveRecord>;
+    list(scope?: string): Promise<ArchiveRecord[]>;
+    /** Remove archives beyond per-scope count/age limits. Returns the number removed. */
+    prune(options?: ArchivePruneOptions): Promise<number>;
+    private ensureGit;
+}
+
+declare class WorkspaceStore {
+    private data;
+    private saving;
+    private readonly path;
+    constructor(path: string);
+    load(): Promise<void>;
+    cwdFor(scopeId: string): string | undefined;
+    setCwd(scopeId: string, cwd: string): void;
+    removeCwd(scopeId: string): boolean;
+    listNamed(): Record<string, string>;
+    getNamed(name: string): string | undefined;
+    saveNamed(name: string, cwd: string): void;
+    touchNamed(name: string): void;
+    removeNamed(name: string): boolean;
+    listIndex(): Array<{
+        name: string;
+        cwd: string;
+        lastUsed: number | undefined;
+    }>;
+    flush(): Promise<void>;
+    private schedulePersist;
+}
+
+/**
+ * Persistent scope → chat/thread directory. Every inbound message registers
+ * its scope, so the bridge can later push outbound notifications to other
+ * chats/topics (cross-session messaging). Persisted per profile at
+ * `<profile>/scopes.json` so targets survive restarts.
+ */
+declare class ScopeDirectory {
+    private data;
+    private saving;
+    private readonly path;
+    constructor(path: string);
+    load(): Promise<void>;
+    register(scope: string, chatId: string, threadId: string | undefined): void;
+    /** Resolve a scope key to its chat destination. */
+    resolve(scope: string): {
+        chatId: string;
+        threadId: string | undefined;
+    } | undefined;
+    /** Direct chat lookup by chatId (also matches topic scopes by prefix). */
+    resolveChat(chatId: string): {
+        chatId: string;
+        threadId: string | undefined;
+    } | undefined;
+    knownScopes(): string[];
+    flush(): Promise<void>;
+    private schedulePersist;
+}
+
+interface StartChannelDeps {
+    appId: string;
+    appSecret: string;
+    tenant: 'feishu' | 'lark';
+    adapter: AgentAdapter;
+    sessions: SessionStore;
+    workspaces: WorkspaceStore;
+    activeRuns: ActiveRuns;
+    runPolicies: RunPolicyStore;
+    concurrencyStore: ConcurrencyStore;
+    defaultScopeConcurrency: number;
+    retentionStore: RetentionStore;
+    roleStore: RoleStore;
+    scopeDirectory?: ScopeDirectory;
+    archiver: SessionArchive;
+    defaultRetention: number;
+    archiveMax: number;
+    archiveMaxAgeDays: number;
+    defaultRunTimeoutMs: number;
+    accessManager: AccessManager;
+    pending: PendingQueue<NormalizedMessage>;
+    approvals?: ApprovalRegistry;
+    questions?: QuestionRegistry;
+    densityStore?: DensityStore;
+    models: ModelStore;
+    dshConfig: DshProviderManager;
+    defaultWorkspace: string;
+    defaultModel: string;
+    allowedUsers?: string[];
+    allowedChats?: string[];
+    accessDefaultDeny?: boolean;
+    eventFreshnessMs?: number;
+    stopGraceMs?: number;
+    createChannel?: typeof createLarkChannel;
+}
+interface BridgeChannel {
+    channel: LarkChannel;
+    disconnect(): Promise<void>;
+}
+declare function startChannel(deps: StartChannelDeps): Promise<BridgeChannel>;
+
+interface BridgeEngineStatus {
+    state: 'running' | 'stopped';
+    profile: string;
+    home: string;
+    adapterId: string;
+    startedAt: string | undefined;
+    workspace: string | undefined;
+    notifyUrl: string | undefined;
+}
+interface BridgeEngine {
+    readonly profile: string;
+    readonly home: string;
+    status(): BridgeEngineStatus;
+    stop(): Promise<void>;
+}
+interface BridgeEngineOptions {
+    env: RuntimeEnv;
+    profileName: string;
+    /** Allow first-run QR onboarding when no credentials exist. */
+    allowOnboarding: boolean;
+    /** Injectable channel factory (tests / host integration). */
+    createChannel?: Parameters<typeof startChannel>[0]['createChannel'];
+    /** Injectable adapter (tests); otherwise built from env. */
+    adapter?: AgentAdapter;
+}
+/**
+ * Start the bridge engine. Runs the full Feishu channel pipeline (stores,
+ * adapter, card queue, notify server) and returns a handle that can be
+ * stopped. No process-level signal handling: the CLI wrapper owns signals,
+ * and the dsh bundle plugin owns lifecycle via the cordis context.
+ */
+declare function startBridgeEngine(options: BridgeEngineOptions): Promise<BridgeEngine>;
+
 /** Cordis plugin name; stable across releases (referenced by the bundle patch). */
 declare const name = "dsh-lark-bot";
 /** No hard service dependency: the bundle must never block a profile boot. */
 declare const inject: string[];
 interface Config {
-    /** Bridge profile managed by this bundle (defaults to `default`). */
+    /** Bridge bot profile name inside the bridge state store (default `default`). */
     profile?: string;
-    /** Start the standalone bridge when the profile boots (env `DSH_LARK_AUTOSTART=1`). */
-    autostart?: boolean;
     /** Explicit `~/.dsh-lark` override (env `DSH_LARK_HOME`). */
     home?: string;
+    /** Feishu/Lark app id (env `DSH_LARK_APP_ID`). */
+    appId?: string;
+    /** Feishu/Lark app secret (env `DSH_LARK_APP_SECRET`). */
+    appSecret?: string;
+    /** `feishu` or `lark` (env `DSH_LARK_TENANT`). */
+    tenant?: string;
+    /** Default workspace for new sessions (env `DSH_LARK_WORKSPACE`). */
+    workspace?: string;
+    /** Agent backend mode: `sdk` (default) / `acp` / `headless`. */
+    adapter?: 'sdk' | 'acp' | 'headless';
+    /** Default model (env `DSH_LARK_MODEL`). */
+    model?: string;
+    /** Set to true (or env `DSH_LARK_DISABLED=1`) to keep the bridge stopped. */
+    disabled?: boolean;
+}
+/** Test-only dependency overrides; production rows configure through Config/env. */
+interface PluginDeps {
+    env?: NodeJS.ProcessEnv;
+    createChannel?: Parameters<typeof startBridgeEngine>[0]['createChannel'];
+    adapter?: AgentAdapter;
+}
+interface LarkBridgeStatus {
+    state: 'starting' | 'running' | 'stopped';
+    profile: string;
+    home: string;
+    adapterId: string;
+    startedAt: string | undefined;
+    workspace: string | undefined;
+    notifyUrl: string | undefined;
 }
 /**
- * `larkBridge` service exposed to other in-process plugins: manages the
- * standalone dsh-lark-bot background service (start / status / restart /
- * stop) through the same controllers the CLI uses.
+ * `larkBridge` service exposed to other in-process plugins: starts/stops the
+ * bridge engine and reports its status. The engine runs inside the dsh
+ * process (same event loop), so the Feishu channel, notify callback and the
+ * nested dsh SDK runtime are all owned by the loaded plugin.
  */
 declare class LarkBridgeService extends Service {
-    private readonly manager;
-    constructor(ctx: Context, manager: ServiceManager);
-    status(): Promise<ServiceStatus>;
-    start(): Promise<ServiceStatus>;
-    restart(): Promise<ServiceStatus>;
-    stop(): Promise<ServiceStatus>;
+    private engine;
+    private startPromise;
+    constructor(ctx: Context);
+    status(): LarkBridgeStatus;
+    start(config?: Config, deps?: PluginDeps): Promise<BridgeEngine>;
+    stop(): Promise<void>;
 }
-declare function apply(ctx: Context, config?: Config, managerOverride?: ServiceManager): LarkBridgeService;
+declare function apply(ctx: Context, config?: Config, deps?: PluginDeps): () => void;
 
-export { type Config, LarkBridgeService, apply, inject, name };
+export { type Config, LarkBridgeService, type LarkBridgeStatus, type PluginDeps, apply, inject, name };