@nocobase/app-plugin-agents 0.0.0-stage → 0.1.0-beta.10

package/dist/server/core/skills/skill.service.d.ts

@@ -0,0 +1,105 @@
+/**
+ * The skill library: skills in the open Agent Skills format, every save a new version, the latest one always the one
+ * runs get. An older version can be compared and restored (as a new version). Skills are attached to agents, and as
+ * defaults to a working directory or a scope the application registers. Who may change skills is the route's concern;
+ * the service checks only the values.
+ *
+ * A skill is named and described by its `SKILL.md` front matter alone, checked against the Agent Skills specification
+ * on every create, save, restore and import (`parseSkillMarkdown`), with each problem's field and reason in the error.
+ * Its `name` is the skill's slug: a save that changes it renames the skill, refused when another skill has that name.
+ * Runs claimed afterwards get it under the new name; a run already given the skill reads its version by hash.
+ *
+ * A version keeps its `SKILL.md` body in its row and lists its files in a manifest (`ManifestEntry`): each file's bytes
+ * are a blob stored once per content (`blobs.ts`). A save resolves its files to blobs before its transaction; a runner's
+ * bundle and an online run's snapshot are assembled from blobs and kept in memory by the version's hash. A skill moves
+ * as a zip in the Agent Skills layout (`importArchive`, `exportArchive`).
+ */
+import { type RunSkill, type SkillBundle } from '@nocobase/agent-protocol';
+import type { DatabaseConnection } from '@nocobase/db';
+import { z } from 'zod';
+import { type Skill, type SkillDetail, type SkillImport, type SkillInput, type SkillSave, type SkillScope, type SkillUpload, type SkillVersion, type SkillVersionDetail } from '../../../shared/skills.js';
+import type { Clock } from '../../kernel/clock.js';
+import type { IdSource } from '../../kernel/ids.js';
+import type { People } from '../../kernel/people.js';
+import type { TxRunner } from '../../kernel/tx.js';
+import { type SkillBlobs } from './blobs.js';
+export declare const SkillInputSchema: z.ZodType<SkillInput>;
+export declare const SkillSaveSchema: z.ZodType<SkillSave>;
+export declare const SkillImportSchema: z.ZodType<SkillImport>;
+export declare const SkillIdsSchema: z.ZodType<{
+    readonly skillIds: string[];
+}>;
+/** A scope and its id: where skills are attached. */
+export interface SkillTarget {
+    readonly scope: SkillScope;
+    readonly scopeId: string;
+}
+export interface SkillService {
+    list(): Promise<Skill[]>;
+    get(id: string): Promise<SkillDetail>;
+    create(userId: string | null, input: SkillInput): Promise<SkillDetail>;
+    /**
+     * A new version with everything given, when the skill is still at `save.expectedRevision` (its revision is its
+     * current version): 409 `REVISION_CONFLICT` with the current `metadata.revision` otherwise.
+     */
+    save(id: string, userId: string | null, save: SkillSave): Promise<SkillDetail>;
+    remove(id: string): Promise<void>;
+    versions(id: string): Promise<SkillVersion[]>;
+    version(id: string, version: number): Promise<SkillVersionDetail>;
+    /** `version` becomes current again, as a new version, when the skill is still at `expectedRevision`. */
+    restore(id: string, version: number, userId: string | null, expectedRevision: number): Promise<SkillDetail>;
+    attached(target: SkillTarget): Promise<string[]>;
+    /** Makes `skillIds` the skills attached to the target; unknown ids are refused. */
+    attach(target: SkillTarget, skillIds: readonly string[], conn?: DatabaseConnection): Promise<string[]>;
+    /**
+     * For a claim: the latest version of every skill attached to `targets`, each once. Where two skills share a slug,
+     * the earlier target's wins (the claim lists the agent first).
+     */
+    forRun(conn: DatabaseConnection, targets: readonly SkillTarget[], runId: string): Promise<RunSkill[]>;
+    /** One of a run's skills, as the runner fetches it: assembled from its blobs, cached by its version's hash. */
+    bundle(conn: DatabaseConnection, slug: string): Promise<SkillBundle>;
+    /** Stores a file or a zip to import, before the save or import that names it (`SkillUpload.id`). */
+    upload(bytes: Uint8Array): Promise<SkillUpload>;
+    /** A file of a version, as it is stored. */
+    file(id: string, version: number, path: string): Promise<{
+        readonly path: string;
+        readonly bytes: Uint8Array;
+    }>;
+    /** A version (the current one by default) as a zip in the Agent Skills layout: `<slug>/SKILL.md` and its files. */
+    exportArchive(id: string, version?: number): Promise<{
+        readonly filename: string;
+        readonly bytes: Uint8Array;
+    }>;
+    /** A zip in the Agent Skills layout as a new skill, or as a new version of `input.skillId`. */
+    importArchive(userId: string | null, input: SkillImport): Promise<SkillDetail>;
+    /**
+     * A version of one of a run's skills, as an online run reads it: `SKILL.md` and its files, text read, by the
+     * version's hash (`RunSkill.hash`); kept in memory, least recently used out first.
+     */
+    snapshot(slug: string, hash: string): Promise<SkillSnapshot>;
+    /** Deletes stored contents no version names, last used more than `graceMs` ago; the number deleted. */
+    collectGarbage(graceMs: number): Promise<number>;
+}
+/** A skill version as an online run's sandbox mounts it. */
+export interface SkillSnapshot {
+    readonly slug: string;
+    readonly hash: string;
+    /** `SKILL.md` as delivered, with its front matter. */
+    readonly markdown: string;
+    readonly files: readonly {
+        readonly path: string;
+        readonly size: number;
+        readonly executable: boolean;
+        /** The text; null for a binary file. */
+        readonly text: string | null;
+    }[];
+}
+export interface SkillServiceDeps {
+    readonly tx: TxRunner;
+    readonly ids: IdSource;
+    readonly clock: Clock;
+    readonly people: People;
+    readonly blobs: SkillBlobs;
+}
+export declare function createSkillService(deps: SkillServiceDeps): SkillService;
+//# sourceMappingURL=skill.service.d.ts.map

package/dist/server/core/skills/skill.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill.service.d.ts","sourceRoot":"","sources":["../../../../server/core/skills/skill.service.ts"],"names":[],"mappings":"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"}