@av-pi-studio/server 0.0.111 → 0.0.113

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -63,6 +63,8 @@ import { registerOrchestrationHandlers } from "./orchestration-rpc.js";
63
63
  import { ExtensionsService } from "../extensions/extensions-service.js";
64
64
  import { registerExtensionsHandlers } from "../extensions/extensions-rpc.js";
65
65
  import { registerViewerSettingsHandlers } from "../viewers/viewer-settings-rpc.js";
66
+ import { ResourceService } from "../resources/resource-service.js";
67
+ import { registerSkillsHandlers } from "../resources/skills-rpc.js";
66
68
  import { SERVER_FEATURES, helloSchema, serverInfoPayloadSchema, statusSchema, } from "@av-pi-studio/protocol";
67
69
  import { connectRelay } from "./relay-transport.js";
68
70
  function resolveHome(opts) {
@@ -422,6 +424,17 @@ export function startDaemon(opts) {
422
424
  getActiveSessions,
423
425
  logger: logger.child({ component: "viewer-settings" }),
424
426
  });
427
+ // ── Pi resource management: skills + Pi packages (sprint-075/077) ────────────
428
+ const resourcesLogger = logger.child({ component: "resources" });
429
+ const resourceService = new ResourceService({
430
+ config,
431
+ fileWatchService,
432
+ broadcast,
433
+ getActiveSessions,
434
+ logger: resourcesLogger,
435
+ studioHome: home,
436
+ });
437
+ registerSkillsHandlers(registry, { service: resourceService, logger: resourcesLogger });
425
438
  // ── Provider auth: remote-driven Pi login flows (sprint-055) ─────────────────
426
439
  const providerAuthLogger = logger.child({ component: "provider-auth" });
427
440
  const providerAuthRuntime = createPiAuthRuntime(resolvePiAuthPaths(config));
@@ -28,9 +28,13 @@ export interface InstallSpawn {
28
28
  command: string[];
29
29
  env: Record<string, string>;
30
30
  timeoutMs: number;
31
+ /** Working directory for the child; omitted = the daemon's own cwd. */
32
+ cwd?: string;
31
33
  }): Promise<{
32
34
  exitCode: number | null;
33
35
  stderr: string;
36
+ /** Tail of stdout (bounded). Only the `skills` CLI needs it — it reports failures there. */
37
+ stdout?: string;
34
38
  timedOut?: boolean;
35
39
  }>;
36
40
  }
@@ -5,13 +5,15 @@ import { SERVER_VERSION } from "./curated-packs.js";
5
5
  import { effectivePiHomeKey, loadExtensionsState, saveExtensionsState, } from "./extensions-state.js";
6
6
  const INSTALL_TIMEOUT_MS = 180_000;
7
7
  const STDERR_TAIL_MAX = 2048;
8
+ const STDOUT_TAIL_MAX = 16_384;
8
9
  /** The production seam: spawns `command`, captures stderr (unbounded here — the executor bounds
9
10
  * what it stores), and kills the whole process tree on timeout rather than just the direct child,
10
11
  * so a `pi install` that itself forked a build/postinstall step doesn't linger. */
