@smartdoca/plugin-sdk 0.1.0

package/dist/LICENSING.md

@@ -0,0 +1,57 @@
+# Licensing
+
+[简体中文](LICENSING.zh-CN.md)
+
+Doca uses a dual-licensing model for code owned by the Doca copyright holders.
+
+## Open-source license
+
+Unless a file or package says otherwise, Doca-owned code in this repository is
+available under the GNU Affero General Public License version 3 only
+(`AGPL-3.0-only`). The full license text is in [LICENSE](LICENSE).
+
+The AGPL permits commercial use. When its conditions apply, it requires the
+corresponding source to remain available under the AGPL, including for modified
+versions offered to users over a network. “Open source” and “free of charge” are
+not the same thing, and the AGPL obligations do not depend on whether an operator
+charges money.
+
+## Commercial license
+
+Organizations that want to use Doca-owned code in a proprietary product without
+the AGPL obligations may obtain a separate commercial license from the Doca
+copyright holders. A commercial license exists only when both parties have
+entered into a written agreement. This repository does not itself grant that
+alternative license.
+
+## Packages and editors
+
+The same licensing direction applies to Doca-owned packages and editors,
+including the Doca plugin SDK and the Slate, presentation, spreadsheet,
+Markdown, and canvas editor packages. Each released npm artifact must:
+
+- carry an accurate license field and license notice;
+- link to the public source repository and the exact source tag for that version;
+- include the build scripts and dependency lock needed to produce the artifact;
+- preserve all notices and license obligations of third-party components.
+
+The historical archives under `vendor/` are development and recovery inputs.
+They are not the long-term public distribution channel. Before the public
+release, active editor dependencies must be rebuilt from their public tagged
+sources, published to npm, and consumed by Doca through registry versions.
+
+## Third-party software and assets
+
+The dual license covers only material for which the Doca copyright holders can
+grant these rights. Third-party libraries, fonts, media, generated artifacts,
+and other bundled material retain their own licenses. Their notices and source
+or attribution requirements must be followed independently.
+
+No trademark rights are granted by either the AGPL or this licensing summary.
+
+## Contributions
+
+Dual licensing requires the project to retain the rights needed to offer future
+commercial licenses. See [CONTRIBUTING.md](CONTRIBUTING.md) before submitting
+code. This document is a project policy summary, not a substitute for the
+license text or legal advice.

package/dist/LICENSING.zh-CN.md

@@ -0,0 +1,48 @@
+# 许可说明
+
+[English](LICENSING.md)
+
+Doca 对其版权所有者拥有权利的代码采用双许可模式。
+
+## 开源许可证
+
+除非文件或包中另有说明，本仓库内由 Doca 版权所有者拥有的代码默认采用
+GNU Affero General Public License version 3 only（`AGPL-3.0-only`）。完整条款见
+[LICENSE](LICENSE)。
+
+AGPL 允许商业使用。当其条件适用时，分发软件或将修改后的版本作为网络服务提供给
+用户，需要继续按 AGPL 提供对应源码。是否收费并不是 AGPL 义务的判断条件，“开源”
+也不等于“免费”。
+
+## 商业许可证
+
+希望在闭源产品中使用 Doca 自研代码、且不希望承担 AGPL 义务的组织，可以向 Doca
+版权所有者申请单独的商业许可证。只有双方签署书面协议后，商业许可证才成立；本仓库
+本身不授予该替代许可证。
+
+## 子包与编辑器
+
+同一许可方向适用于 Doca 自研的子包和编辑器，包括插件 SDK，以及 Slate 富文本、
+演示文稿、表格、Markdown 和画板编辑器。每个正式发布的 npm 制品必须：
+
+- 使用准确的许可证字段并携带许可证说明；
+- 链接公开源码仓库以及与该版本精确对应的 Git tag；
+- 提供生成该制品所需的构建脚本和依赖锁文件；
+- 保留所有第三方组件要求的许可证及声明。
+
+`vendor/` 中的历史压缩包是开发和恢复输入，不作为长期公开分发渠道。正式开源前，
+当前使用的编辑器依赖应从公开且已打 tag 的源码重新构建并发布到 npm，Doca 再改为
+使用 registry 版本。
+
+## 第三方软件与素材
+
+双许可只覆盖 Doca 版权所有者有权授予许可的内容。第三方库、字体、媒体、生成产物及
+其他随附内容继续适用各自许可证，其声明、源码提供或署名要求需要独立履行。
+
+AGPL 和本文均不授予商标使用权。
+
+## 外部贡献
+
+双许可要求项目持续保有提供商业许可证所需的权利。提交代码前请阅读
+[CONTRIBUTING.zh-CN.md](CONTRIBUTING.zh-CN.md)。本文只是项目政策摘要，不能替代
+许可证原文或专业法律意见。

