@av-pi-studio/protocol 0.0.110 → 0.0.112

package/dist/messages.js

@@ -1054,6 +1054,252 @@ export const viewerSettingsUpdateSchema = z
 })
     .passthrough();
 // ===========================================================================
+// Skills (swe/architecture/pi-resource-management.md § Wire family `skills_*`) — sprint-075
+// slice 1: list + toggle only. Preview/install/remove/update_all land in sprints 076-077 and
+// reuse `skillInfoSchema`/`piPackageInfoSchema` below.
+// ===========================================================================
+/**
+ * One resolved Agent Skill as Pi's `DefaultPackageManager.resolve()` reports it, projected to the
+ * wire. `origin` documents the four values Pi emits today (`"agent_dir" | "agents_dir" |
+ * "package" | "settings_path"`) but stays `z.string()` — a future Pi origin must still parse on
+ * an older client/daemon pair. `removable` reflects Pi's own rule (e.g. a package-owned skill
+ * isn't independently removable); the daemon never re-derives it.
+ */
+export const skillInfoSchema = z
+    .object({
+    name: z.string(),
+    description: z.string().optional(),
+    path: z.string(),
+    enabled: z.boolean(),
+    /** `"agent_dir" | "agents_dir" | "package" | "settings_path"` today; open string on the wire. */
+    origin: z.string(),
+    originLabel: z.string(),
+    packageSource: z.string().optional(),
+    shadowedBy: z.string().optional(),
+    symlinkTarget: z.string().optional(),
+    provenance: z
+        .object({
+        source: z.string(),
+        sourceUrl: z.string().optional(),
+        installedAt: z.string().optional(),
+    })
+        .passthrough()
+        .optional(),
+    disableModelInvocation: z.boolean().optional(),
+    warnings: z.array(z.string()).optional(),
+    removable: z.boolean(),
+})
+    .passthrough();
+/** One `settings.json` `packages[]` entry resolved against disk. */
+export const piPackageInfoSchema = z
+    .object({
+    source: z.string(),
+    kind: z.enum(["npm", "git", "local"]),
+    identity: z.string(),
+    pinned: z.boolean(),
+    curated: z.boolean(),
+    filtered: z.boolean(),
+    skillCount: z.number(),
+})
+    .passthrough();
+export const skillsListRequestSchema = z
+    .object({
+    type: z.literal("skills_list_request"),
+    requestId: z.string(),
+})
+    .passthrough();
+/**
+ * `ok`/`error` are domain fields, not `rpc_error` (mirrors `extension_packs_set_response`'s
+ * idiom) — e.g. a corrupt `settings.json` answers `{ok:false, error:"settings_unreadable"}`
+ * rather than failing transport-level. `message` is an optional human-readable elaboration.
+ */
+export const skillsListResponseSchema = z
+    .object({
+    type: z.literal("skills_list_response"),
+    requestId: z.string(),
+    ok: z.boolean(),
+    error: z.string().optional(),
+    message: z.string().optional(),
+    skills: z.array(skillInfoSchema),
+    packages: z.array(piPackageInfoSchema),
+})
+    .passthrough();
+export const skillsSetEnabledRequestSchema = z
+    .object({
+    type: z.literal("skills_set_enabled_request"),
+    requestId: z.string(),
+    path: z.string(),
+    enabled: z.boolean(),
+})
+    .passthrough();
+export const skillsSetEnabledResponseSchema = z
+    .object({
+    type: z.literal("skills_set_enabled_response"),
+    requestId: z.string(),
+    ok: z.boolean(),
+    error: z.string().optional(),
+    message: z.string().optional(),
+    skills: z.array(skillInfoSchema),
+    packages: z.array(piPackageInfoSchema),
+})
+    .passthrough();
+/**
+ * Broadcast, no `requestId` — every connected client re-lists. `reason` is a plain string
+ * (`"mutation" | "external"` documented) so a future reason stays append-only, same idiom as
+ * `agent_timeline_reset`'s `reason`.
+ */
+export const skillsChangedSchema = z
+    .object({
+    type: z.literal("skills_changed"),
+    reason: z.string(),
+})
+    .passthrough();
+/**
+ * Base wire shape — used as the `sessionMessageSchema` union member (a `discriminatedUnion` entry
+ * must stay a `ZodObject`, so the xor-refine below wraps this one instead of replacing it).
+ */
+const skillsRemoveRequestShapeSchema = z
+    .object({
+    type: z.literal("skills_remove_request"),
+    requestId: z.string(),
+    path: z.string().optional(),
+    packageSource: z.string().optional(),
+})
+    .passthrough();
+/**
+ * Exactly one of `path` (a top-level skill: `settings_path`/symlink/plain directory) or
+ * `packageSource` (a whole `settings.json` `packages[]` entry) must be set — never both, never
+ * neither. A package-owned skill's own `path` is rejected daemon-side as `not_removable`; this
+ * schema only enforces the wire shape/xor, not daemon-side removability.
+ */
+export const skillsRemoveRequestSchema = skillsRemoveRequestShapeSchema.refine((v) => (v.path !== undefined) !== (v.packageSource !== undefined), { message: "exactly one of path or packageSource is required" });
+/**
+ * `stderr` is the spawned CLI's truncated (≤2048 bytes) stderr tail when the underlying `skills
+ * remove`/`pi remove` process failed; absent on success or on a pre-spawn domain error (e.g.
+ * `not_found`/`not_removable`). `ok`/`error` are domain fields, same idiom as `skills_list_response`.
+ */
+export const skillsRemoveResponseSchema = z
+    .object({
+    type: z.literal("skills_remove_response"),
+    requestId: z.string(),
+    ok: z.boolean(),
+    error: z.string().optional(),
+    message: z.string().optional(),
+    stderr: z.string().optional(),
+    skills: z.array(skillInfoSchema),
+    packages: z.array(piPackageInfoSchema),
+})
+    .passthrough();
+/** One engine's outcome inside an `ItemResult[]` list (used by `skills_update_all_response`). */
+export const itemResultSchema = z
+    .object({
+    target: z.string(),
+    ok: z.boolean(),
+    error: z.string().optional(),
+    stderr: z.string().optional(),
+})
+    .passthrough();
+export const skillsUpdateAllRequestSchema = z
+    .object({
+    type: z.literal("skills_update_all_request"),
+    requestId: z.string(),
+})
+    .passthrough();
+/** One `ItemResult` per engine (`agent-skills` via `skills update -g -y`, `pi-packages` via `pi update --extensions`); a mixed ok/failed `results` array is expected, not an overall failure. */
+export const skillsUpdateAllResponseSchema = z
+    .object({
+    type: z.literal("skills_update_all_response"),
+    requestId: z.string(),
+    ok: z.boolean(),
+    error: z.string().optional(),
+    message: z.string().optional(),
+    results: z.array(itemResultSchema),
+    skills: z.array(skillInfoSchema),
+    packages: z.array(piPackageInfoSchema),
+})
+    .passthrough();
+// ---------------------------------------------------------------------------
+// Skills preview/install (sprint-077/task-002). Client-side source classification lives in
+// `source-detect.ts`'s `detectSkillSource()` — the daemon always re-runs detection
+// authoritatively, so neither request below carries a client-sent `kind`. Reuses
+// `itemResultSchema`/`skillInfoSchema`/`piPackageInfoSchema` above.
+// ---------------------------------------------------------------------------
+/**
+ * One installable skill found inside a `skills_repo`/`local_path` preview (never package kinds —
+ * those answer `{ok:true, kind, skills: []}`, nothing to pick). `valid` means frontmatter had a
+ * name + description; `exists` means `~/.agents/skills/<sanitized-name>` is already present
+ * (drives the client's "Already installed — replace" checkbox).
+ */
+export const previewSkillSchema = z
+    .object({
+    name: z.string(),
+    description: z.string().optional(),
+    relPath: z.string(),
+    warnings: z.array(z.string()).optional(),
+    valid: z.boolean(),
+    exists: z.boolean(),
+})
+    .passthrough();
+export const skillsPreviewRequestSchema = z
+    .object({
+    type: z.literal("skills_preview_request"),
+    requestId: z.string(),
+    source: z.string(),
+})
+    .passthrough();
+/**
+ * `ok`/`error` are domain fields, same idiom as every other `skills_*` response. `kind` is the
+ * daemon's own `detect(source)` result (never the client's) and `source` echoes the request's
+ * `source` verbatim — both present even on a domain failure (e.g. `invalid_source`), so a client
+ * can still render what it tried against. `pi_npm`/`pi_git` always answer
+ * `{ok:true, kind, source, skills: []}` — package kinds install as a unit, nothing to pick.
+ */
+export const skillsPreviewResponseSchema = z
+    .object({
+    type: z.literal("skills_preview_response"),
+    requestId: z.string(),
+    ok: z.boolean(),
+    error: z.string().optional(),
+    message: z.string().optional(),
+    kind: z.string(),
+    source: z.string(),
+    skills: z.array(previewSkillSchema),
+})
+    .passthrough();
+/**
+ * `skills` is the picked skill names from a prior preview — meaningful for `skills_repo` only
+ * (ignored for `pi_npm`/`pi_git`, which install every skill the package ships; irrelevant for
+ * `local_path`, which registers the whole folder). `replace` resends an already-installed picked
+ * name instead of excluding it as `name_exists`.
+ */
+export const skillsInstallRequestSchema = z
+    .object({
+    type: z.literal("skills_install_request"),
+    requestId: z.string(),
+    source: z.string(),
+    skills: z.array(z.string()).optional(),
+    replace: z.boolean().optional(),
+})
+    .passthrough();
+/**
+ * One `ItemResult` per engine outcome — one entry for `pi_npm`/`pi_git`/`local_path`, one per
+ * picked name for `skills_repo` (e.g. a `name_exists` exclusion still gets its own `ItemResult`).
+ * `skills`/`packages` are the post-mutation list, same idiom as every other mutating `skills_*`
+ * response.
+ */
+export const skillsInstallResponseSchema = z
+    .object({
+    type: z.literal("skills_install_response"),
+    requestId: z.string(),
+    ok: z.boolean(),
+    error: z.string().optional(),
+    message: z.string().optional(),
+    results: z.array(itemResultSchema),
+    skills: z.array(skillInfoSchema),
+    packages: z.array(piPackageInfoSchema),
+})
+    .passthrough();
+// ===========================================================================
 // Extension UI (features/extension-ui-rpc.md) — additive, new in sprint-066
 // ===========================================================================
 /**
@@ -1263,6 +1509,19 @@ export const sessionMessageSchema = z.discriminatedUnion("type", [
     viewerSettingsSetRequestSchema,
     viewerSettingsSetResponseSchema,
     viewerSettingsUpdateSchema,
+    skillsListRequestSchema,
+    skillsListResponseSchema,
+    skillsSetEnabledRequestSchema,
+    skillsSetEnabledResponseSchema,
+    skillsChangedSchema,
+    skillsRemoveRequestShapeSchema,
+    skillsRemoveResponseSchema,
+    skillsUpdateAllRequestSchema,
+    skillsUpdateAllResponseSchema,
+    skillsPreviewRequestSchema,
+    skillsPreviewResponseSchema,
+    skillsInstallRequestSchema,
+    skillsInstallResponseSchema,
     agentUiRequestSchema,
     agentUiResolvedSchema,
     agentUiRespondRequestSchema,

package/dist/source-detect.d.ts

@@ -0,0 +1,18 @@
+/** One of the four installable source kinds the daemon recognizes; `null` from
+ * `detectSkillSource` means "anything else" (`invalid_source` once the server rejects it). */
+export type SkillSourceKind = "pi_npm" | "pi_git" | "skills_repo" | "local_path";
+export interface DetectedSkillSource {
+    kind: SkillSourceKind;
+    /** Whitespace-trimmed input, unchanged otherwise. Further parsing (e.g. splitting a
+     * `/tree/<ref>/<path>` subpath out of a `skills_repo` URL, or expanding a `~` in a
+     * `local_path`) is each consumer's own job — this classifier never reaches into the
+     * filesystem or re-derives host state. */
+    normalized: string;
+}
+/**
+ * Classify a skill install source string. Returns `null` for anything that isn't one of the four
+ * recognized kinds (relative paths, bare words, non-git `http(s)` file URLs, empty input) — the
+ * caller renders that as "Unrecognized" / the daemon answers `invalid_source`.
+ */
+export declare function detectSkillSource(input: string): DetectedSkillSource | null;
+//# sourceMappingURL=source-detect.d.ts.map