11
- export const defaultInstallSpawn = ({ command, env, timeoutMs }) => new Promise((resolve, reject) => {
12
+ export const defaultInstallSpawn = ({ command, env, timeoutMs, cwd }) => new Promise((resolve, reject) => {
12
13
  const [bin, ...args] = command;
13
- const child = spawn(bin, args, { env, stdio: ["ignore", "ignore", "pipe"] });
14
+ const child = spawn(bin, args, { env, cwd, stdio: ["ignore", "pipe", "pipe"] });
14
15
  let stderr = "";
16
+ let stdout = "";
15
17
  let timedOut = false;
16
18
  let settled = false;
17
19
  const timer = setTimeout(() => {
@@ -24,6 +26,10 @@ export const defaultInstallSpawn = ({ command, env, timeoutMs }) => new Promise(
24
26
  child.stderr?.on("data", (chunk) => {
25
27
  stderr += chunk.toString("utf8");
26
28
  });
29
+ // Drained (an unread pipe would block the child) but kept bounded: only the tail matters.
30
+ child.stdout?.on("data", (chunk) => {
31
+ stdout = (stdout + chunk.toString("utf8")).slice(-STDOUT_TAIL_MAX);
32
+ });
27
33
  child.on("error", (err) => {
28
34
  if (settled)
29
35
  return;
@@ -36,7 +42,7 @@ export const defaultInstallSpawn = ({ command, env, timeoutMs }) => new Promise(
36
42
  return;
37
43
  settled = true;
38
44
  clearTimeout(timer);
39
- resolve({ exitCode: code, stderr, timedOut });
45
+ resolve({ exitCode: code, stderr, stdout, timedOut });
40
46
  });
41
47
  });
42
48
  /** Maps a spawn result (non-zero exit / timeout) or a caught throw to the reason taxonomy.
@@ -0,0 +1,26 @@
1
+ import { DefaultPackageManager, loadSkillsFromDir, SettingsManager } from "@earendil-works/pi-coding-agent";
2
+ import type { LoadSkillsResult, PackageSource } from "@earendil-works/pi-coding-agent";
3
+ /**
4
+ * The single importer of Pi's `SettingsManager`, `DefaultPackageManager`, and `loadSkillsFromDir`
5
+ * (swe/architecture/pi-resource-management.md § Public contract — `pi-sdk.ts`). A Pi bump has
6
+ * exactly one place to check for this feature's symbols. Mirrors the in-process-import precedent
7
+ * in `agent/provider-auth/pi-auth-runtime.ts`, except this one imports eagerly: the daemon already
8
+ * pays for `@earendil-works/pi-coding-agent`'s module graph via
9
+ * `agent/providers/pi/session-hydration.ts` (`SessionManager`), so there is no boot-resilience
10
+ * reason to defer it here.
11
+ */
12
+ export { loadSkillsFromDir };
13
+ export type { LoadSkillsResult, PackageSource };
14
+ /** Pi's two resource managers for one `agentDir`, freshly constructed per operation (never
15
+ * cached across calls — `swe/architecture/pi-resource-management.md` tenet 1: no cache). */
16
+ export interface PiResources {
17
+ /** Reloaded from disk — reflects the current `<agentDir>/settings.json` and
18
+ * `<cwd>/.pi/settings.json`, not whatever a prior instance observed. */
19
+ settings: SettingsManager;
20
+ packages: DefaultPackageManager;
21
+ }
22
+ /** Construct a fresh `SettingsManager`/`DefaultPackageManager` pair for `agentDir`, reloading
23
+ * settings from disk first so every caller sees the current file, never a stale in-memory copy
24
+ * from an earlier `SettingsManager.create()` elsewhere in the process. */
25
+ export declare function openPiResources(agentDir: string, cwd: string): Promise<PiResources>;
26
+ //# sourceMappingURL=pi-sdk.d.ts.map
@@ -0,0 +1,21 @@
1
+ import { DefaultPackageManager, loadSkillsFromDir, SettingsManager, } from "@earendil-works/pi-coding-agent";
2
+ /**
3
+ * The single importer of Pi's `SettingsManager`, `DefaultPackageManager`, and `loadSkillsFromDir`
4
+ * (swe/architecture/pi-resource-management.md § Public contract — `pi-sdk.ts`). A Pi bump has
5
+ * exactly one place to check for this feature's symbols. Mirrors the in-process-import precedent
6
+ * in `agent/provider-auth/pi-auth-runtime.ts`, except this one imports eagerly: the daemon already
7
+ * pays for `@earendil-works/pi-coding-agent`'s module graph via
8
+ * `agent/providers/pi/session-hydration.ts` (`SessionManager`), so there is no boot-resilience
9
+ * reason to defer it here.
10
+ */
11
+ export { loadSkillsFromDir };
12
+ /** Construct a fresh `SettingsManager`/`DefaultPackageManager` pair for `agentDir`, reloading
13
+ * settings from disk first so every caller sees the current file, never a stale in-memory copy
14
+ * from an earlier `SettingsManager.create()` elsewhere in the process. */
15
+ export async function openPiResources(agentDir, cwd) {
16
+ const settings = SettingsManager.create(cwd, agentDir);
17
+ await settings.reload();
18
+ const packages = new DefaultPackageManager({ cwd, agentDir, settingsManager: settings });
19
+ return { settings, packages };
20
+ }
21
+ //# sourceMappingURL=pi-sdk.js.map
@@ -0,0 +1,197 @@
1
+ import { type ItemResult, type PiPackageInfo, type PreviewSkill, type SkillInfo } from "@av-pi-studio/protocol";
2
+ import type { PersistedConfig } from "../config/daemon-config.js";
3
+ import { type InstallSpawn } from "../extensions/sync-executor.js";
4
+ import type { FileWatchService } from "../files/file-watch-service.js";
5
+ import type { Logger } from "../logging/logger.js";
6
+ import type { Session } from "../ws/session.js";
7
+ import { type SpawnOutcome } from "./spawn-runner.js";
8
+ export interface ResourceServiceResult {
9
+ ok: boolean;
10
+ /** Free-form domain error string (e.g. `"settings_unreadable"`, `"not_found"`, or a descriptive
11
+ * malformed-request message) — never thrown as an `rpc_error`. */
12
+ error?: string;
13
+ skills: SkillInfo[];
14
+ packages: PiPackageInfo[];
15
+ }
16
+ export interface PreviewResult {
17
+ ok: boolean;
18
+ error?: string;
19
+ message?: string;
20
+ kind: string;
21
+ source: string;
22
+ skills: PreviewSkill[];
23
+ }
24
+ export interface InstallResult {
25
+ ok: boolean;
26
+ error?: string;
27
+ results: ItemResult[];
28
+ skills: SkillInfo[];
29
+ packages: PiPackageInfo[];
30
+ }
31
+ export interface ResourceServiceDeps {
32
+ config: PersistedConfig;
33
+ fileWatchService: FileWatchService;
34
+ broadcast: (sessions: Iterable<Session>, message: unknown) => void;
35
+ getActiveSessions: () => Iterable<Session>;
36
+ logger?: Logger;
37
+ /** Overridable for tests; defaults to 500 ms (architecture doc § Queue, watcher, broadcast). */
38
+ externalDebounceMs?: number;
39
+ /** Injectable process seam for queued mutations (`runSpawn`); defaults to
40
+ * `defaultInstallSpawn` (`extensions/sync-executor.ts`). Tests pass a fake. */
41
+ spawn?: InstallSpawn;
42
+ /** `$PI_STUDIO_HOME` — root of the preview scratch directory (`<studioHome>/tmp/preview-*`,
43
+ * task-003). Defaults to `process.env.PI_STUDIO_HOME ?? ~/.pi-studio`, mirroring
44
+ * `daemon/bootstrap.ts`'s own `resolveHome`. */
45
+ studioHome?: string;
46
+ }
47
+ interface ResourceCtx {
48
+ agentDir: string;
49
+ /** `$HOME` — `~/.agents/skills` resolves from this, not `agentDir` (architecture doc § Ground
50
+ * truth); also `SettingsManager`'s `cwd` (`skill-catalog.ts`'s own `BuildCatalogContext.home`
51
+ * doc). */
52
+ home: string;
53
+ agentsSkillsDir: string;
54
+ lockPath: string;
55
+ }
56
+ export declare class ResourceService {
57
+ private readonly config;
58
+ private readonly fileWatchService;
59
+ private readonly broadcastFn;
60
+ private readonly getActiveSessions;
61
+ private readonly logger;
62
+ private readonly externalDebounceMs;
63
+ private readonly spawnFn;
64
+ /** `$PI_STUDIO_HOME` — preview scratch root (task-003). */
65
+ private readonly studioHome;
66
+ /** FIFO for preview/install/remove/update_all (tasks 004/005/077) — separate from
67
+ * `ExtensionsService`'s own sync mutex; `list`/`setEnabled` bypass it entirely (D21,
68
+ * architecture doc § Queue, watcher, broadcast). */
69
+ private readonly queue;
70
+ private watcherStarted;
71
+ private externalTimer;
72
+ /** Timestamp (ms) until which an incoming fs event is attributed to this service's own last
73
+ * write, not an external edit — see {@link markOwnWrite} / {@link handleFsEvent}. */
74
+ private ownWriteUntil;
75
+ constructor(deps: ResourceServiceDeps);
76
+ list(): Promise<ResourceServiceResult>;
77
+ /**
78
+ * `skills_preview_request` (architecture doc § Behavior & algorithms "Preview", task-003):
79
+ * stateless — `pi_npm`/`pi_git` answer `{kind, skills: []}` immediately (nothing to pick);
80
+ * `local_path` scans the host folder in place; `skills_repo` shallow-clones into a scratch dir
81
+ * under `<studioHome>/tmp/preview-*`, removed in `finally` regardless of outcome. Queued behind
82
+ * {@link queue} alongside install/remove/update_all (architecture doc § Queue, watcher,
83
+ * broadcast), but — unlike {@link enqueueMutation} — never writes to `settings.json`, so it
84
+ * skips `markOwnWrite`/re-list/broadcast entirely.
85
+ */
86
+ preview(source: string): Promise<PreviewResult>;
87
+ private previewLocked;
88
+ /** `skills_repo`: shallow clone into a scratch dir, scan it (honouring a `/tree/<ref>/<path>`
89
+ * subpath), then remove the scratch dir unconditionally. */
90
+ private previewSkillsRepo;
91
+ /** Scans `root` with Pi's own `loadSkillsFromDir`, turning both its loaded `Skill`s (always
92
+ * `valid: true` — the loader only returns an entry once description validation passes) and its
93
+ * description-less diagnostics (a `SKILL.md` that failed to load at all — `valid: false`) into
94
+ * one flat `PreviewSkill[]`, so an invalid skill still gets its own row instead of silently
95
+ * disappearing (task-003 acceptance #1). */
96
+ private buildPreviewResult;
97
+ setEnabled(path: string, enabled: boolean): Promise<ResourceServiceResult>;
98
+ /**
99
+ * `skills_install_request` (architecture doc § Behavior & algorithms "Install", tasks
100
+ * 004/005): dispatches on the daemon's own authoritative `detectSkillSource(source)` — a
101
+ * client-sent `kind` is never trusted. Queued behind {@link enqueueMutation} alongside
102
+ * remove/update_all; `markOwnWrite`/re-list/broadcast are handled there, not here.
103
+ */
104
+ install(source: string, picked?: string[], replace?: boolean): Promise<InstallResult>;
105
+ private installSource;
106
+ /** `pi_npm`/`pi_git` (task-004, R3/R8): spawn bundled `pi install <source>` as a unit, then one
107
+ * locked write upgrading the matched settings entry to skills-only object form
108
+ * (`extensions: [], prompts: [], themes: []`) — any pre-existing `skills` filter on that entry
109
+ * survives untouched (task-001 spike: `addSourceToSettings` only ever rewrites `source`). */
110
+ private installPiPackage;
111
+ /** `skills_repo` (task-005): picked names already present under `agentsSkillsDir` without
112
+ * `replace` are excluded as `name_exists`, never spawned; the rest go through one `skills add
113
+ * <url> -g -a pi -y -s <picked…>` spawn, each name's own result decided by a post-spawn
114
+ * `<agentsSkillsDir>/<sanitized>/SKILL.md` existence check (D18's lock file is `skills`'s own
115
+ * bookkeeping, never hand-read here for the outcome). */
116
+ private installSkillsRepo;
117
+ /** `local_path` (task-005): nothing copied — `settings.skills` gains one bare `<absPath>`
118
+ * entry, de-duplicated against any existing entry with the same stripped form (bare or
119
+ * `±`-prefixed).
120
+ *
121
+ * Deviation from the architecture doc's literal `"+" + absPath` pseudocode, found by code
122
+ * inspection of the installed `@earendil-works/pi-coding-agent` 1.4.0
123
+ * (`package-manager.js`'s `resolveLocalEntries`/`isPattern`/`applyPatterns`): a `±`-prefixed
124
+ * `settings.skills` entry is parsed as an *override pattern* that only flips the enabled state
125
+ * of a path already discovered via a *plain* (unprefixed) entry or auto-discovery — it is
126
+ * never itself scanned for resources. A `+<absPath>` entry with no matching plain entry
127
+ * resolves zero files. A bare entry, by contrast, goes through `resolveLocalEntries`'s `plain`
128
+ * branch (`collectFilesFromPaths`), which is exactly what the existing `remove`'s own
129
+ * `settings_path` handling above already assumes (a bare directory entry, e.g. the
130
+ * `removes a settings_path entry` test fixture). */
131
+ private installLocalPath;
132
+ /**
133
+ * `skills_remove_request` (architecture doc § Behavior & algorithms "Remove", D9/D20): removes
134
+ * one top-level skill the way its origin requires, or spawns `pi remove` for a whole package.
135
+ * Queued behind {@link enqueueMutation} alongside install/update_all — `markOwnWrite`/re-list/
136
+ * broadcast are handled there, not here.
137
+ */
138
+ remove(target: {
139
+ path: string;
140
+ } | {
141
+ packageSource: string;
142
+ }): Promise<{
143
+ ok: boolean;
144
+ error?: string;
145
+ stderr?: string;
146
+ } & ResourceServiceResult>;
147
+ /** `remove({path})` — settings-path entry, symlink, `skills`-CLI-tracked `agents_dir` skill, or
148
+ * a plain directory under `agent_dir`/`agents_dir` whose realpath must stay inside that origin
149
+ * root. Never follows symlinks; never deletes a package row's files (D9). */
150
+ private removeByPath;
151
+ /** `remove({packageSource})` — spawns bundled `pi remove <source>`; Pi owns deleting the
152
+ * package's install root and removing its `packages[]` entry. */
153
+ private removePackage;
154
+ /**
155
+ * `skills_update_all_request` (architecture doc § Behavior & algorithms "Update all", R5): one
156
+ * queued operation spawning `skills update -g -y` then `pi update --extensions` in sequence —
157
+ * a failure in the first never skips the second; `ok` is true only when both succeed.
158
+ */
159
+ updateAll(): Promise<{
160
+ ok: boolean;
161
+ results: ItemResult[];
162
+ } & ResourceServiceResult>;
163
+ private updateAgentSkills;
164
+ private updatePiPackages;
165
+ /** Runs `command` through the injected spawn seam, bounding and redacting its stderr tail
166
+ * (architecture doc § Spawn environment, § Redaction & logging). Shared by every queued
167
+ * mutation (install/remove/update_all — tasks 004/005/077); exposed as a method (rather than
168
+ * requiring every caller to thread `this.spawnFn` through) so operations only need `this`. */
169
+ runSpawn(command: string[], env: Record<string, string>, timeoutMs: number, cwd?: string): Promise<SpawnOutcome>;
170
+ /**
171
+ * FIFO-queues one mutating operation behind {@link queue}, then runs the tail every mutation
172
+ * shares: structured logging (`{op, kind, source, outcome, durationMs}`, warn with the redacted
173
+ * stderr tail on failure), re-list, and `skills_changed("mutation")` broadcast — always, so a
174
+ * failed spawn that still partially touched `settings.json` is reflected (architecture doc
175
+ * § Behavior & algorithms "Install", § Redaction & logging). `fn`'s own `ok`/`error` (the
176
+ * operation's outcome) wins over the re-list's, except when the re-list itself fails (e.g. a
177
+ * `settings.json` that became unreadable mid-operation), which then takes over as the surfaced
178
+ * error — `skills`/`packages` always come from the fresh re-list.
179
+ */
180
+ enqueueMutation<T extends {
181
+ ok: boolean;
182
+ error?: string;
183
+ stderr?: string;
184
+ }>(op: string, kind: string, source: string, fn: (ctx: ResourceCtx) => Promise<T>): Promise<T & ResourceServiceResult>;
185
+ private loadResult;
186
+ /** Started on the first `skills_*` RPC, lives for the daemon's lifetime (architecture doc
187
+ * § Queue, watcher, broadcast) — never torn down by this service itself. */
188
+ private ensureWatcher;
189
+ /** Call immediately before the mutating `SettingsManager` setter so the fold window covers the
190
+ * resulting disk write and the watcher's own event latency (`FileWatchService`'s internal
191
+ * coalescing plus this service's own debounce below). */
192
+ private markOwnWrite;
193
+ private handleFsEvent;
194
+ private broadcastChanged;
195
+ }
196
+ export {};
197
+ //# sourceMappingURL=resource-service.d.ts.map