@aexol/spectral 0.9.167 → 0.9.170

package/dist/agent/agents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../src/agent/agents.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC;AACrD,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,UAAU,CAAC;AAC/C,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;IACrC,QAAQ,EAAE,MAAM,CAAC;CAClB;AACD,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAyDD,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAO3E;AACD;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC,yEAAyE;IACzE,YAAY,EAAE,IAAI,CAAC;IACnB,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG;IACF,YAAY,EAAE,KAAK,CAAC;IACpB,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,wBAAsB,kBAAkB,CAAC,IAAI,EAAE;IAC7C,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAAC,uBAAuB,CAAC,CA8FnC;AAkBD,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,UAAU,EACjB,QAAQ,CAAC,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,MAAM,GACd,oBAAoB,CAkBtB;AACD,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,MAAM,EACX,KAAK,GAAE,UAAmB,EAC1B,QAAQ,CAAC,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,MAAM,GACd,WAAW,GAAG,IAAI,CAepB;AACD;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CACzC,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACvC,GAAG,EAAE,MAAM,EACX,QAAQ,CAAC,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,MAAM,GACd,WAAW,GAAG,IAAI,CAgBpB;AACD;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,YAAY,EAAE,IAAI,CAChB,WAAW,EACX,MAAM,GAAG,aAAa,GAAG,cAAc,GAAG,OAAO,GAAG,QAAQ,CAC7D,GAAG,IAAI,GACP,MAAM,GAAG,SAAS,CAQpB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,IAAI,CACT,WAAW,EACX,MAAM,GAAG,aAAa,GAAG,cAAc,GAAG,OAAO,GAAG,QAAQ,CAC7D,GAAG,IAAI,GACP,MAAM,CAcR"}
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../src/agent/agents.ts"],"names":[],"mappings":"AAUA,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC;AACrD,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,UAAU,CAAC;AAC/C,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;IACrC,QAAQ,EAAE,MAAM,CAAC;CAClB;AACD,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAyDD,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAO3E;AACD;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC,yEAAyE;IACzE,YAAY,EAAE,IAAI,CAAC;IACnB,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG;IACF,YAAY,EAAE,KAAK,CAAC;IACpB,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,wBAAsB,kBAAkB,CAAC,IAAI,EAAE;IAC7C,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAAC,uBAAuB,CAAC,CA2EnC;AAkBD,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,UAAU,EACjB,QAAQ,CAAC,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,MAAM,GACd,oBAAoB,CAkBtB;AACD,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,MAAM,EACX,KAAK,GAAE,UAAmB,EAC1B,QAAQ,CAAC,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,MAAM,GACd,WAAW,GAAG,IAAI,CAepB;AACD;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CACzC,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACvC,GAAG,EAAE,MAAM,EACX,QAAQ,CAAC,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,MAAM,GACd,WAAW,GAAG,IAAI,CAgBpB;AACD;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,YAAY,EAAE,IAAI,CAChB,WAAW,EACX,MAAM,GAAG,aAAa,GAAG,cAAc,GAAG,OAAO,GAAG,QAAQ,CAC7D,GAAG,IAAI,GACP,MAAM,GAAG,SAAS,CAQpB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,IAAI,CACT,WAAW,EACX,MAAM,GAAG,aAAa,GAAG,cAAc,GAAG,OAAO,GAAG,QAAQ,CAC7D,GAAG,IAAI,GACP,MAAM,CAcR"}

package/dist/agent/agents.js

@@ -2,6 +2,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import chalk from "chalk";
 import { getAgentDir, parseFrontmatter } from "../sdk/coding-agent/index.js";