package/dist/ai.d.ts

@@ -0,0 +1,27 @@
+import type { JsonObject, JsonValue } from "@smartdoca/plugin-contracts";
+import type { PluginRequestContext } from "./platform.js";
+export interface PluginAIToolContext extends PluginRequestContext {
+    readonly sessionId: string;
+    readonly turnId: string;
+    readonly jobId: string;
+    readonly callId: string;
+}
+export interface PluginAITool {
+    readonly id: string;
+    readonly description: string;
+    readonly inputSchema: JsonObject;
+    readonly approval?: "never" | "policy" | "always";
+    execute(input: JsonObject, context: PluginAIToolContext): Promise<JsonValue>;
+}
+export interface PluginAISkill {
+    readonly id: string;
+    readonly name: string;
+    readonly description: string;
+    readonly content: string;
+    readonly formats: readonly string[];
+}
+export interface AIServiceV1 {
+    registerTool(tool: PluginAITool): () => void;
+    registerSkill(skill: PluginAISkill): () => void;
+}
+export declare const aiServiceToken: import("@smartdoca/plugin-contracts").ServiceToken<AIServiceV1>;

package/dist/ai.js

@@ -0,0 +1,2 @@
+import { defineService } from "./index.js";
+export const aiServiceToken = defineService("ai.v1");

package/dist/files.d.ts

@@ -0,0 +1,3 @@
+import { type FilesServiceV1 } from "@smartdoca/files-capability";
+export * from "@smartdoca/files-capability";
+export declare const filesServiceToken: import("@smartdoca/plugin-contracts").ServiceToken<FilesServiceV1>;

package/dist/files.js

@@ -0,0 +1,4 @@
+import { defineService } from "./index.js";
+import { FILES_SERVICE_ID } from "@smartdoca/files-capability";
+export * from "@smartdoca/files-capability";
+export const filesServiceToken = defineService(FILES_SERVICE_ID);

package/dist/index.d.ts

