@emiliosp/pi-maestro 0.9.2 → 0.9.3

package/ROADMAP.md

@@ -76,6 +76,25 @@ All 5 `acceptance criteria` passed through independent inspection of the written
 
 ## Now
 
+### R-06: Check subagent extensions at activation
+
+#### Objective
+
+Make `pi-subagents` availability problems visible before a `builder` or `verifier` `run` starts.
+
+#### Implementation status
+
+Activation now requires a successful version 1 `ping` reply from the parent `pi-subagents` extension within 2000 ms. The check does not start an agent. All 7 `acceptance criteria` passed with no `verifier` `findings`; the workflow reached `candidate-ready`.
+
+A later integration test requested by the `owner` directly checks the environment check's failed-reply error. This test addition is outside the completed independent verification.
+
+[Specification](.specs/20261013-194407-check-pi-subagents-availability-with-ping-at-activation/spec.md).
+
+#### Completed when
+
+Unavailable `pi-subagents` prevents activation. The error identifies the problem.
+
+
 ## Next
 
 ## Later
@@ -104,16 +123,6 @@ When criteria are removed during `spec` preparation or revision, renumber the re
 
 The `spec` and its current references use consistent numbering.
 
-### R-06: Check subagent extensions at activation
-
-#### Objective
-
-Make extension availability problems visible before a `builder` or `verifier` `run` starts. Activation already checks agent launch requirements, so first identify any missing extension checks.
-
-#### Completed when
-
-Unavailable required subagent extensions prevent activation. The error identifies the problem.
-
 ### R-07: Guide initial configuration
 
 #### Objective

package/extensions/maestro.ts

@@ -83,7 +83,7 @@ export default (pi: ExtensionAPI): void => {
       }
 
       try {
-        await assertEnvironment(context);
+        await assertEnvironment({ context, piEventsBus: pi.events });
         const config = await loadConfiguration(context.cwd);
 
         maestroSessionState.activate();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emiliosp/pi-maestro",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "description": "A spec-driven multiagent development workflow for Pi.",
   "license": "MIT",
   "type": "module",

package/src/maestro/checks/assertEnvironment.ts

@@ -3,12 +3,26 @@
  * Used: When the owner activates Maestro mode.
  */
 
+import { randomUUID } from 'node:crypto';
 import { realpath } from 'node:fs/promises';
-import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from '@earendil-works/pi-coding-agent';
 import { resolveSubagentLaunchContract } from 'pi-subagents/preflight';
 import { loadConfiguration } from '#config/loadConfiguration.ts';
 import { AGENTS } from '#config/schema.ts';
 
+export const SUBAGENT_PING = {
+  REQUEST_EVENT: 'subagents:rpc:v1:request',
+  REPLY_EVENT_PREFIX: 'subagents:rpc:v1:reply:',
+  VERSION: 1,
+  METHOD: 'ping',
+  TIMEOUT_MS: 2000,
+  INSTALLATION_ERROR:
+    'Maestro flow requires pi-subagents installed in the Pi environment.',
+} as const;
+
 const getErrorMessage = (error: unknown): string =>
   error instanceof Error ? error.message : String(error);
 
@@ -76,9 +90,81 @@ async function assertAgentsAvailable(projectRoot: string): Promise<void> {
   }
 }
 
-export async function assertEnvironment(
-  context: ExtensionContext,
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const isReplyWithRequestId = (
+  reply: unknown,
+): reply is Record<string, unknown> & { requestId: string } =>
+  isRecord(reply) && typeof reply.requestId === 'string';
+
+type SuccessfulPingReply = {
+  version: typeof SUBAGENT_PING.VERSION;
+  requestId: string;
+  method: typeof SUBAGENT_PING.METHOD;
+  success: true;
+  data: { version: typeof SUBAGENT_PING.VERSION };
+};
+
+function assertSuccessfulPingReply(
+  reply: unknown,
+): asserts reply is SuccessfulPingReply {
+  if (
+    !isReplyWithRequestId(reply) ||
+    reply.version !== SUBAGENT_PING.VERSION ||
+    reply.method !== SUBAGENT_PING.METHOD ||
+    reply.success !== true ||
+    !isRecord(reply.data) ||
+    reply.data.version !== SUBAGENT_PING.VERSION
+  ) {
+    throw new Error('Unsuccessful or invalid pi-subagents ping reply.');
+  }
+}
+
+async function assertSubagentsRespond(
+  piEventsBus: ExtensionAPI['events'],
 ): Promise<void> {
+  const requestId = randomUUID();
+  const { promise, resolve, reject } = Promise.withResolvers<unknown>();
+
+  const unsubscribe = piEventsBus.on(
+    `${SUBAGENT_PING.REPLY_EVENT_PREFIX}${requestId}`,
+    (reply) => {
+      if (isReplyWithRequestId(reply) && reply.requestId !== requestId) {
+        return;
+      }
+
+      resolve(reply);
+    },
+  );
+
+  const timeout = setTimeout(
+    () => reject(new Error('Pi-subagents ping timed out after 2000 ms.')),
+    SUBAGENT_PING.TIMEOUT_MS,
+  );
+
+  try {
+    piEventsBus.emit(SUBAGENT_PING.REQUEST_EVENT, {
+      version: SUBAGENT_PING.VERSION,
+      requestId,
+      method: SUBAGENT_PING.METHOD,
+    });
+    assertSuccessfulPingReply(await promise);
+  } finally {
+    clearTimeout(timeout);
+    unsubscribe();
+  }
+}
+
+type AssertEnvironmentInput = {
+  context: ExtensionContext;
+  piEventsBus: ExtensionAPI['events'];
+};
+
+export async function assertEnvironment({
+  context,
+  piEventsBus,
+}: AssertEnvironmentInput): Promise<void> {
   const projectRoot = await getProjectRoot(context);
 
   try {
@@ -92,4 +178,13 @@ export async function assertEnvironment(
   const config = await getActivationConfiguration(projectRoot);
 
   assertModelsAvailable({ context, config });
+
+  try {
+    await assertSubagentsRespond(piEventsBus);
+  } catch (error) {
+    throw new Error(
+      `${SUBAGENT_PING.INSTALLATION_ERROR} ${getErrorMessage(error)}`,
+      { cause: error },
+    );
+  }
 }