@dfy-plugins/resource-core 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xiaoxiao44443
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,5 @@
+# @dfy-plugins/resource-core
+
+普通 npm 公共库，不是 Harness 插件。提供版本化不透明资源引用、provider 所有权隔离、进程内资源注册表和纯文本降级。
+
+`getProcessResourceRegistry()` 通过稳定的 `Symbol.for` ABI 共享注册表，因此独立发布或各自打包依赖的插件仍可在同一个 Harness 进程中交换短期资源，而不把字节放进 JSON。

package/lib/index.d.ts

@@ -0,0 +1,48 @@
+/** Provider-neutral transient resource references shared by DFY DSH plugins. */
+export declare const RESOURCE_PROTOCOL_VERSION: 1;
+export declare const RESOURCE_REFERENCE_PREFIX = "dfyr1_";
+export declare const PROCESS_RESOURCE_REGISTRY_SYMBOL_KEY = "@dfy-plugins/resource-core/process-registry/v1";
+export interface ResourceReferenceV1 {
+    version: typeof RESOURCE_PROTOCOL_VERSION;
+    provider: string;
+    kind: string;
+    id: string;
+}
+export interface ResolvedResource {
+    kind: string;
+    data?: Uint8Array;
+    mediaType?: string;
+    bytes?: number;
+    name?: string;
+    metadata?: Readonly<Record<string, unknown>>;
+}
+export interface ResourceProvider {
+    readonly id: string;
+    resolve(reference: ResourceReferenceV1, signal?: AbortSignal): Promise<ResolvedResource | undefined>;
+}
+export interface ResourceTextFallback {
+    kind: string;
+    name?: string;
+    path?: string;
+    url?: string;
+    mediaType?: string;
+    bytes?: number;
+}
+export declare function encodeResourceReference(reference: ResourceReferenceV1): string;
+export declare function decodeResourceReference(token: string): ResourceReferenceV1;
+/** In-process broker. Providers retain ownership and authorization of their resources. */
+export declare class ResourceRegistry {
+    #private;
+    readonly version: 1;
+    registerProvider(provider: ResourceProvider): () => void;
+    hasProvider(id: string): boolean;
+    listProviders(): string[];
+    resolve(token: string, expectedKind?: string, signal?: AbortSignal): Promise<ResolvedResource>;
+}
+/**
+ * Process-local singleton shared even when independently bundled plugins load
+ * different physical copies of this package. No resource data crosses JSON.
+ */
+export declare function getProcessResourceRegistry(): ResourceRegistry;
+/** Safe readable fallback for a consumer that cannot project the resource itself. */
+export declare function renderResourceTextFallback(resource: ResourceTextFallback): string;

package/lib/index.js