+import { classifyGraphqlError, createBackendClient, graphqlErrorMessage, scalars, } from "../generated/graphql-client.js";
 function loadAgentsFromDir(dir, source) {
     const agents = [];
     if (!fs.existsSync(dir))
@@ -70,48 +71,25 @@ export async function refreshCloudAgents(opts) {
     let refresh;
     refresh = (async () => {
         try {
-            const response = await fetch(`${opts.backendUrl.replace(/\/$/, "")}/graphql`, {
-                method: "POST",
-                headers: {
-                    "content-type": "application/json",
-                    authorization: `Bearer ${opts.machineJwt}`,
-                    "x-team-id": teamId,
-                },
-                body: JSON.stringify({
-                    query: `query CloudAgents($teamId: ID!) { agents(teamId: $teamId) { name description systemPrompt model mode scope } }`,
-                    variables: { teamId },
-                }),
+            const client = createBackendClient({
+                backendUrl: opts.backendUrl,
+                machineJwt: opts.machineJwt,
+                teamId,
             });
-            // HTTP 401/403: the machine JWT was rejected outright (expired,
-            // revoked, or signed with a stale secret). Surface as auth-rejected so
-            // the caller can trigger a forced re-registration instead of looping
-            // on the same dead token.
-            if (response.status === 401 || response.status === 403) {
-                const reason = `Cloud agents: backend rejected machine JWT (HTTP ${response.status})`;
-                console.warn(reason);
-                return { authRejected: true, reason };
-            }
-            if (!response.ok) {
-                console.warn(`Cloud agents: backend returned HTTP ${response.status}`);
-                return { authRejected: false, count: 0 };
-            }
-            const payload = (await response.json());
-            // GraphQL commonly returns 200 with an `errors` array when auth fails
-            // (e.g. "Authentication required", "Not authorized for this team").
-            // Treat any auth-flavored error as auth-rejected so the caller can
-            // recover; other GraphQL errors are non-fatal (no agents loaded).
-            if (payload.errors && payload.errors.length > 0) {
-                const msg = payload.errors.map((e) => e.message ?? "").join("; ");
-                const looksLikeAuth = /authentication required|not authorized|unauthor/i.test(msg);
-                const reason = `Cloud agents: backend rejected machine JWT (${msg})`;
-                if (looksLikeAuth) {
-                    console.warn(reason);
-                    return { authRejected: true, reason };
-                }
-                console.warn(reason);
-                return { authRejected: false, count: 0 };
-            }
-            const fetched = payload.data?.agents ?? [];
+            const result = await client("query", { scalars })({
+                agents: [
+                    { teamId },
+                    {
+                        name: true,
+                        description: true,
+                        systemPrompt: true,
+                        model: true,
+                        mode: true,
+                        scope: true,
+                    },
+                ],
+            });
+            const fetched = result.agents ?? [];
             const agents = fetched
                 .filter((a) => typeof a.name === "string" &&
                 typeof a.description === "string" &&
@@ -133,8 +111,18 @@ export async function refreshCloudAgents(opts) {
             return { authRejected: false, count: agents.length };
         }
         catch (err) {
+            // Zeus surfaces a GraphQL `errors` array as `GraphQLError` (HTTP 200)
+            // and non-2xx responses as an error too. Treat auth-flavored failures
+            // as auth-rejected so the caller can trigger a forced re-registration
+            // instead of looping on the same dead token.
+            const classified = classifyGraphqlError(err);
+            if (classified.authRejected) {
+                const reason = `Cloud agents: backend rejected machine JWT (${classified.message})`;
+                console.warn(reason);
+                return { authRejected: true, reason };
+            }
             // Network errors are non-fatal — local agents remain available offline.
-            const msg = err instanceof Error ? err.message : String(err);
+            const msg = graphqlErrorMessage(err);
             console.warn(`Cloud agents: refresh failed (${msg})`);
             return { authRejected: false, count: 0 };
         }

package/dist/agent/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAIX,SAAS,EAET,MAAM,4BAA4B,CAAC;AAUpC,OAAO,EACN,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,MAAM,8BAA8B,CAAC;AAGtC,OAAO,EACN,KAAK,WAAW,EAKhB,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAOrD,OAAO,KAAK,EAAE,gBAAgB,IAAI,oBAAoB,EAAE,MAAM,8CAA8C,CAAC;AAsG7G;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACxC,gBAAgB,EAAE,MAAM,GAAG,SAAS,EACpC,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,GAAG,cAAc,GAAG,OAAO,GAAG,QAAQ,CAAC,GACpF,MAAM,CAYR;AAgID;;;GAGG;AACH,wBAAgB,oCAAoC,CACnD,cAAc,EAAE,gBAAgB,CAAC,gBAAgB,CAAC,GAChD,IAAI,CAAC,oBAAoB,CAAC,gBAAgB,CAAC,EAAE,WAAW,CAAC,CAK3D;AAED,wBAAgB,oBAAoB,CACnC,SAAS,EAAE,MAAM,EAAE,GAAG,SAAS,EAC/B,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,YAAY,EACjB,GAAG,EAAE,gBAAgB,GACnB,SAAS,EAAE,CAwCb;AAkbD,MAAM,CAAC,OAAO,UAAU,iBAAiB,CACxC,GAAG,EAAE,YAAY,EACjB,IAAI,CAAC,EAAE;IACN,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB,GACC,IAAI,CAgaN"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAIX,SAAS,EAET,MAAM,4BAA4B,CAAC;AAUpC,OAAO,EACN,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,MAAM,8BAA8B,CAAC;AAGtC,OAAO,EACN,KAAK,WAAW,EAKhB,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAOrD,OAAO,KAAK,EAAE,gBAAgB,IAAI,oBAAoB,EAAE,MAAM,8CAA8C,CAAC;AAsG7G;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACxC,gBAAgB,EAAE,MAAM,GAAG,SAAS,EACpC,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,GAAG,cAAc,GAAG,OAAO,GAAG,QAAQ,CAAC,GACpF,MAAM,CAYR;AAkID;;;GAGG;AACH,wBAAgB,oCAAoC,CACnD,cAAc,EAAE,gBAAgB,CAAC,gBAAgB,CAAC,GAChD,IAAI,CAAC,oBAAoB,CAAC,gBAAgB,CAAC,EAAE,WAAW,CAAC,CAK3D;AAED,wBAAgB,oBAAoB,CACnC,SAAS,EAAE,MAAM,EAAE,GAAG,SAAS,EAC/B,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,YAAY,EACjB,GAAG,EAAE,gBAAgB,GACnB,SAAS,EAAE,CAwCb;AAicD,MAAM,CAAC,OAAO,UAAU,iBAAiB,CACxC,GAAG,EAAE,YAAY,EACjB,IAAI,CAAC,EAAE;IACN,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB,GACC,IAAI,CAgaN"}

package/dist/agent/index.js

@@ -420,12 +420,16 @@ async function runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, si
     // Accumulated thinking deltas for the live subagent sheet. This stays outside
     // final `SingleResult` so the public subagent tool_result contract is unchanged.
     let thinkingText = "";
+    // Responses API reasoning metadata that lets the UI classify accumulated
+    // subagent thinking as activity (mirrors the main-session thinking metadata).
+    let thinkingMetadata;
     const emitUpdate = () => {
         if (onUpdate) {
             const liveResult = {
                 ...currentResult,
                 ...(streamingText ? { streamingText } : {}),
                 ...(thinkingText ? { thinkingText } : {}),
+                ...(thinkingMetadata ? { thinkingMetadata } : {}),
             };
             onUpdate({
                 content: [{ type: "text", text: getFinalOutput(currentResult.messages) || streamingText || (thinkingText ? "(thinking...)" : "(running...)") }],
@@ -489,6 +493,9 @@ async function runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, si
                 }
                 else if (inner?.type === "thinking_delta" && inner.delta) {
                     thinkingText += inner.delta;
+                    if (inner.metadata) {
+                        thinkingMetadata = { ...(thinkingMetadata ?? {}), ...inner.metadata };
+                    }
                     emitUpdate();
                 }
                 continue;

package/dist/cli.js

@@ -36,6 +36,7 @@ function printHeader() {
         "  spectral bind          Link this directory to an Aexol Studio project",
         "  spectral unbind        Remove the Aexol Studio project binding",
         "  spectral update        Check for and install the latest Spectral version",
+        "  spectral ports         Diagnose port collisions across local projects",
         "  spectral --version     Print version and exit",
         "  spectral --help        Print this help and exit",
         "",
@@ -113,6 +114,11 @@ async function main() {
         await runUpdate(args.slice(1));
         process.exit(0);
     }
+    if (first === "ports") {
+        const { runPorts } = await import("./commands/ports.js");
+        await runPorts(args.slice(1));
+        process.exit(0);
+    }
     // No TUI/interactive mode is supported. All other invocations must use
     // explicit subcommands.
     process.stderr.write(`spectral: unknown command "${first ?? ""}".\n` +

package/dist/commands/ports.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `spectral ports` — diagnose port collisions across local projects.
+ *
+ * Usage:
+ *   spectral ports                 list every listening TCP port + owner
+ *   spectral ports check <p>...    check specific ports and suggest free ones
+ *   spectral ports free [start]    find the first free port from `start`
+ *
+ * Shares the exact same platform logic as the native `ports` extension, so
+ * results are identical whether run from the shell or from inside the agent.
+ */
+export declare function runPorts(args: string[]): Promise<void>;
+//# sourceMappingURL=ports.d.ts.map

package/dist/commands/ports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.d.ts","sourceRoot":"","sources":["../../src/commands/ports.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AA0CH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA0E5D"}

package/dist/commands/ports.js

@@ -0,0 +1,110 @@
+/**
+ * `spectral ports` — diagnose port collisions across local projects.
+ *
+ * Usage:
+ *   spectral ports                 list every listening TCP port + owner
+ *   spectral ports check <p>...    check specific ports and suggest free ones
+ *   spectral ports free [start]    find the first free port from `start`
+ *
+ * Shares the exact same platform logic as the native `ports` extension, so
+ * results are identical whether run from the shell or from inside the agent.
+ */
+import pc from "picocolors";
+import { findFreePort, isPortFree, knownPortLabel, scanPorts, } from "../extensions/ports/platform.js";
+function renderTable(entries) {
+    if (entries.length === 0)
+        return "No listening TCP ports found.";
+    const dedup = new Map();
+    for (const e of entries) {
+        const existing = dedup.get(e.port);
+        if (!existing || (existing.address === "0.0.0.0" && e.address !== "0.0.0.0")) {
+            dedup.set(e.port, { address: e.address, process: e.process, pid: e.pid });
+        }
+    }
+    const rows = [...dedup.entries()].sort((a, b) => a[0] - b[0]);
+    const portW = Math.max(5, ...rows.map(([p]) => String(p).length));
+    const lines = [
+        `${rows.length} listening TCP port(s):`,
+        "",
+        `${"Port".padStart(portW)}  ${"Bind".padEnd(22)}  Process`,
+        `${"─".repeat(portW)}  ${"─".repeat(22)}  ${"─".repeat(30)}`,
+    ];
+    for (const [port, info] of rows) {
+        const known = knownPortLabel(port);
+        const label = known ? `  ${known}` : "";
+        const owner = info.process ? `${info.process}${info.pid !== null ? ` (pid ${info.pid})` : ""}` : "unknown";
+        const bind = info.address === "0.0.0.0" || info.address === "::" || info.address === "::1"
+            ? "all" : info.address;
+        lines.push(`${String(port).padStart(portW)}  ${bind.padEnd(22)}  ${owner}${label}`);
+    }
+    return lines.join("\n");
+}
+export async function runPorts(args) {
+    const sub = args[0];
+    if (sub === "check") {
+        const ports = args
+            .slice(1)
+            .map((p) => Number(p))
+            .filter((p) => Number.isInteger(p) && p > 0);
+        if (ports.length === 0) {
+            process.stderr.write(pc.red("Usage: spectral ports check <port> [<port>...]\n"));
+            process.exit(1);
+        }
+        const scan = await scanPorts();
+        const owners = new Map();
+        for (const e of scan.entries) {
+            if (!owners.has(e.port))
+                owners.set(e.port, { process: e.process, pid: e.pid });
+        }
+        for (const port of ports) {
+            const owner = owners.get(port);
+            const free = owner === undefined && (await isPortFree(port));
+            if (free) {
+                process.stdout.write(pc.green(`✓ ${port} is free\n`));
+            }
+            else {
+                const who = owner?.process ? `${owner.process}${owner.pid !== null ? ` (pid ${owner.pid})` : ""}` : "already bound";
+                const label = knownPortLabel(port) ? ` — ${knownPortLabel(port)}` : "";
+                const alternative = await findFreePort(port);
+                process.stdout.write(pc.red(`✗ ${port} is taken by ${who}${label}\n`));
+                process.stdout.write(pc.dim(`  first free port from ${port}: ${alternative ?? "none found"}\n`));
+            }
+        }
+        return;
+    }
+    if (sub === "free") {
+        const start = Number(args[1]) || 3000;
+        const port = await findFreePort(start);
+        if (port === null) {
+            process.stderr.write(pc.red(`No free port found from ${start}\n`));
+            process.exit(1);
+        }
+        const label = knownPortLabel(port) ? ` (usually: ${knownPortLabel(port)})` : "";
+        process.stdout.write(pc.green(`✓ First free port from ${start}: ${port}${label}\n`));
+        return;
+    }
+    if (sub === "--help" || sub === "-h") {
+        process.stdout.write([
+            "Usage:",
+            "  spectral ports                 list listening TCP ports + owners",
+            "  spectral ports check <p>...    check specific ports and suggest free ones",
+            "  spectral ports free [start]    find first free port from `start` (default 3000)",
+            "",
+        ].join("\n"));
+        process.exit(0);
+    }
+    // Default: full scan.
+    if (sub === undefined) {
+        try {
+            const scan = await scanPorts();
+            process.stdout.write(`${renderTable(scan.entries)}\n`);
+        }
+        catch (err) {
+            process.stderr.write(pc.red(`Port scan failed: ${err instanceof Error ? err.message : String(err)}\n`));
+            process.exit(1);
+        }
+        return;
+    }
+    process.stderr.write(pc.red(`Unknown ports subcommand: ${sub}\n`));
+    process.exit(1);
+}

package/dist/extensions/ports/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Ports — native spectral extension.
+ *
+ * Helps resolve the classic "many projects on one machine" problem where
+ * Postgres, NATS, Debezium, MinIO, Redis, etc. collide on the same ports.
+ *
+ * Registers three read-only/free tools:
+ *   - ports_scan         list every listening TCP port + owning process
+ *   - ports_check         check specific ports (status + owner + suggestion)
+ *   - ports_find_free     find the first free port from a starting point
+ *
+ * No external dependencies. On macOS we parse `lsof`, on Linux `ss`/`netstat`,
+ * and on Windows `netstat`. Port reservation for CI/docker is left to the
+ * user's compose/env files; this extension is the diagnostic + allocation
+ * layer that gives the agent the facts it needs to fix collisions.
+ */
+import type { ExtensionAPI } from "../../sdk/coding-agent/index.js";
+export default function portsExtension(ext: ExtensionAPI): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/extensions/ports/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/extensions/ports/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,KAAK,EAAmB,YAAY,EAAkB,MAAM,iCAAiC,CAAC;AAuDrG,wBAA8B,cAAc,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CA+F7E"}

package/dist/extensions/ports/index.js

@@ -0,0 +1,154 @@
+/**
+ * Ports — native spectral extension.
+ *
+ * Helps resolve the classic "many projects on one machine" problem where
+ * Postgres, NATS, Debezium, MinIO, Redis, etc. collide on the same ports.
+ *
+ * Registers three read-only/free tools:
+ *   - ports_scan         list every listening TCP port + owning process
+ *   - ports_check         check specific ports (status + owner + suggestion)
+ *   - ports_find_free     find the first free port from a starting point
+ *
+ * No external dependencies. On macOS we parse `lsof`, on Linux `ss`/`netstat`,
+ * and on Windows `netstat`. Port reservation for CI/docker is left to the
+ * user's compose/env files; this extension is the diagnostic + allocation
+ * layer that gives the agent the facts it needs to fix collisions.
+ */
+import { Type } from "typebox";
+import { knownPortLabel, scanPorts, isPortFree, findFreePort } from "./platform.js";
+function errorResult(msg) {
+    return { content: [{ type: "text", text: `❌ ${msg}` }], details: { isError: true, error: msg } };
+}
+function renderScan(entries) {
+    if (entries.length === 0)
+        return "No listening TCP ports found.";
+    const dedup = new Map();
+    for (const e of entries) {
+        // Prefer a non-wildcard address when the same port appears twice (IPv4 + IPv6).
+        const existing = dedup.get(e.port);
+        if (!existing || (existing.address === "0.0.0.0" && e.address !== "0.0.0.0")) {
+            dedup.set(e.port, { address: e.address, process: e.process, pid: e.pid });
+        }
+    }
+    const rows = [...dedup.entries()].sort((a, b) => a[0] - b[0]);
+    const portW = Math.max(5, ...rows.map(([p]) => String(p).length));
+    const rowsText = rows.map(([port, info]) => {
+        const known = knownPortLabel(port);
+        const label = known ? `  ${known}` : "";
+        const owner = info.process ? `${info.process}${info.pid !== null ? ` (pid ${info.pid})` : ""}` : "unknown";
+        const bind = info.address === "0.0.0.0" || info.address === "::" || info.address === "::1"
+            ? "all" : info.address;
+        return `${String(port).padStart(portW)}  ${bind.padEnd(22)}  ${owner}${label}`;
+    });
+    return [
+        `${rows.length} listening TCP port(s):`,
+        "",
+        `${"Port".padStart(portW)}  ${"Bind".padEnd(22)}  Process`,
+        `${"─".repeat(portW)}  ${"─".repeat(22)}  ${"─".repeat(30)}`,
+        ...rowsText,
+    ].join("\n");
+}
+const scanSchema = Type.Object({});
+const checkSchema = Type.Object({
+    ports: Type.Array(Type.Number(), { description: "Port numbers to check (e.g. [5432, 4222, 9000])." }),
+    host: Type.Optional(Type.String({ default: "0.0.0.0", description: "Bind host to test for free ports. Default: 0.0.0.0." })),
+});
+const findSchema = Type.Object({
+    start: Type.Optional(Type.Number({ default: 3000, description: "Start searching from this port. Default: 3000." })),
+    host: Type.Optional(Type.String({ default: "0.0.0.0", description: "Bind host to test. Default: 0.0.0.0." })),
+    max: Type.Optional(Type.Number({ default: 65535, description: "Upper bound. Default: 65535." })),
+});
+export default async function portsExtension(ext) {
+    const scanTool = {
+        name: "ports_scan",
+        label: "Scan Ports",
+        description: "List every listening TCP port on this machine with its bind address and owning process. " +
+            "Use this when services from multiple projects (Postgres, NATS, Debezium, MinIO, Redis, etc.) " +
+            "may be colliding on the same ports. Read-only.",
+        promptSnippet: "`ports_scan` — list listening TCP ports and their owning processes",
+        parameters: scanSchema,
+        async execute(_toolCallId, _params) {
+            try {
+                const result = await scanPorts();
+                return {
+                    content: [{ type: "text", text: renderScan(result.entries) }],
+                    details: { count: result.entries.length, platform: result.platform, command: result.command },
+                };
+            }
+            catch (err) {
+                return errorResult(err instanceof Error ? err.message : String(err));
+            }
+        },
+    };
+    const checkTool = {
+        name: "ports_check",
+        label: "Check Ports",
+        description: "Check whether specific TCP ports are free or taken. Returns the owner process for taken ports " +
+            "and the first free alternative for requested ones. Use before starting another project's stack.",
+        promptSnippet: "`ports_check` — check status of specific ports and suggest free alternatives",
+        parameters: checkSchema,
+        async execute(_toolCallId, params) {
+            const ports = params.ports.map((p) => Number(p)).filter((p) => Number.isInteger(p) && p > 0);
+            if (ports.length === 0)
+                return errorResult("Provide at least one valid port in `ports`.");
+            const host = params.host ?? "0.0.0.0";
+            try {
+                const scan = await scanPorts();
+                const owners = new Map();
+                for (const e of scan.entries) {
+                    if (!owners.has(e.port))
+                        owners.set(e.port, { process: e.process, pid: e.pid });
+                }
+                const lines = [];
+                for (const port of ports) {
+                    const owner = owners.get(port);
+                    const free = owner === undefined && (await isPortFree(port, host));
+                    if (free) {
+                        lines.push(`✓ ${port} is free (bindable on ${host}).`);
+                    }
+                    else {
+                        const who = owner?.process ? `${owner.process}${owner.pid !== null ? ` (pid ${owner.pid})` : ""}` : "already bound";
+                        const label = knownPortLabel(port) ? ` — ${knownPortLabel(port)}` : "";
+                        const alternative = await findFreePort(port, 65535, host);
+                        lines.push(`✗ ${port} is taken by ${who}${label}. First free port from ${port}: ${alternative ?? "none found"}.`);
+                    }
+                }
+                return { content: [{ type: "text", text: lines.join("\n") }], details: { ports, host } };
+            }
+            catch (err) {
+                return errorResult(err instanceof Error ? err.message : String(err));
+            }
+        },
+    };
+    const findTool = {
+        name: "ports_find_free",
+        label: "Find Free Port",
+        description: "Find the first free TCP port at or after a starting port. Useful when allocating a per-project " +
+            "offset for a new stack without colliding with services already running on this machine.",
+        promptSnippet: "`ports_find_free` — find the first free port from a starting point",
+        parameters: findSchema,
+        async execute(_toolCallId, params) {
+            const start = Number(params.start) || 3000;
+            const max = Number(params.max) || 65535;
+            const host = params.host ?? "0.0.0.0";
+            try {
+                const port = await findFreePort(start, max, host);
+                if (port === null) {
+                    return { content: [{ type: "text", text: `No free port found between ${start} and ${max} on ${host}.` }], details: { start, max, host } };
+                }
+                const label = knownPortLabel(port) ? ` (usually: ${knownPortLabel(port)})` : "";
+                return {
+                    content: [{ type: "text", text: `✓ First free port from ${start} on ${host}: ${port}${label}.` }],
+                    details: { port, start, max, host },
+                };
+            }
+            catch (err) {
+                return errorResult(err instanceof Error ? err.message : String(err));
+            }
+        },
+    };
+    ext.registerTool(scanTool);
+    ext.registerTool(checkTool);
+    ext.registerTool(findTool);
+    process.stderr.write(`[ports] Registered ports_scan + ports_check + ports_find_free (platform: ${process.platform}).\n`);
+}

package/dist/extensions/ports/platform.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Cross-platform port introspection for the ports extension.
+ *
+ * Zero external dependencies. We shell out to the OS's native tooling and
+ * parse its output, so a machine with many projects/services can be inspected
+ * without requiring `lsof` from JS bindings or admin privileges.
+ *
+ * Detection order per platform:
+ *   - darwin: lsof -nP -iTCP -sTCP:LISTEN
+ *   - linux:  ss -ltnp  (fallback: netstat -ltnp)
+ *   - win32:  netstat -ano (pids are resolved in a second best-effort pass)
+ */
+export interface PortEntry {
+    port: number;
+    protocol: "tcp" | "udp";
+    address: string;
+    pid: number | null;
+    process: string | null;
+}
+export interface PortScanResult {
+    platform: string;
+    command: string;
+    entries: PortEntry[];
+}
+/** Well-known services so the report can label ports humans recognize. */
+export declare const KNOWN_PORTS: Record<number, string>;
+export declare function knownPortLabel(port: number): string | undefined;
+export declare function scanPorts(): Promise<PortScanResult>;
+/**
+ * Check a single port using a real bind attempt, which is the only reliable
+ * cross-platform way to know whether a port is actually free (a service may be
+ * listening only on a specific interface, so a "scan" alone is not enough).
+ */
+export declare function isPortFree(port: number, host?: string): Promise<boolean>;
+/**
+ * Find the first free port at or after `start`, bounded by `max`.
+ */
+export declare function findFreePort(start: number, max?: number, host?: string): Promise<number | null>;
+//# sourceMappingURL=platform.d.ts.map

package/dist/extensions/ports/platform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform.d.ts","sourceRoot":"","sources":["../../../src/extensions/ports/platform.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAQH,MAAM,WAAW,SAAS;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,KAAK,GAAG,KAAK,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,SAAS,EAAE,CAAC;CACrB;AAED,0EAA0E;AAC1E,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAuBrC,CAAC;AAEX,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE/D;AA+JD,wBAAsB,SAAS,IAAI,OAAO,CAAC,cAAc,CAAC,CA+BzD;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,SAAY,GAAG,OAAO,CAAC,OAAO,CAAC,CAWjF;AAED;;GAEG;AACH,wBAAsB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,SAAQ,EAAE,IAAI,SAAY,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAKvG"}