@huanlin/dsh-plugin-aigc-canvas 0.1.0 → 0.1.2

package/lib/config.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Serializable configuration and defaults for the AIGC canvas host half.
+ * The `providers` array holds one or more AIGC provider configs (name /
+ * endpoint / apiKey / instructions), editable at runtime through the DSH
+ * GUI settings page; cordis.yml `config:` is the first-boot seed only.
+ *
+ * @module @dsh-external/dsh-aigc-canvas/config
+ */
+import z from 'schemastery';
+/** Provider id pattern: lowercase letters, digits, hyphens; must start with a letter. */
+export declare const PROVIDER_ID_PATTERN: RegExp;
+/** How the aigc_http_request tool attaches the provider apiKey to requests. */
+export interface AigcProviderAuth {
+    /**
+     * Auth scheme:
+     *  - `bearer`: `Authorization: Bearer <apiKey>` (the default)
+     *  - `header`: `<name>: <apiKey>` (name defaults to `x-api-key`)
+     *  - `query`:  `<name>=<apiKey>` URL query parameter (name defaults to `api_key`)
+     */
+    scheme?: 'bearer' | 'header' | 'query';
+    /** Header name (scheme=header) or query param name (scheme=query). Ignored for bearer. */
+    name?: string;
+}
+/** Resolved auth config (every field guaranteed). */
+export interface ResolvedAigcProviderAuth {
+    scheme: 'bearer' | 'header' | 'query';
+    name: string;
+}
+/** One AIGC provider configuration (editable at runtime via the settings page). */
+export interface AigcProvider {
+    /** Stable identifier (lowercase, hyphenated); used as the `provider_id` tool param. */
+    id: string;
+    /** Provider display name (e.g. "Volcano Engine", "Jimeng", "MiniMax"). */
+    name: string;
+    /** Provider API endpoint URL. `stub://aigc-backend` = the built-in stub. */
+    endpoint: string;
+    /** Provider API key (stored in memory only; set via GUI or cordis.yml). */
+    apiKey: string;
+    /** Free-form usage instructions the agent reads via aigc_get_provider_info. */
+    instructions: string;
+    /** How the http tool attaches the apiKey (default: Authorization: Bearer). */
+    auth?: AigcProviderAuth;
+    /** Whether this provider is a builtin seed (cordis.yml); user-added providers are never builtin. */
+    builtin?: boolean;
+}
+/** Tunable AIGC canvas host settings (every field optional; defaults fill in). */
+export interface AigcCanvasConfig {
+    /** One or more AIGC providers; the first is the default. */
+    providers?: AigcProvider[];
+    /** Per-request timeout for backend calls (ms). */
+    requestTimeoutMs?: number;
+    /** Maximum media bytes to write to disk per generated asset. */
+    mediaSizeLimit?: number;
+}
+/** Schemastery schema for the plugin configuration. */
+export declare const Config: z<AigcCanvasConfig>;
+/** A fully-resolved provider (all fields guaranteed). */
+export interface ResolvedAigcProvider extends AigcProvider {
+    name: string;
+    endpoint: string;
+    apiKey: string;
+    instructions: string;
+    auth: ResolvedAigcProviderAuth;
+    builtin: boolean;
+}
+/** Fully defaulted settings consumed by the host half. */
+export interface ResolvedAigcConfig {
+    readonly providers: readonly ResolvedAigcProvider[];
+    requestTimeoutMs: number;
+    mediaSizeLimit: number;
+}
+/** Returns true when the provider endpoint points at the built-in stub backend. */
+export declare function isStubEndpoint(endpoint: string): boolean;
+/** Validate a provider id; returns an error message or undefined if valid. */
+export declare function validateProviderId(id: string): string | undefined;
+/** Apply direct-call defaults after Loader schema validation has normally run. */
+export declare function resolveAigcConfig(config: AigcCanvasConfig | undefined): ResolvedAigcConfig;