@@ -0,0 +1,67 @@
+import { type DispatchMode, type DispatchResult, type DocaContext, type DocaContributionRegistry, type DocaPluginPackage, type DocaSystemConfig, type DocaPlugin, type EffectCleanup, type EffectDisposer, type EventHandler, type EventToken, type JsonObject, type NonWaterfallDispatchMode, type PluginLifecycleContext, type PluginManifest, type ServiceToken, type ContributionPoint, type ContributionRecord, type WaterfallNext } from "@smartdoca/plugin-contracts";
+import { Context as CordisContext, type Fiber as CordisFiber } from "@deepseek-ai/cordis";
+export * from "@smartdoca/plugin-contracts";
+export declare function plugin(packageName: string, options?: Omit<DocaPluginPackage, "package">): DocaPluginPackage;
+export declare function defineDocaConfig(config: DocaSystemConfig): DocaSystemConfig;
+export declare function defineService<T>(id: string): ServiceToken<T>;
+export declare function defineEvent<Payload, Result = void, Mode extends DispatchMode = "emit">(id: string, mode?: Mode): EventToken<Payload, Result, Mode>;
+export declare function defineContributionPoint<T>(id: string): ContributionPoint<T>;
+interface ContextCore {
+    readonly eventModes: Map<string, DispatchMode>;
+    nextScopeId: number;
+}
+export declare class Context implements DocaContext {
+    #private;
+    readonly scopeId: string;
+    constructor(scopeId?: string, internal?: {
+        native: CordisContext;
+        core: ContextCore;
+        fiber?: CordisFiber;
+        ownsFiber?: boolean;
+    });
+    get disposed(): boolean;
+    effect(setup: () => EffectCleanup | void): EffectDisposer;
+    effectAsync(setup: () => Promise<EffectCleanup | void>): Promise<EffectDisposer>;
+    provide<T>(token: ServiceToken<T>, value: T): EffectDisposer;
+    inject<T>(token: ServiceToken<T>): T;
+    injectOptional<T>(token: ServiceToken<T>): T | undefined;
+    has(token: ServiceToken<unknown>): boolean;
+    child(scopeId?: string): Context;
+    /**
+     * Create a Doca scope backed by a live Cordis plugin Fiber.
+     * PluginHost uses this for every registered plugin.
+     */
+    createFiberScope(scopeId: string): Promise<Context>;
+    on<Payload, Result, Mode extends DispatchMode>(event: EventToken<Payload, Result, Mode>, handler: EventHandler<Payload, Result, Mode>): EffectDisposer;
+    dispatch<Payload, Result>(event: EventToken<Payload, Result, "waterfall">, payload: Payload, next: WaterfallNext<Result>): Result;
+    dispatch<Payload, Result, Mode extends NonWaterfallDispatchMode>(event: EventToken<Payload, Result, Mode>, payload: Payload): DispatchResult<Result, Mode>;
+    dispose(): Promise<void>;
+}
+export declare class ContributionStore {
+    #private;
+    forContext(context: DocaContext, pluginId: string): DocaContributionRegistry;
+    register<T>(context: DocaContext, pluginId: string, point: ContributionPoint<T>, id: string, value: T): EffectDisposer;
+    get<T>(point: ContributionPoint<T>, id: string): ContributionRecord<T> | undefined;
+    list<T>(point: ContributionPoint<T>): readonly ContributionRecord<T>[];
+}
+export declare class PluginContext<Config extends JsonObject = JsonObject> implements PluginLifecycleContext<Config> {
+    readonly context: DocaContext;
+    readonly manifest: PluginManifest;
+    readonly config: Config;
+    readonly contributions: DocaContributionRegistry;
+    constructor(context: DocaContext, manifest: PluginManifest, config: Config, contributions: DocaContributionRegistry);
+    get scopeId(): string;
+    get disposed(): boolean;
+    provide<T>(token: ServiceToken<T>, value: T): EffectDisposer;
+    inject<T>(token: ServiceToken<T>): T;
+    injectOptional<T>(token: ServiceToken<T>): T | undefined;
+    has(token: ServiceToken<unknown>): boolean;
+    effect(setup: () => EffectCleanup | void): EffectDisposer;
+    effectAsync(setup: () => Promise<EffectCleanup | void>): Promise<EffectDisposer>;
+    child(scopeId?: string): DocaContext;
+    on<Payload, Result, Mode extends DispatchMode>(event: EventToken<Payload, Result, Mode>, handler: EventHandler<Payload, Result, Mode>): EffectDisposer;
+    dispatch<Payload, Result>(event: EventToken<Payload, Result, "waterfall">, payload: Payload, next: WaterfallNext<Result>): Result;
+    dispatch<Payload, Result, Mode extends NonWaterfallDispatchMode>(event: EventToken<Payload, Result, Mode>, payload: Payload): DispatchResult<Result, Mode>;
+    dispose(): Promise<void>;
+}
+export declare function definePlugin<Config extends JsonObject = JsonObject>(plugin: DocaPlugin<Config>): DocaPlugin<Config>;

package/dist/index.js