@@ -0,0 +1,153 @@
+/** Provider-neutral transient resource references shared by DFY DSH plugins. */
+export const RESOURCE_PROTOCOL_VERSION = 1;
+export const RESOURCE_REFERENCE_PREFIX = 'dfyr1_';
+export const PROCESS_RESOURCE_REGISTRY_SYMBOL_KEY = '@dfy-plugins/resource-core/process-registry/v1';
+const MAX_REFERENCE_LENGTH = 2048;
+const PROVIDER_PATTERN = /^[a-z0-9](?:[a-z0-9._-]{0,62}[a-z0-9])?$/;
+const KIND_PATTERN = /^[a-z0-9](?:[a-z0-9._-]{0,62}[a-z0-9])?$/;
+const RESOURCE_ID_PATTERN = /^[A-Za-z0-9_-]{8,256}$/;
+function validReferencePart(value, pattern) {
+    return typeof value === 'string' && pattern.test(value);
+}
+export function encodeResourceReference(reference) {
+    if (reference.version !== RESOURCE_PROTOCOL_VERSION
+        || !validReferencePart(reference.provider, PROVIDER_PATTERN)
+        || !validReferencePart(reference.kind, KIND_PATTERN)
+        || !validReferencePart(reference.id, RESOURCE_ID_PATTERN)) {
+        throw new Error('resource reference is invalid');
+    }
+    const encoded = Buffer.from(JSON.stringify({
+        v: reference.version,
+        p: reference.provider,
+        k: reference.kind,
+        i: reference.id,
+    }), 'utf8').toString('base64url');
+    return `${RESOURCE_REFERENCE_PREFIX}${encoded}`;
+}
+export function decodeResourceReference(token) {
+    const value = token.trim();
+    if (value.length <= RESOURCE_REFERENCE_PREFIX.length
+        || value.length > MAX_REFERENCE_LENGTH
+        || !value.startsWith(RESOURCE_REFERENCE_PREFIX)) {
+        throw new Error('resource reference is invalid');
+    }
+    const encoded = value.slice(RESOURCE_REFERENCE_PREFIX.length);
+    if (!/^[A-Za-z0-9_-]+$/.test(encoded))
+        throw new Error('resource reference is invalid');
+    let parsed;
+    try {
+        parsed = JSON.parse(Buffer.from(encoded, 'base64url').toString('utf8'));
+    }
+    catch {
+        throw new Error('resource reference is invalid');
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error('resource reference is invalid');
+    }
+    const record = parsed;
+    if (record.v !== RESOURCE_PROTOCOL_VERSION
+        || !validReferencePart(record.p, PROVIDER_PATTERN)
+        || !validReferencePart(record.k, KIND_PATTERN)
+        || !validReferencePart(record.i, RESOURCE_ID_PATTERN)
+        || Object.keys(record).some((key) => !['v', 'p', 'k', 'i'].includes(key))) {
+        throw new Error('resource reference is invalid');
+    }
+    return {
+        version: RESOURCE_PROTOCOL_VERSION,
+        provider: record.p,
+        kind: record.k,
+        id: record.i,
+    };
+}
+function providerId(provider) {
+    if (!PROVIDER_PATTERN.test(provider.id))
+        throw new Error('resource provider id is invalid');
+    return provider.id;
+}
+/** In-process broker. Providers retain ownership and authorization of their resources. */
+export class ResourceRegistry {
+    version = RESOURCE_PROTOCOL_VERSION;
+    #providers = new Map();
+    registerProvider(provider) {
+        const id = providerId(provider);
+        if (this.#providers.has(id))
+            throw new Error(`resource provider already registered: ${id}`);
+        this.#providers.set(id, provider);
+        return () => {
+            if (this.#providers.get(id) === provider)
+                this.#providers.delete(id);
+        };
+    }
+    hasProvider(id) {
+        return this.#providers.has(id);
+    }
+    listProviders() {
+        return [...this.#providers.keys()].sort();
+    }
+    async resolve(token, expectedKind, signal) {
+        signal?.throwIfAborted();
+        const reference = decodeResourceReference(token);
+        if (expectedKind !== undefined && reference.kind !== expectedKind) {
+            throw new Error(`resource kind mismatch: expected ${expectedKind}, received ${reference.kind}`);
+        }
+        const provider = this.#providers.get(reference.provider);
+        if (provider === undefined)
+            throw new Error(`resource provider is unavailable: ${reference.provider}`);
+        const resource = await provider.resolve(reference, signal);
+        signal?.throwIfAborted();
+        if (resource === undefined)
+            throw new Error('resource is unavailable or expired');
+        if (resource.kind !== reference.kind)
+            throw new Error('resource provider returned a mismatched kind');
+        if (resource.data !== undefined && resource.bytes !== undefined && resource.data.byteLength !== resource.bytes) {
+            throw new Error('resource provider returned inconsistent byte metadata');
+        }
+        return resource;
+    }
+}
+function isCompatibleRegistry(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const registry = value;
+    return registry.version === RESOURCE_PROTOCOL_VERSION
+        && typeof registry.registerProvider === 'function'
+        && typeof registry.hasProvider === 'function'
+        && typeof registry.listProviders === 'function'
+        && typeof registry.resolve === 'function';
+}
+/**
+ * Process-local singleton shared even when independently bundled plugins load
+ * different physical copies of this package. No resource data crosses JSON.
+ */
+export function getProcessResourceRegistry() {
+    const key = Symbol.for(PROCESS_RESOURCE_REGISTRY_SYMBOL_KEY);
+    const globals = globalThis;
+    const existing = globals[key];
+    if (existing !== undefined) {
+        if (!isCompatibleRegistry(existing))
+            throw new Error('process resource registry version conflict');
+        return existing;
+    }
+    const registry = new ResourceRegistry();
+    globals[key] = registry;
+    return registry;
+}
+function displayValue(value, limit) {
+    return value.replace(/[\u0000-\u001f\u007f]+/g, ' ').replace(/\s+/g, ' ').trim().slice(0, limit);
+}
+/** Safe readable fallback for a consumer that cannot project the resource itself. */
+export function renderResourceTextFallback(resource) {
+    const kind = displayValue(resource.kind, 64) || 'resource';
+    const lines = [`Resource available (${kind}).`];
+    if (resource.name !== undefined)
+        lines.push(`Name: ${displayValue(resource.name, 255)}`);
+    if (resource.mediaType !== undefined)
+        lines.push(`Media type: ${displayValue(resource.mediaType, 127)}`);
+    if (resource.bytes !== undefined)
+        lines.push(`Bytes: ${String(resource.bytes)}`);
+    if (resource.path !== undefined)
+        lines.push(`Local path: ${displayValue(resource.path, 2048)}`);
+    if (resource.url !== undefined)
+        lines.push(`Source URL: ${displayValue(resource.url, 2048)}`);
+    return lines.join('\n');
+}

package/lib/session-storage.d.ts

@@ -0,0 +1,3 @@
+export declare function sessionArtifactDirectory(persistence: unknown, header: unknown): string | undefined;
+/** Resolve through the backend, including after a restart when no Agent is loaded. */
+export declare function persistedSessionArtifactDirectory(persistence: unknown, sessionId: string, signal: AbortSignal): Promise<string | undefined>;

package/lib/session-storage.js

@@ -0,0 +1,26 @@
+/** Compatibility boundary for DSH's legacy headers and handle-based persistence. */
+import { dirname, isAbsolute } from 'node:path';
+export function sessionArtifactDirectory(persistence, header) {
+    const backend = persistence;
+    const location = backend.locate?.(header);
+    return location !== undefined && isAbsolute(location.path) ? dirname(location.path) : undefined;
+}
+/** Resolve through the backend, including after a restart when no Agent is loaded. */
+export async function persistedSessionArtifactDirectory(persistence, sessionId, signal) {
+    signal.throwIfAborted();
+    const backend = persistence;
+    let header;
+    if (typeof backend.stat === 'function') {
+        header = (await backend.stat(sessionId, { signal }))?.header;
+    }
+    else {
+        const entries = await backend.list(signal);
+        header = entries.map((entry) => {
+            if (entry !== null && typeof entry === 'object' && 'header' in entry)
+                return entry.header;
+            return entry;
+        }).find((entry) => entry !== null && typeof entry === 'object' && 'id' in entry && entry.id === sessionId);
+    }
+    signal.throwIfAborted();
+    return header === undefined ? undefined : sessionArtifactDirectory(backend, header);
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@dfy-plugins/resource-core",
+  "version": "0.1.1",
+  "description": "Versioned resource references and provider registry shared by DFY DSH plugins.",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./session-storage": {
+      "types": "./lib/session-storage.d.ts",
+      "default": "./lib/session-storage.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.5.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xiaoxiao44443/dfy-dsh-plugins.git",
+    "directory": "packages/resource-core"
+  },
+  "homepage": "https://github.com/xiaoxiao44443/dfy-dsh-plugins#readme",
+  "bugs": {
+    "url": "https://github.com/xiaoxiao44443/dfy-dsh-plugins/issues"
+  },
+  "keywords": [
+    "deepseek-harness"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "tsc -p tsconfig.json && node --test"
+  }
+}