package/lib/context-types.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Structural types for the cordis services this plugin consumes, plus the
+ * Context augmentation both halves share. A third-party plugin resolves
+ * outside the DSH monorepo's single cordis instance, so the upstream
+ * `declare module 'cordis'` augmentations do not reach this Context — and
+ * the npm cordis package does not declare the DSH-vendored runtime members
+ * (`ctx.effect`, the httpServer/sessions/loader faces). The members below
+ * mirror the actual runtime shapes this plugin touches:
+ *
+ * - httpServer: @deepseek-ai/dsh-host-webserver
+ * - sessions:   @deepseek-ai/dsh-session (host side)
+ * - loader:     @cordisjs/plugin-loader (entry options)
+ * - invariants: @deepseek-ai/dsh-invariants
+ * - effect:     the DSH-vendored cordis lifecycle helper
+ *
+ * Drift from upstream is contained to this file.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Duplex } from 'node:stream';
+import type { Context } from 'cordis';
+import type { AigcCanvasService } from './canvas-registry.js';
+/** One named webserver route (mirror of the host-webserver WebRoute). */
+export interface AigcWebRoute {
+    kind: 'exact' | 'prefix';
+    path: string;
+    handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>;
+}
+/** One exact-path HTTP upgrade registration (mirror of WebUpgradeRoute). */
+export interface AigcWebUpgradeRoute {
+    path: string;
+    handler: (req: IncomingMessage, socket: Duplex, head: Buffer) => void | Promise<void>;
+}
+/** The httpServer service face this plugin uses. */
+export interface AigcHttpServer {
+    register(route: AigcWebRoute): () => void;
+    registerUpgrade(route: AigcWebUpgradeRoute): () => void;
+}
+/** A published session's header slice (authoritative cwd). */
+export interface AigcSessionHeader {
+    cwd?: string;
+}
+/** The host session store face (`ctx.sessions.get(id)` returns the live session). */
+export interface AigcSessionStore {
+    get(id: string): {
+        header: AigcSessionHeader;
+    } | undefined;
+}
+/**
+ * The minimal Agent face this plugin uses for context injection.
+ * Mirrors `@deepseek-ai/dsh-agent`'s `Agent.inject()` — see the DSH
+ * agent loop's inbox/splice path. The plugin calls `inject()` to push
+ * a notice into the agent's next-step context (non-waking).
+ */
+export interface AigcAgent {
+    readonly id: string;
+    inject(message: AigcUserMessage): void;
+}
+/** A minimal user-role message for agent.inject (mirrors dsh-llm's UserMessage). */
+export interface AigcUserMessage {
+    readonly id: string;
+    readonly role: 'user';
+    readonly content: ReadonlyArray<{
+        type: 'text';
+        text: string;
+    }>;
+    readonly source: {
+        readonly kind: 'plugin';
+        readonly plugin: string;
+        readonly form?: 'notice';
+        readonly summary?: string;
+    };
+}
+/** The agents registry face (`ctx.agents.get(sessionId)` returns the live agent). */
+export interface AigcAgentRegistry {
+    get(id: string): AigcAgent | undefined;
+}
+/** One loader entry's options slice (the connection row's resolved config). */
+export interface AigcLoaderEntry {
+    options: {
+        name: string;
+        config?: unknown;
+    };
+}
+/** The loader face used to read the connection row's trustedHosts config. */
+export interface AigcLoader {
+    entries(): Iterable<AigcLoaderEntry>;
+}
+/** The invariants service face (mirror of @deepseek-ai/dsh-invariants). */
+export interface AigcInvariantsService {
+    register(packageName: string, installer: (ctx: Context, fail: (message: string) => never) => void | Promise<void>): () => void;
+}
+/**
+ * The invariant service face restated (mirror of @deepseek-ai/dsh-invariants).
+ * Mirrored here exactly like better-sidebar does — the dual-cordis-instance
+ * resolution otherwise hides the upstream augmentation. The `tools` service
+ * face is declared in `./types.d.ts` (the ambient cordis module augmentation)
+ * and not restated here to avoid a "subsequent property declarations must
+ * have the same type" error.
+ */
+export interface AigcToolsService {
+    register(tool: unknown): () => void;
+}
+declare module 'cordis' {
+    interface Context {
+        httpServer: AigcHttpServer;
+        sessions: AigcSessionStore;
+        agents: AigcAgentRegistry;
+        loader: AigcLoader;
+        invariants: AigcInvariantsService;
+        /**
+         * The host-side AIGC canvas registry: holds the per-session element
+         * table (prompts + generated assets) and edges. Provided by the host
+         * half (see {@link ./canvas-registry.ts}); undefined on the client.
+         */
+        aigcCanvas: AigcCanvasService;
+        /** Register a lifecycle callback (DSH-vendored cordis). */
+        effect(fn: () => void | (() => void), label?: string): void;
+    }
+}
+export type { Context };

package/lib/index.d.ts

@@ -0,0 +1,12 @@
+import type { Context } from './context-types.js';
+import { Config, type AigcCanvasConfig, type AigcProvider, type ResolvedAigcConfig, type ResolvedAigcProvider } from './config.js';
+export { Config };
+export type { AigcCanvasConfig, AigcProvider, ResolvedAigcConfig, ResolvedAigcProvider };
+export type { Context } from './context-types.js';
+export type { AigcCanvasService, AigcElement, AigcEdge, AigcCanvasState, AigcElementKind, } from './canvas-registry.js';
+/** Plugin identity for cordis.yml rows. */
+export declare const name = "dsh-aigc-canvas";
+/** Services required before mounting. */
+export declare const inject: string[];
+/** Plugin body. */
+export declare function apply(ctx: Context, config?: AigcCanvasConfig): void;