@mocito/pi-goal 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.1.2
+
+- Move the extension entry point to `extensions/index.ts` so Pi displays the package extension compactly.
+
+## 0.1.1
+
+- Add best-effort install/update telemetry, gated by Pi telemetry/offline settings and disabled in CI.
+
 ## 0.1.0
 
 - Initial `@mocito/pi-goal` package with `/goal`, goal tools, branch-scoped session persistence, usage accounting, UI status, and automatic continuation.

package/CONTRIBUTING.md

@@ -43,7 +43,7 @@ Before opening a pull request:
 
 ## Coding guidelines
 
-- Keep `extensions/pi-goal/index.ts` focused on Pi extension wiring and move reusable implementation details into `src/`.
+- Keep `extensions/index.ts` focused on Pi extension wiring and move reusable implementation details into `src/`.
 - When changing model tool parameters, update the Typebox schema, runtime validation, README tool docs, and tests together.
 - Treat persisted mutation shapes, custom message types, command names, and tool names as public interface.
 - Preserve branch-scoped semantics: reconstruct state from `ctx.sessionManager.getBranch()` and avoid global process state that crosses sessions unexpectedly.

package/README.md

@@ -13,7 +13,7 @@ For local development:
 ```bash
 pi -e ./packages/pi-goal
 # or
-pi -e ./packages/pi-goal/extensions/pi-goal/index.ts
+pi -e ./packages/pi-goal/extensions/index.ts
 ```
 
 ## Commands
@@ -69,7 +69,14 @@ Branch behavior: goal mutations are stored on the current session branch. If you
 
 ## Configuration
 
-v1 has no user-facing configuration. Automatic continuation is enabled for active goals and stops when the goal is paused, blocked, complete, usage-limited, budget-limited, cleared, or when pending user messages exist.
+v1 has no user-facing goal configuration. Automatic continuation is enabled for active goals and stops when the goal is paused, blocked, complete, usage-limited, budget-limited, cleared, or when pending user messages exist.
+
+Environment flags:
+
+| Flag | Description |
+| --- | --- |
+| `PI_OFFLINE=1` | Disables install/update telemetry. |
+| `PI_TELEMETRY=0` | Disables install/update telemetry. |
 
 ## Troubleshooting
 
@@ -120,4 +127,6 @@ Use the project-local release command from the repository root when possible:
 
 Pi packages execute arbitrary code with your user permissions. Install only from sources you trust.
 
-`pi-goal` does not require API keys, does not read provider credentials, and does not make network requests. Goal state is stored in local Pi session entries and goal objectives may be sent to the active model as hidden continuation context. Do not put secrets, credentials, tokens, or private data into goal objectives. See [SECURITY.md](./SECURITY.md) for the full security model and reporting instructions.
+`pi-goal` does not require API keys and does not read provider credentials. Goal state is stored in local Pi session entries and goal objectives may be sent to the active model as hidden continuation context. Do not put secrets, credentials, tokens, or private data into goal objectives.
+
+On startup, Pi Goal sends a best-effort install/update telemetry ping once per package version unless Pi telemetry is disabled, offline mode is enabled, or Pi runs in CI. See [SECURITY.md](./SECURITY.md) for the full security model and reporting instructions.

package/SECURITY.md

@@ -23,6 +23,8 @@ The maintainer will acknowledge reports as soon as practical and coordinate disc
 
 `pi-goal` stores goal state as custom entries in the current Pi session branch. Goal objectives and usage summaries may appear in local Pi session files and in hidden continuation context sent to the active model. Do not put secrets, credentials, tokens, or private data into goal objectives.
 
-The package does not require API keys, does not read provider credentials, does not make network requests, and does not write files outside Pi's normal session storage. Its model tools can only inspect the current goal, create a new explicitly requested goal when none exists, or mark the current goal `complete`/`blocked`.
+The package does not require API keys and does not read provider credentials. Its model tools can only inspect the current goal, create a new explicitly requested goal when none exists, or mark the current goal `complete`/`blocked`.
+
+On startup, the extension sends a best-effort install/update telemetry ping to `mocito.dev` once per package version unless Pi telemetry is disabled, offline mode is enabled, or Pi runs in CI. The ping includes only the package name, version, and parsed platform/runtime/architecture from its User-Agent; it does not include prompts, goal objectives, file paths, session data, config values, or API keys. Telemetry writes a local deduplication marker under Pi's agent extensions directory.
 
 Goal objectives are treated as untrusted user-provided task data when continuation context is built. They are JSON-encoded before being embedded in the hidden context message to reduce prompt-injection risk from delimiter-breaking text.

package/extensions/{pi-goal/index.ts → index.ts}