@@ -0,0 +1,342 @@
+import { PluginContractError, validatePluginManifest, } from "@smartdoca/plugin-contracts";
+import { Context as CordisContext, } from "@deepseek-ai/cordis";
+export * from "@smartdoca/plugin-contracts";
+const contractIdentifier = /^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$/;
+const contributionIdentifier = /^[A-Za-z0-9][A-Za-z0-9:./_-]*$/;
+function assertIdentifier(value, kind) {
+    if (!contractIdentifier.test(value))
+        throw new PluginContractError("INVALID_MANIFEST", `${kind} must be a stable lowercase dotted or dashed identifier`, value || "$");
+}
+export function plugin(packageName, options = {}) {
+    if (!/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/i.test(packageName))
+        throw new TypeError(`Invalid plugin package name: ${packageName}`);
+    const targets = options.targets
+        ? [...new Set(options.targets)]
+        : undefined;
+    return Object.freeze({
+        package: packageName,
+        ...(options.enabled === undefined ? {} : { enabled: options.enabled }),
+        ...(options.config === undefined
+            ? {}
+            : { config: structuredClone(options.config) }),
+        ...(targets === undefined ? {} : { targets: Object.freeze(targets) }),
+    });
+}
+export function defineDocaConfig(config) {
+    const seen = new Set();
+    const plugins = config.plugins.map((entry) => {
+        if (seen.has(entry.package))
+            throw new TypeError(`Duplicate plugin package: ${entry.package}`);
+        seen.add(entry.package);
+        return plugin(entry.package, entry);
+    });
+    return Object.freeze({ plugins: Object.freeze(plugins) });
+}
+export function defineService(id) {
+    assertIdentifier(id, "service identifier");
+    return Object.freeze({ id });
+}
+export function defineEvent(id, mode = "emit") {
+    assertIdentifier(id, "event identifier");
+    if (!["emit", "parallel", "serial", "bail", "waterfall"].includes(mode))
+        throw new PluginContractError("INVALID_MANIFEST", "unsupported dispatch mode", id);
+    return Object.freeze({ id, mode });
+}
+export function defineContributionPoint(id) {
+    assertIdentifier(id, "contribution point identifier");
+    return Object.freeze({ id });
+}
+export class Context {
+    scopeId;
+    #native;
+    #core;
+    #effects = [];
+    #fiber;
+    #ownsFiber;
+    #state = "active";
+    #disposePromise;
+    constructor(scopeId = "root", internal) {
+        this.scopeId = scopeId;
+        this.#native = internal?.native ?? new CordisContext();
+        this.#core = internal?.core ?? {
+            eventModes: new Map(),
+            nextScopeId: 0,
+        };
+        this.#fiber = internal?.fiber;
+        this.#ownsFiber = internal?.ownsFiber ?? false;
+    }
+    get disposed() {
+        return this.#state !== "active";
+    }
+    #assertActive() {
+        if (this.#state !== "active")
+            throw new PluginContractError("CONTEXT_DISPOSED", `context ${this.scopeId} is disposed`, this.scopeId);
+    }
+    #assertReadable() {
+        if (this.#state === "disposed")
+            throw new PluginContractError("CONTEXT_DISPOSED", `context ${this.scopeId} is disposed`, this.scopeId);
+    }
+    #track(dispose) {
+        this.#assertActive();
+        const record = { active: true, dispose };
+        this.#effects.push(record);
+        return async () => {
+            if (!record.active)
+                return;
+            record.active = false;
+            await record.dispose();
+        };
+    }
+    effect(setup) {
+        this.#assertActive();
+        const dispose = this.#native.fiber.effect(() => setup() ?? (() => { }), `doca.effect(${this.scopeId})`);
+        return this.#track(dispose);
+    }
+    async effectAsync(setup) {
+        this.#assertActive();
+        const cordisEffect = this.#native.fiber.effect(async () => (await setup()) ?? (() => { }), `doca.effectAsync(${this.scopeId})`);
+        const release = this.#track(cordisEffect);
+        await cordisEffect;
+        if (this.#state !== "active") {
+            await release();
+            throw new PluginContractError("CONTEXT_DISPOSED", `context ${this.scopeId} was disposed during async effect setup`, this.scopeId);
+        }
+        return release;
+    }
+    provide(token, value) {
+        this.#assertActive();
+        try {
+            return this.#track(this.#native.provide(token.id, value));
+        }
+        catch (error) {
+            if (error instanceof Error &&
+                error.message.includes(`service "${token.id}" has been registered`))
+                throw new PluginContractError("DUPLICATE_PROVIDER", `service ${token.id} is already provided (${error.message})`, token.id);
+            throw error;
+        }
+    }
+    inject(token) {
+        this.#assertReadable();
+        const value = this.#native.get(token.id, true);
+        if (value === undefined)
+            throw new PluginContractError("MISSING_INJECTION", `required service ${token.id} is unavailable`, token.id);
+        return value;
+    }
+    injectOptional(token) {
+        this.#assertReadable();
+        return this.#native.get(token.id, true);
+    }
+    has(token) {
+        this.#assertReadable();
+        return this.#native.get(token.id, true) !== undefined;
+    }
+    child(scopeId) {
+        this.#assertActive();
+        const child = new Context(scopeId ?? `${this.scopeId}.${++this.#core.nextScopeId}`, {
+            native: this.#native.extend(),
+            core: this.#core,
+            fiber: this.#fiber,
+        });
+        this.effect(() => () => child.dispose());
+        return child;
+    }
+    /**
+     * Create a Doca scope backed by a live Cordis plugin Fiber.
+     * PluginHost uses this for every registered plugin.
+     */
+    async createFiberScope(scopeId) {
+        this.#assertActive();
+        const runtime = {
+            name: `doca:${scopeId}`,
+            apply(_context) { },
+        };
+        const fiber = this.#native.plugin(runtime);
+        await fiber;
+        const child = new Context(scopeId, {
+            native: fiber.ctx,
+            core: this.#core,
+            fiber,
+            ownsFiber: true,
+        });
+        this.#track(() => child.dispose());
+        return child;
+    }
+    #assertEventMode(event) {
+        const current = this.#core.eventModes.get(event.id);
+        if (current && current !== event.mode)
+            throw new PluginContractError("INVALID_MANIFEST", `event ${event.id} was already defined with ${current} dispatch`, event.id);
+        this.#core.eventModes.set(event.id, event.mode);
+    }
+    on(event, handler) {
+        this.#assertActive();
+        this.#assertEventMode(event);
+        const dispose = this.#native.on(event.id, handler);
+        return this.#track(dispose);
+    }
+    dispatch(event, payload, next) {
+        this.#assertReadable();
+        this.#assertEventMode(event);
+        const native = this.#native;
+        if (event.mode === "waterfall") {
+            if (!next)
+                throw new PluginContractError("INVALID_MANIFEST", `waterfall event ${event.id} requires a next continuation`, event.id);
+            return native.waterfall(event.id, payload, next);
+        }
+        return native[event.mode](event.id, payload);
+    }
+    dispose() {
+        if (this.#disposePromise)
+            return this.#disposePromise;
+        this.#state = "disposing";
+        this.#disposePromise = (async () => {
+            const errors = [];
+            for (let index = this.#effects.length - 1; index >= 0; index--) {
+                const effect = this.#effects[index];
+                if (!effect.active)
+                    continue;
+                effect.active = false;
+                try {
+                    await effect.dispose();
+                }
+                catch (error) {
+                    errors.push(error);
+                }
+            }
+            if (this.#ownsFiber && this.#fiber) {
+                try {
+                    await this.#fiber.dispose();
+                }
+                catch (error) {
+                    errors.push(error);
+                }
+            }
+            this.#state = "disposed";
+            if (errors.length === 1)
+                throw errors[0];
+            if (errors.length)
+                throw new AggregateError(errors, `Failed to dispose context ${this.scopeId}`);
+        })();
+        return this.#disposePromise;
+    }
+}
+export class ContributionStore {
+    #records = new Map();
+    forContext(context, pluginId) {
+        assertIdentifier(pluginId, "plugin identifier");
+        return new ScopedContributionRegistry(this, context, pluginId);
+    }
+    register(context, pluginId, point, id, value) {
+        assertIdentifier(point.id, "contribution point identifier");
+        if (!contributionIdentifier.test(id))
+            throw new PluginContractError("INVALID_MANIFEST", "contribution identifier contains unsupported characters", id || "$");
+        const key = `${point.id}\u0000${id}`;
+        const existing = this.#records.get(key);
+        if (existing)
+            throw new PluginContractError("CONTRIBUTION_COLLISION", `contribution ${point.id}/${id} is already registered by ${existing.pluginId}`, `${point.id}.${id}`);
+        const record = {
+            point: point.id,
+            id,
+            pluginId,
+            value,
+        };
+        this.#records.set(key, record);
+        try {
+            return context.effect(() => () => {
+                if (this.#records.get(key) === record)
+                    this.#records.delete(key);
+            });
+        }
+        catch (error) {
+            this.#records.delete(key);
+            throw error;
+        }
+    }
+    get(point, id) {
+        return this.#records.get(`${point.id}\u0000${id}`);
+    }
+    list(point) {
+        return [...this.#records.values()].filter((record) => record.point === point.id);
+    }
+}
+class ScopedContributionRegistry {
+    store;
+    context;
+    pluginId;
+    constructor(store, context, pluginId) {
+        this.store = store;
+        this.context = context;
+        this.pluginId = pluginId;
+    }
+    register(point, id, value) {
+        return this.store.register(this.context, this.pluginId, point, id, value);
+    }
+    get(point, id) {
+        return this.store.get(point, id);
+    }
+    list(point) {
+        return this.store.list(point);
+    }
+}
+export class PluginContext {
+    context;
+    manifest;
+    config;
+    contributions;
+    constructor(context, manifest, config, contributions) {
+        this.context = context;
+        this.manifest = manifest;
+        this.config = config;
+        this.contributions = contributions;
+    }
+    get scopeId() {
+        return this.context.scopeId;
+    }
+    get disposed() {
+        return this.context.disposed;
+    }
+    provide(token, value) {
+        return this.context.provide(token, value);
+    }
+    inject(token) {
+        return this.context.inject(token);
+    }
+    injectOptional(token) {
+        return this.context.injectOptional(token);
+    }
+    has(token) {
+        return this.context.has(token);
+    }
+    effect(setup) {
+        return this.context.effect(setup);
+    }
+    effectAsync(setup) {
+        return this.context.effectAsync(setup);
+    }
+    child(scopeId) {
+        return this.context.child(scopeId);
+    }
+    on(event, handler) {
+        return this.context.on(event, handler);
+    }
+    dispatch(event, payload, next) {
+        if (event.mode === "waterfall")
+            return this.context.dispatch(event, payload, next);
+        return this.context.dispatch(event, payload);
+    }
+    dispose() {
+        return this.context.dispose();
+    }
+}
+export function definePlugin(plugin) {
+    const manifest = validatePluginManifest(plugin.manifest);
+    const required = plugin.injections?.required ?? [];
+    const optional = plugin.injections?.optional ?? [];
+    const seen = new Set();
+    for (const token of [...required, ...optional]) {
+        assertIdentifier(token.id, "service identifier");
+        if (seen.has(token.id))
+            throw new PluginContractError("INVALID_MANIFEST", `service ${token.id} is declared more than once`, `${manifest.id}.injections`);
+        seen.add(token.id);
+    }
+    return Object.freeze({ ...plugin, manifest });
+}

package/dist/knowledge.d.ts

@@ -0,0 +1,3 @@
+import type { KnowledgeSourceRegistryV1 } from "@smartdoca/knowledge-capability";
+export * from "@smartdoca/knowledge-capability";
+export declare const knowledgeSourceRegistryToken: import("@smartdoca/plugin-contracts").ServiceToken<Pick<KnowledgeSourceRegistryV1, "register">>;

package/dist/knowledge.js

@@ -0,0 +1,3 @@
+import { defineService } from "./index.js";
+export * from "@smartdoca/knowledge-capability";
+export const knowledgeSourceRegistryToken = defineService("knowledge.sources.v1");