package/dist/source-detect.js

@@ -0,0 +1,61 @@
+// Pure, zero-dependency classifier for a skill install source string
+// (swe/architecture/pi-resource-management.md § Source kinds). Shared between the web client
+// (live label while the user types a source) and the daemon (`source-detect.ts` re-export per
+// the architecture doc's component table) — the **daemon's** classification is always
+// authoritative; a client-sent `kind` on the wire is ignored (`skills_preview_request` /
+// `skills_install_request` carry only `source`, never `kind`).
+//
+// No filesystem access here: `local_path` is detected purely syntactically (absolute or
+// `~`-prefixed); whether the directory actually exists on the daemon host is checked server-side.
+const NPM_SOURCE_RE = /^npm:\S+$/;
+const GIT_PREFIX_SOURCE_RE = /^git:\S+$/;
+const SSH_URL_RE = /^ssh:\/\/\S+$/;
+/** `git@host:owner/repo[.git]` scp-like syntax. */
+const SCP_LIKE_RE = /^git@[^\s:/]+:\S+$/;
+/** `http(s)://[www.]<github|gitlab>.com/<anything>` — covers plain repo URLs and
+ * `/tree/<ref>/<path>` subpaths alike; the subpath is opaque here. */
+const GIT_HOST_URL_RE = /^https?:\/\/(?:[^\s/]*\.)?(?:github|gitlab)\.com\/\S+$/i;
+/** Any scheme'd URL ending in `.git` (self-hosted Git forges, bare `git://`, etc). */
+const GIT_SUFFIX_URL_RE = /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\/\S+\.git$/;
+const URL_SCHEME_RE = /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//;
+/** GitHub/GitLab slug segment: alnum, `.`/`_`/`-` in the middle, never a leading/trailing one. */
+const OWNER_REPO_SEGMENT = "[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?";
+/** `owner/repo` or `owner/repo@skill` — exactly one slash, so a deeper or `./`/`../`-prefixed
+ * relative path never matches (those fall through to `null`). */
+const OWNER_REPO_RE = new RegExp(`^${OWNER_REPO_SEGMENT}/${OWNER_REPO_SEGMENT}(?:@${OWNER_REPO_SEGMENT})?$`);
+/**
+ * Classify a skill install source string. Returns `null` for anything that isn't one of the four
+ * recognized kinds (relative paths, bare words, non-git `http(s)` file URLs, empty input) — the
+ * caller renders that as "Unrecognized" / the daemon answers `invalid_source`.
+ */
+export function detectSkillSource(input) {
+    const normalized = input.trim();
+    if (normalized.length === 0) {
+        return null;
+    }
+    if (NPM_SOURCE_RE.test(normalized)) {
+        return { kind: "pi_npm", normalized };
+    }
+    if (GIT_PREFIX_SOURCE_RE.test(normalized)) {
+        return { kind: "pi_git", normalized };
+    }
+    if (normalized === "~" || normalized.startsWith("~/") || normalized.startsWith("/")) {
+        return { kind: "local_path", normalized };
+    }
+    if (SCP_LIKE_RE.test(normalized) ||
+        SSH_URL_RE.test(normalized) ||
+        GIT_HOST_URL_RE.test(normalized) ||
+        GIT_SUFFIX_URL_RE.test(normalized)) {
+        return { kind: "skills_repo", normalized };
+    }
+    if (URL_SCHEME_RE.test(normalized)) {
+        // Has a URL scheme but isn't a recognized git host or `*.git` suffix — e.g. a plain file
+        // link. Explicitly not installable, never falls through to the owner/repo check below.
+        return null;
+    }
+    if (OWNER_REPO_RE.test(normalized)) {
+        return { kind: "skills_repo", normalized };
+    }
+    return null;
+}
+//# sourceMappingURL=source-detect.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@av-pi-studio/protocol",
-  "version": "0.0.110",
+  "version": "0.0.112",
   "files": [
     "dist",
     "!dist/**/*.map",