@@ -1,16 +1,19 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { accountUsageFromBranch, isBudgetExceeded } from "../../src/accounting.js";
-import { goalCompletions, handleGoalCommand } from "../../src/commands.js";
-import { filterGoalContextMessages, GoalContinuationScheduler } from "../../src/continuation.js";
-import { registerGoalRenderers } from "../../src/rendering.js";
-import { appendGoalMutation, applyGoalMutation, reconstructGoalState, statusMutation } from "../../src/state.js";
-import { registerGoalTools } from "../../src/tools.js";
-import type { GoalState } from "../../src/types.js";
-import { GOAL_EVENT_TYPE } from "../../src/types.js";
-import { nowIso, realizedTimeUsed } from "../../src/utils.js";
-import { clearGoalUi, updateGoalUi } from "../../src/ui.js";
+import { accountUsageFromBranch, isBudgetExceeded } from "../src/accounting.js";
+import { goalCompletions, handleGoalCommand } from "../src/commands.js";
+import { filterGoalContextMessages, GoalContinuationScheduler } from "../src/continuation.js";
+import { registerGoalRenderers } from "../src/rendering.js";
+import { appendGoalMutation, applyGoalMutation, reconstructGoalState, statusMutation } from "../src/state.js";
+import { reportInstallTelemetry } from "../src/install-telemetry.js";
+import { registerGoalTools } from "../src/tools.js";
+import type { GoalState } from "../src/types.js";
+import { GOAL_EVENT_TYPE } from "../src/types.js";
+import { nowIso, realizedTimeUsed } from "../src/utils.js";
+import { clearGoalUi, updateGoalUi } from "../src/ui.js";
 
 export default function piGoal(pi: ExtensionAPI) {
+  reportInstallTelemetry();
+
   let goal: GoalState | null = null;
   const scheduler = new GoalContinuationScheduler(pi, { getGoal: () => goal });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mocito/pi-goal",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Persistent long-running goals for Pi.",
   "type": "module",
   "license": "MIT",
@@ -26,7 +26,7 @@
   },
   "pi": {
     "extensions": [
-      "./extensions/pi-goal/index.ts"
+      "./extensions/index.ts"
     ]
   },
   "files": [

package/src/index.ts

@@ -9,3 +9,4 @@ export * from "./continuation.js";
 export * from "./tools.js";
 export * from "./ui.js";
 export * from "./rendering.js";
+export * from "./install-telemetry.js";

package/src/install-telemetry.ts

@@ -0,0 +1,104 @@
+import { readFileSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+const PACKAGE_NAME = "pi-goal";
+const INSTALL_TELEMETRY_URL = "https://mocito.dev/api/report-install";
+const INSTALL_TELEMETRY_TIMEOUT_MS = 5000;
+const CI_ENVIRONMENT_VARIABLES = [
+  "APPVEYOR",
+  "BITBUCKET_BUILD_NUMBER",
+  "BUILDKITE",
+  "CIRCLECI",
+  "CODESPACES",
+  "DRONE",
+  "GITHUB_ACTIONS",
+  "GITLAB_CI",
+  "JENKINS_URL",
+  "NETLIFY",
+  "TEAMCITY_VERSION",
+  "TF_BUILD",
+  "TRAVIS",
+  "VERCEL",
+];
+
+interface InstallTelemetryState {
+  lastReportedVersion?: string;
+}
+
+interface PiSettingsDocument {
+  enableInstallTelemetry?: unknown;
+}
+
+function readJsonFile(path: string): unknown {
+  try {
+    return JSON.parse(readFileSync(path, "utf8")) as unknown;
+  } catch {
+    return {};
+  }
+}
+
+function isTruthyEnvFlag(value: string | undefined): boolean {
+  if (!value) return false;
+  return value === "1" || value.toLowerCase() === "true" || value.toLowerCase() === "yes";
+}
+
+function isPresentEnvFlag(value: string | undefined): boolean {
+  if (!value) return false;
+  const normalized = value.toLowerCase();
+  return normalized !== "0" && normalized !== "false" && normalized !== "no";
+}
+
+function isCiEnvironment(): boolean {
+  if (isTruthyEnvFlag(process.env.CI)) return true;
+  return CI_ENVIRONMENT_VARIABLES.some((name) => isPresentEnvFlag(process.env[name]));
+}
+
+function isInstallTelemetryEnabled(): boolean {
+  if (isCiEnvironment()) return false;
+  if (isTruthyEnvFlag(process.env.PI_OFFLINE)) return false;
+  if (process.env.PI_TELEMETRY !== undefined) return isTruthyEnvFlag(process.env.PI_TELEMETRY);
+
+  const settings = readJsonFile(join(getAgentDir(), "settings.json")) as PiSettingsDocument;
+  return settings.enableInstallTelemetry !== false;
+}
+
+function getPackageVersion(): string {
+  const packageJson = readJsonFile(fileURLToPath(new URL("../package.json", import.meta.url))) as { version?: unknown };
+  return typeof packageJson.version === "string" && packageJson.version.length > 0 ? packageJson.version : "0.0.0";
+}
+
+function getInstallTelemetryUserAgent(version: string): string {
+  const runtimeVersions = process.versions as NodeJS.ProcessVersions & { bun?: string };
+  const runtime = runtimeVersions.bun ? `bun/${runtimeVersions.bun}` : `node/${process.version}`;
+  return `${PACKAGE_NAME}/${version} (${process.platform}; ${runtime}; ${process.arch})`;
+}
+
+async function reportInstallTelemetryAsync(): Promise<void> {
+  try {
+    if (!isInstallTelemetryEnabled()) return;
+
+    const version = getPackageVersion();
+    const extensionsDir = join(getAgentDir(), "extensions");
+    const statePath = join(extensionsDir, "pi-goal-install.json");
+    const state = readJsonFile(statePath) as InstallTelemetryState;
+    if (state.lastReportedVersion === version) return;
+
+    await mkdir(extensionsDir, { recursive: true });
+    await writeFile(statePath, `${JSON.stringify({ lastReportedVersion: version }, null, 2)}\n`, "utf8");
+
+    const params = new URLSearchParams({ tool: PACKAGE_NAME, version });
+    await fetch(`${INSTALL_TELEMETRY_URL}?${params.toString()}`, {
+      headers: { "User-Agent": getInstallTelemetryUserAgent(version) },
+      signal: AbortSignal.timeout(INSTALL_TELEMETRY_TIMEOUT_MS),
+    });
+  } catch {
+    // Best-effort telemetry: ignore settings, filesystem, and network failures.
+  }
+}
+
+export function reportInstallTelemetry(): void {
+  void reportInstallTelemetryAsync();
+}