@ai-outfitter/outfitter 1.7.1 → 1.8.1

package/dist/telemetry/CiEnvironment.js

@@ -0,0 +1,4 @@
+import { id, isCI } from 'ci-info';
+export const normalizeCiVendorId = (vendorId) => vendorId === null ? null : vendorId.toLowerCase();
+export const detectCi = () => ({ isCI, vendorId: normalizeCiVendorId(id) });
+//# sourceMappingURL=CiEnvironment.js.map

package/dist/telemetry/CiEnvironment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CiEnvironment.js","sourceRoot":"","sources":["../../src/telemetry/CiEnvironment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAOnC,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,QAAuB,EAAiB,EAAE,CAC5E,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC;AAEpD,MAAM,CAAC,MAAM,QAAQ,GAAG,GAAe,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,mBAAmB,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC"}

package/dist/telemetry/TelemetryConsent.d.ts

@@ -0,0 +1,8 @@
+import type { SettingsLoadResult } from '../settings/SettingsLoader.js';
+export type TelemetryConsentSource = 'default' | 'user settings' | 'user-local settings' | 'project settings' | 'project-local settings' | 'invalid settings' | 'OUTFITTER_TELEMETRY' | 'DO_NOT_TRACK';
+export interface TelemetryConsent {
+    readonly enabled: boolean;
+    readonly source: TelemetryConsentSource;
+}
+export type TelemetryEnvironment = Readonly<Record<string, string | undefined>>;
+export declare const resolveTelemetryConsent: (loaded: SettingsLoadResult, env: TelemetryEnvironment) => TelemetryConsent;

package/dist/telemetry/TelemetryConsent.js

@@ -0,0 +1,39 @@
+const localSource = (file) => {
+    switch (file.location.scope) {
+        case 'user':
+            return 'user settings';
+        case 'user-local':
+            return 'user-local settings';
+        case 'project':
+            return 'project settings';
+        case 'project-local':
+            return 'project-local settings';
+        case 'remote':
+            return undefined;
+    }
+};
+const environmentConsent = (env) => {
+    if (env.OUTFITTER_TELEMETRY === '0')
+        return { enabled: false, source: 'OUTFITTER_TELEMETRY' };
+    if (env.DO_NOT_TRACK === '1')
+        return { enabled: false, source: 'DO_NOT_TRACK' };
+    return undefined;
+};
+export const resolveTelemetryConsent = (loaded, env) => {
+    const killed = environmentConsent(env);
+    if (killed !== undefined)
+        return killed;
+    if (loaded.issues.length > 0)
+        return { enabled: false, source: 'invalid settings' };
+    // Any local opt-out wins. Remote settings are deliberately excluded from consent.
+    const disabled = loaded.files.findLast((file) => localSource(file) !== undefined && file.settings.telemetry?.enabled === false);
+    if (disabled !== undefined)
+        return { enabled: false, source: localSource(disabled) };
+    // Only settings owned by the user may explicitly enable collection.
+    const enabled = loaded.files.findLast((file) => (file.location.scope === 'user' || file.location.scope === 'user-local') &&
+        file.settings.telemetry?.enabled === true);
+    if (enabled !== undefined)
+        return { enabled: true, source: localSource(enabled) };
+    return { enabled: true, source: 'default' };
+};
+//# sourceMappingURL=TelemetryConsent.js.map

package/dist/telemetry/TelemetryConsent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TelemetryConsent.js","sourceRoot":"","sources":["../../src/telemetry/TelemetryConsent.ts"],"names":[],"mappings":"AAmBA,MAAM,WAAW,GAAG,CAAC,IAAwB,EAAsC,EAAE;IACnF,QAAQ,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;QAC5B,KAAK,MAAM;YACT,OAAO,eAAe,CAAC;QACzB,KAAK,YAAY;YACf,OAAO,qBAAqB,CAAC;QAC/B,KAAK,SAAS;YACZ,OAAO,kBAAkB,CAAC;QAC5B,KAAK,eAAe;YAClB,OAAO,wBAAwB,CAAC;QAClC,KAAK,QAAQ;YACX,OAAO,SAAS,CAAC;IACrB,CAAC;AACH,CAAC,CAAC;AAEF,MAAM,kBAAkB,GAAG,CAAC,GAAyB,EAAgC,EAAE;IACrF,IAAI,GAAG,CAAC,mBAAmB,KAAK,GAAG;QAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,qBAAqB,EAAE,CAAC;IAC9F,IAAI,GAAG,CAAC,YAAY,KAAK,GAAG;QAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;IAChF,OAAO,SAAS,CAAC;AACnB,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,MAA0B,EAAE,GAAyB,EAAoB,EAAE;IACjH,MAAM,MAAM,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;IACvC,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC;IACxC,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,kBAAkB,EAAE,CAAC;IAEpF,kFAAkF;IAClF,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,CAAC,QAAQ,CACpC,CAAC,IAAI,EAAE,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,KAAK,SAAS,IAAI,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,OAAO,KAAK,KAAK,CACxF,CAAC;IACF,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,CAAC,QAAQ,CAAE,EAAE,CAAC;IAEtF,oEAAoE;IACpE,MAAM,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,QAAQ,CACnC,CAAC,IAAI,EAAE,EAAE,CACP,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,KAAK,MAAM,IAAI,IAAI,CAAC,QAAQ,CAAC,KAAK,KAAK,YAAY,CAAC;QACxE,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,OAAO,KAAK,IAAI,CAC5C,CAAC;IACF,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,OAAO,CAAE,EAAE,CAAC;IAEnF,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;AAC9C,CAAC,CAAC"}

package/dist/telemetry/TelemetryConstants.d.ts

@@ -0,0 +1,10 @@
+/**
+ * PostHog project configuration. An empty key makes telemetry completely inert.
+ *
+ * This is a PostHog project API key: write-only, safe to ship in client code, and useless for
+ * reading any project data. It belongs to the `ai-outfitter` organization, project 562393, on
+ * PostHog Cloud US — so `POSTHOG_HOST` must stay a US endpoint or events are accepted nowhere.
+ */
+export declare const POSTHOG_API_KEY = "phc_v9FGDjtEC7h9UvLxHdJKaHFtFfMN7UZwpJ2weRTFoqvz";
+export declare const POSTHOG_HOST = "https://us.i.posthog.com";
+export declare const TELEMETRY_SHUTDOWN_BUDGET_MS = 1000;

package/dist/telemetry/TelemetryConstants.js

@@ -0,0 +1,11 @@
+/**
+ * PostHog project configuration. An empty key makes telemetry completely inert.
+ *
+ * This is a PostHog project API key: write-only, safe to ship in client code, and useless for
+ * reading any project data. It belongs to the `ai-outfitter` organization, project 562393, on
+ * PostHog Cloud US — so `POSTHOG_HOST` must stay a US endpoint or events are accepted nowhere.
+ */
+export const POSTHOG_API_KEY = 'phc_v9FGDjtEC7h9UvLxHdJKaHFtFfMN7UZwpJ2weRTFoqvz';
+export const POSTHOG_HOST = 'https://us.i.posthog.com';
+export const TELEMETRY_SHUTDOWN_BUDGET_MS = 1000;
+//# sourceMappingURL=TelemetryConstants.js.map

package/dist/telemetry/TelemetryConstants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TelemetryConstants.js","sourceRoot":"","sources":["../../src/telemetry/TelemetryConstants.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,kDAAkD,CAAC;AAClF,MAAM,CAAC,MAAM,YAAY,GAAG,0BAA0B,CAAC;AACvD,MAAM,CAAC,MAAM,4BAA4B,GAAG,IAAI,CAAC"}

package/dist/telemetry/TelemetryContext.d.ts

@@ -0,0 +1,15 @@
+import type { SettingsLoadResult } from '../settings/SettingsLoader.js';
+import type { TelemetryEnvironment } from './TelemetryConsent.js';
+import type { DetectedCi } from './CiEnvironment.js';
+import type { TelemetryStateStore } from './TelemetryState.js';
+export interface TelemetryContextInput {
+    readonly homeDirectory: string;
+    readonly projectDirectory: string;
+    readonly env: TelemetryEnvironment;
+}
+export interface TelemetryContext {
+    readonly settingsReader: () => SettingsLoadResult;
+    readonly stateStore: TelemetryStateStore;
+    readonly ci: DetectedCi;
+}
+export declare const createTelemetryContext: (input: TelemetryContextInput) => TelemetryContext;

package/dist/telemetry/TelemetryContext.js

@@ -0,0 +1,13 @@
+// Composes the process-level telemetry collaborators used by the CLI entrypoint.
+import { discoverSettingsLoadPlan, loadSettingsFiles } from '../settings/SettingsLoader.js';
+import { detectCi } from './CiEnvironment.js';
+import { createTelemetryStateStore, resolveTelemetryStatePath } from './TelemetryState.js';
+export const createTelemetryContext = (input) => {
+    const plan = discoverSettingsLoadPlan(input);
+    return {
+        settingsReader: () => loadSettingsFiles(plan),
+        stateStore: createTelemetryStateStore(resolveTelemetryStatePath(input.homeDirectory, input.env)),
+        ci: detectCi(),
+    };
+};
+//# sourceMappingURL=TelemetryContext.js.map

package/dist/telemetry/TelemetryContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TelemetryContext.js","sourceRoot":"","sources":["../../src/telemetry/TelemetryContext.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,OAAO,EAAE,wBAAwB,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAG5F,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE9C,OAAO,EAAE,yBAAyB,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAe3F,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,KAA4B,EAAoB,EAAE;IACvF,MAAM,IAAI,GAAG,wBAAwB,CAAC,KAAK,CAAC,CAAC;IAC7C,OAAO;QACL,cAAc,EAAE,GAAG,EAAE,CAAC,iBAAiB,CAAC,IAAI,CAAC;QAC7C,UAAU,EAAE,yBAAyB,CAAC,yBAAyB,CAAC,KAAK,CAAC,aAAa,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;QAChG,EAAE,EAAE,QAAQ,EAAE;KACf,CAAC;AACJ,CAAC,CAAC"}

package/dist/telemetry/TelemetryService.d.ts

@@ -0,0 +1,57 @@
+import type { PostHogOptions } from 'posthog-node';
+import type { SettingsLoadResult } from '../settings/SettingsLoader.js';
+import type { TelemetryEnvironment } from './TelemetryConsent.js';
+import type { TelemetryStateStore } from './TelemetryState.js';
+import type { DetectedCi } from './CiEnvironment.js';
+export type DurationBucket = '<1s' | '1-5s' | '5-30s' | '30s+';
+export type WarningCountBucket = '0' | '1-5' | '5+' | 'unknown';
+export type TelemetryOutcome = 'success' | 'error';
+export interface TelemetryCommandContext {
+    readonly command: string;
+    readonly outfitterVersion: string;
+    readonly nodeVersion: string;
+    readonly platform: string;
+    readonly architecture: string;
+    readonly interactive: boolean;
+    readonly harness?: string;
+    readonly strict?: boolean;
+}
+export interface TelemetryCompletionContext extends TelemetryCommandContext {
+    readonly outcome: TelemetryOutcome;
+    readonly durationMs: number;
+    readonly exitCode: number;
+}
+export interface TelemetryClient {
+    capture(message: {
+        readonly distinctId: string;
+        readonly event: string;
+        readonly properties: Record<string, unknown>;
+    }): void | Promise<void>;
+    shutdown(timeoutMs?: number): Promise<void>;
+}
+export interface TelemetryClientOptions {
+    readonly host: string;
+    readonly disableGeoip: true;
+    readonly fetch: TelemetryFetch;
+}
+export type TelemetryFetch = NonNullable<PostHogOptions['fetch']>;
+export type TelemetryClientFactory = (apiKey: string, options: TelemetryClientOptions) => TelemetryClient | Promise<TelemetryClient>;
+export interface TelemetryService {
+    captureCommandStarted(context: TelemetryCommandContext): Promise<void>;
+    captureCommandCompleted(context: TelemetryCompletionContext): Promise<void>;
+    shutdown(): Promise<void>;
+}
+export interface TelemetryServiceDependencies {
+    readonly settingsReader: () => SettingsLoadResult;
+    readonly stateStore: TelemetryStateStore;
+    readonly env: TelemetryEnvironment;
+    readonly ci: DetectedCi;
+    readonly writeError: (message: string) => void;
+    readonly apiKey?: string;
+    readonly clientFactory?: TelemetryClientFactory;
+    readonly shutdownBudgetMs?: number;
+}
+export declare const createBoundedTelemetryFetch: (fetchImplementation: typeof globalThis.fetch, budgetMs: number) => TelemetryFetch;
+export declare const buildCommandStartedProperties: (context: TelemetryCommandContext, ci: DetectedCi) => Record<string, unknown>;
+export declare const buildCommandCompletedProperties: (context: TelemetryCompletionContext, ci: DetectedCi) => Record<string, unknown>;
+export declare const createTelemetryService: (dependencies: TelemetryServiceDependencies) => TelemetryService;

package/dist/telemetry/TelemetryService.js

@@ -0,0 +1,157 @@
+import { HARNESSES } from '../settings/Settings.js';
+import { POSTHOG_API_KEY, POSTHOG_HOST, TELEMETRY_SHUTDOWN_BUDGET_MS } from './TelemetryConstants.js';
+import { resolveTelemetryConsent } from './TelemetryConsent.js';
+const OS_FAMILIES = ['aix', 'android', 'darwin', 'freebsd', 'linux', 'openbsd', 'sunos', 'win32', 'unknown'];
+const ARCHITECTURES = [
+    'arm',
+    'arm64',
+    'ia32',
+    'loong64',
+    'mips',
+    'mipsel',
+    'ppc',
+    'ppc64',
+    'riscv64',
+    's390',
+    's390x',
+    'x64',
+    'unknown',
+];
+const defaultClientFactory = async (apiKey, options) => {
+    const { PostHog } = await import('posthog-node');
+    return new PostHog(apiKey, options);
+};
+const syntheticSuccess = () => ({
+    status: 200,
+    text: () => Promise.resolve(''),
+    json: () => Promise.resolve({}),
+    headers: { get: () => null },
+    body: null,
+});
+export const createBoundedTelemetryFetch = (fetchImplementation, budgetMs) => async (url, options) => {
+    try {
+        // Leave time for the SDK to finish its queue drain before its own shutdown timer fires.
+        const requestBudgetMs = Math.max(1, budgetMs - Math.min(50, budgetMs / 2));
+        const signal = AbortSignal.timeout(requestBudgetMs);
+        const deadline = new Promise((resolve) => {
+            signal.addEventListener('abort', () => resolve(syntheticSuccess()), { once: true });
+        });
+        const request = fetchImplementation(url, { ...options, signal });
+        const response = await Promise.race([request, deadline]);
+        if (response.status >= 200 && response.status < 300)
+            return response;
+        void response.body?.cancel().catch(() => undefined);
+        return syntheticSuccess();
+    }
+    catch {
+        return syntheticSuccess();
+    }
+};
+const durationBucket = (milliseconds) => {
+    if (milliseconds < 1000)
+        return '<1s';
+    if (milliseconds < 5000)
+        return '1-5s';
+    if (milliseconds < 30_000)
+        return '5-30s';
+    return '30s+';
+};
+const knownValue = (values, value) => values.includes(value) ? value : 'unknown';
+export const buildCommandStartedProperties = (context, ci) => ({
+    command: context.command,
+    outfitter_version: context.outfitterVersion,
+    node_major: Number.parseInt(context.nodeVersion.split('.')[0], 10),
+    os_family: knownValue(OS_FAMILIES, context.platform),
+    arch: knownValue(ARCHITECTURES, context.architecture),
+    interactive: context.interactive,
+    harness: knownValue(HARNESSES, context.harness ?? 'unknown'),
+    strict: context.strict === true,
+    is_ci: ci.isCI,
+    ci_name: ci.isCI ? (ci.vendorId ?? 'unknown') : 'none',
+    $process_person_profile: false,
+});
+export const buildCommandCompletedProperties = (context, ci) => ({
+    ...buildCommandStartedProperties(context, ci),
+    outcome: context.outcome,
+    duration_bucket: durationBucket(context.durationMs),
+    exit_code_class: context.exitCode === 0 ? 'success' : 'error',
+    warning_count_bucket: 'unknown',
+});
+const NOTICE = [
+    'Outfitter sends pseudonymous command adoption and reliability analytics',
+    'to PostHog. No content, paths, or free-form arguments are collected.',
+    "Opt out: set 'telemetry.enabled: false' in ~/.agents/settings.yml, or set",
+    'OUTFITTER_TELEMETRY=0 / DO_NOT_TRACK=1.',
+    'Details:',
+    'https://github.com/ai-outfitter/outfitter/blob/main/docs/documentation/telemetry.md',
+].join('\n');
+export const createTelemetryService = (dependencies) => {
+    /* v8 ignore next -- tests never consume a compiled production key; they inject an empty or test key. */
+    const apiKey = dependencies.apiKey ?? POSTHOG_API_KEY;
+    const shutdownBudgetMs = dependencies.shutdownBudgetMs ?? TELEMETRY_SHUTDOWN_BUDGET_MS;
+    const clientFactory = dependencies.clientFactory ?? defaultClientFactory;
+    const ci = dependencies.ci;
+    let client;
+    let distinctId;
+    let prepared;
+    // Consent, client, and state are resolved once per process.
+    const prepare = async () => {
+        if (prepared !== undefined)
+            return prepared;
+        prepared = false;
+        // An empty compiled key keeps telemetry fully inert: no client, no consent read, no state access.
+        if (apiKey === '')
+            return false;
+        const consent = resolveTelemetryConsent(dependencies.settingsReader(), dependencies.env);
+        if (!consent.enabled) {
+            if (!ci.isCI)
+                dependencies.stateStore.delete();
+            return false;
+        }
+        client = await clientFactory(apiKey, {
+            host: POSTHOG_HOST,
+            disableGeoip: true,
+            fetch: createBoundedTelemetryFetch(globalThis.fetch.bind(globalThis), shutdownBudgetMs),
+        });
+        if (ci.isCI) {
+            distinctId = `ci.${ci.vendorId ?? 'unknown'}`;
+        }
+        else {
+            const state = dependencies.stateStore.readOrCreate();
+            distinctId = state.installation_id;
+            if (!state.notice_shown) {
+                dependencies.stateStore.recordNoticeShown(state);
+                dependencies.writeError(NOTICE);
+            }
+        }
+        prepared = true;
+        return true;
+    };
+    const capture = async (event, properties) => {
+        try {
+            if (!(await prepare()))
+                return;
+            const result = client.capture({ distinctId: distinctId, event, properties });
+            // The SDK queues synchronously. A non-standard client promise is observed but never allowed to delay the CLI.
+            void Promise.resolve(result).catch(() => undefined);
+        }
+        catch {
+            // Analytics must never affect command behavior or emit diagnostics.
+        }
+    };
+    return {
+        captureCommandStarted: (context) => capture('cli command started', buildCommandStartedProperties(context, ci)),
+        captureCommandCompleted: (context) => capture('cli command completed', buildCommandCompletedProperties(context, ci)),
+        async shutdown() {
+            if (client === undefined)
+                return;
+            try {
+                await client.shutdown(shutdownBudgetMs);
+            }
+            catch {
+                // Analytics must never affect command behavior or emit diagnostics.
+            }
+        },
+    };
+};
+//# sourceMappingURL=TelemetryService.js.map

package/dist/telemetry/TelemetryService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TelemetryService.js","sourceRoot":"","sources":["../../src/telemetry/TelemetryService.ts"],"names":[],"mappings":"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"}

package/dist/telemetry/TelemetryState.d.ts

@@ -0,0 +1,11 @@
+export interface TelemetryState {
+    readonly installation_id: string;
+    readonly notice_shown: boolean;
+}
+export interface TelemetryStateStore {
+    readOrCreate(): TelemetryState;
+    recordNoticeShown(state: TelemetryState): TelemetryState;
+    delete(): void;
+}
+export declare const resolveTelemetryStatePath: (homeDirectory: string, env: Readonly<Record<string, string | undefined>>) => string;
+export declare const createTelemetryStateStore: (path: string, createId?: () => string) => TelemetryStateStore;

package/dist/telemetry/TelemetryState.js

@@ -0,0 +1,51 @@
+import { randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { resolveOutfitterStateDir } from '../paths/OutfitterCache.js';
+export const resolveTelemetryStatePath = (homeDirectory, env) => join(resolveOutfitterStateDir(env, homeDirectory), 'telemetry.json');
+const isTelemetryState = (value) => {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const candidate = value;
+    return typeof candidate.installation_id === 'string' && typeof candidate.notice_shown === 'boolean';
+};
+export const createTelemetryStateStore = (path, createId = randomUUID) => {
+    const write = (state) => {
+        const directory = dirname(path);
+        const temporaryPath = join(directory, `.telemetry-${randomUUID()}.tmp`);
+        mkdirSync(directory, { recursive: true });
+        try {
+            writeFileSync(temporaryPath, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+            renameSync(temporaryPath, path);
+        }
+        finally {
+            rmSync(temporaryPath, { force: true });
+        }
+    };
+    return {
+        readOrCreate() {
+            if (existsSync(path)) {
+                try {
+                    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+                    if (isTelemetryState(parsed))
+                        return parsed;
+                }
+                catch {
+                    // A partial or corrupt state file is replaced with a fresh pseudonymous identifier.
+                }
+            }
+            const state = { installation_id: createId(), notice_shown: false };
+            write(state);
+            return state;
+        },
+        recordNoticeShown(state) {
+            const updated = { ...state, notice_shown: true };
+            write(updated);
+            return updated;
+        },
+        delete() {
+            rmSync(path, { force: true });
+        },
+    };
+};
+//# sourceMappingURL=TelemetryState.js.map

package/dist/telemetry/TelemetryState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TelemetryState.js","sourceRoot":"","sources":["../../src/telemetry/TelemetryState.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACjG,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAE1C,OAAO,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AAatE,MAAM,CAAC,MAAM,yBAAyB,GAAG,CACvC,aAAqB,EACrB,GAAiD,EACzC,EAAE,CAAC,IAAI,CAAC,wBAAwB,CAAC,GAAG,EAAE,aAAa,CAAC,EAAE,gBAAgB,CAAC,CAAC;AAElF,MAAM,gBAAgB,GAAG,CAAC,KAAc,EAA2B,EAAE;IACnE,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,SAAS,GAAG,KAAgC,CAAC;IACnD,OAAO,OAAO,SAAS,CAAC,eAAe,KAAK,QAAQ,IAAI,OAAO,SAAS,CAAC,YAAY,KAAK,SAAS,CAAC;AACtG,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,IAAY,EAAE,WAAyB,UAAU,EAAuB,EAAE;IAClH,MAAM,KAAK,GAAG,CAAC,KAAqB,EAAQ,EAAE;QAC5C,MAAM,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QAChC,MAAM,aAAa,GAAG,IAAI,CAAC,SAAS,EAAE,cAAc,UAAU,EAAE,MAAM,CAAC,CAAC;QACxE,SAAS,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1C,IAAI,CAAC;YACH,aAAa,CAAC,aAAa,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;YACrF,UAAU,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC;QAClC,CAAC;gBAAS,CAAC;YACT,MAAM,CAAC,aAAa,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACzC,CAAC;IACH,CAAC,CAAC;IAEF,OAAO;QACL,YAAY;YACV,IAAI,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;gBACrB,IAAI,CAAC;oBACH,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;oBAC/D,IAAI,gBAAgB,CAAC,MAAM,CAAC;wBAAE,OAAO,MAAM,CAAC;gBAC9C,CAAC;gBAAC,MAAM,CAAC;oBACP,oFAAoF;gBACtF,CAAC;YACH,CAAC;YACD,MAAM,KAAK,GAAG,EAAE,eAAe,EAAE,QAAQ,EAAE,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC;YACnE,KAAK,CAAC,KAAK,CAAC,CAAC;YACb,OAAO,KAAK,CAAC;QACf,CAAC;QACD,iBAAiB,CAAC,KAAqB;YACrC,MAAM,OAAO,GAAG,EAAE,GAAG,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;YACjD,KAAK,CAAC,OAAO,CAAC,CAAC;YACf,OAAO,OAAO,CAAC;QACjB,CAAC;QACD,MAAM;YACJ,MAAM,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAChC,CAAC;KACF,CAAC;AACJ,CAAC,CAAC"}

package/dist/version/OutfitterVersion.js

@@ -1,8 +1,11 @@
 // Reads the installed Outfitter package version for CLI output and runtime branding.
 import { readFileSync } from 'node:fs';
+let cachedVersion;
 export const readOutfitterVersion = () => {
-    const packageJsonPath = new URL('../../package.json', import.meta.url);
-    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
-    return packageJson.version;
+    if (cachedVersion === undefined) {
+        const packageJsonPath = new URL('../../package.json', import.meta.url);
+        cachedVersion = JSON.parse(readFileSync(packageJsonPath, 'utf8')).version;
+    }
+    return cachedVersion;
 };
 //# sourceMappingURL=OutfitterVersion.js.map

package/dist/version/OutfitterVersion.js.map

@@ -1 +1 @@
-{"version":3,"file":"OutfitterVersion.js","sourceRoot":"","sources":["../../src/version/OutfitterVersion.ts"],"names":[],"mappings":"AAAA,qFAAqF;AACrF,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,MAAM,CAAC,MAAM,oBAAoB,GAAG,GAAW,EAAE;IAC/C,MAAM,eAAe,GAAG,IAAI,GAAG,CAAC,oBAAoB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACvE,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,eAAe,EAAE,MAAM,CAAC,CAAiC,CAAC;IAEtG,OAAO,WAAW,CAAC,OAAO,CAAC;AAC7B,CAAC,CAAC"}
+{"version":3,"file":"OutfitterVersion.js","sourceRoot":"","sources":["../../src/version/OutfitterVersion.ts"],"names":[],"mappings":"AAAA,qFAAqF;AACrF,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,IAAI,aAAiC,CAAC;AAEtC,MAAM,CAAC,MAAM,oBAAoB,GAAG,GAAW,EAAE;IAC/C,IAAI,aAAa,KAAK,SAAS,EAAE,CAAC;QAChC,MAAM,eAAe,GAAG,IAAI,GAAG,CAAC,oBAAoB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACvE,aAAa,GAAI,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,eAAe,EAAE,MAAM,CAAC,CAAkC,CAAC,OAAO,CAAC;IAC9G,CAAC;IAED,OAAO,aAAa,CAAC;AACvB,CAAC,CAAC"}

package/docs/documentation/README.md

@@ -47,6 +47,7 @@ One runbook per rung of [the adoption ramp](../philosophy.md#the-ramp-to-an-auto
 The same composition runs on every surface; only the trigger changes.
 
 - [Running an agent in GitHub Actions](./actions.md) — headless runs on any workflow trigger.
+- [Channels](./channels.md) — add external event sources that wake a resident agent only when work arrives.
 - [Container images](./containers.md) — run the published Debian-based image persistently, extend it with apt, or use the `-nix` variant.
 - [Recurring runs](./recurring-runs.md) — loops three ways: the local loop extension, Actions cron, cluster schedules.
 - [In-cluster agents](./in-cluster.md) — resident agents, CronJobs, and subagent Jobs via Link Operator.
@@ -71,5 +72,6 @@ Each use case is a worked story — a problem, the composition that answers it,
 ## Reference
 
 - [CLI reference](./cli.md)
+- [Telemetry](./telemetry.md)
 - [Migration from legacy profiles](./migration.md)
 - [Philosophy](../philosophy.md) — why Outfitter exists.

package/docs/documentation/channels.md

@@ -0,0 +1,112 @@
+# Channels
+
+A **channel** is an external source of work an agent watches — a mailbox, Signal,
+GitHub notifications, or a chat service. The
+[`ai-outfitter/channels`](https://github.com/ai-outfitter/channels) Pi extension
+owns those transports as source modules under `extensions/sources/`. A source
+opens its push connection, daemon, or polling loop and sends an **idle-gated
+wake** only when it detects matching work. Multiple sources can run at once and
+feed one notification queue.
+
+Every wake is a trusted, body-free signal. Sources that support exact-item
+actions put only an opaque locator in the wake; the agent passes that locator
+unchanged to `channel_read`, which returns the message inside explicit
+untrusted-content markers. It replies through `channel_respond`. Signal-only
+sources instead wake the agent to use that channel's existing client workflow.
+In neither case does an external message enter the session as an instruction.
+
+The extension and the response instructions have separate jobs:
+
+- `git:github.com/ai-outfitter/channels` supplies event delivery and the common
+  channel tools;
+- skills and runbooks in the Channels repository teach the agent how to handle
+  each source.
+
+Those channel skills are not published by the `community-profiles` catalog. For
+example, Channels currently carries its Slack workflow at
+[`dev/slack-responder/SKILL.md`](https://github.com/ai-outfitter/channels/blob/main/dev/slack-responder/SKILL.md)
+and its operational guides under
+[`docs/runbooks/`](https://github.com/ai-outfitter/channels/tree/main/docs/runbooks).
+
+## Add channels to an agent
+
+Add the Channels extension source to the agent's [loadout](./agents.md):
+
+```markdown
+---
+name: email-assistant
+extensions: [git:github.com/ai-outfitter/channels]
+model: your-model
+---
+```
+
+Then follow the source-specific skill or runbook in the Channels repository and
+provide that source's credentials. Do not add `mail`, `signal-responder`, or
+`slack-responder` on the assumption that they are community-catalog skill IDs.
+If you want to use the repository's development Slack skill, bring that skill
+into a catalog you control and select its resulting local ID.
+
+Because an [agent _is_ the profile](./profiles.md), a multi-channel agent still
+loads the extension only once:
+
+```markdown
+---
+name: personal-assistant
+extensions: [git:github.com/ai-outfitter/channels]
+---
+```
+
+All configured sources feed a single notification queue. Each wake names the
+sources with activity and, when available, includes opaque locators for the
+agent to pass to the common channel tools.
+
+## Select which channels run
+
+`OUTFITTER_CHANNELS` chooses the active channels; unset means **auto-detect** —
+every channel whose credentials are present starts. So composing a channel into an
+agent is really just supplying its credentials.
+
+| `OUTFITTER_CHANNELS` | Behavior                   |
+| -------------------- | -------------------------- |
+| unset                | Auto-detect by credentials |
+| `jmap,signal`        | Exactly those channels     |
+| `off` / `none`       | Disabled                   |
+
+## Credentials per channel
+
+Each source reads its configuration from environment variables. Supply them the
+Outfitter way for where the agent runs:
+
+- **Local runs** — export them in the shell before `outfitter run` (see the
+  [channels README](https://github.com/ai-outfitter/channels) for the bare-pi
+  flow).
+- **In-cluster** — project them as env from Secrets via the Kubernetes operator;
+  the operator exposes referenced Secrets without inspecting them, and the keys
+  inside are each channel's contract.
+
+| Source                   | Delivery                                                 | Variables                                                                                            |
+| ------------------------ | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `jmap` (email over JMAP) | JMAP state-change wake                                   | `XIN_BASE_URL`, `XIN_BASIC_USER`, `XIN_BASIC_PASS`                                                   |
+| `signal`                 | `signal-cli` wake                                        | `SIGNAL_NUMBER`, `SIGNAL_CLI_CONFIG`                                                                 |
+| `slack`                  | Socket Mode wake plus `channel_read` / `channel_respond` | `SLACK_APP_TOKEN`, `SLACK_BOT_TOKEN`, optional `SLACK_CHANNEL_IDS`                                   |
+| `github`                 | filtered notification wake                               | `GITHUB_NOTIFY_TOKEN` (or `GITHUB_TOKEN`), optional `GITHUB_NOTIFY_FILTERS`, `GITHUB_NOTIFY_POLL_MS` |
+
+This is only a quick orientation; the Channels README is the source of truth for
+the complete source list, credentials, prerequisites, and behavior. For a
+concrete email deployment, see its
+[Google Workspace agent-mailbox runbook](https://github.com/ai-outfitter/channels/blob/main/docs/runbooks/agent-mailbox-google-workspace.md).
+
+## Running resident
+
+A channel watcher opens push connections for the life of a session, so it needs a
+long-running agent — an interactive session, `--mode rpc`, or an always-on
+in-cluster deployment. Session switches reopen the connections; one-shot print runs
+are not suitable.
+
+## See also
+
+- [`ai-outfitter/channels`](https://github.com/ai-outfitter/channels) — the
+  extension source, channel source modules, skills, runbooks, and setup.
+- [Skills](./skills.md) — how to bring a repository-owned channel skill into a
+  catalog and select it in a loadout.
+- [Agents](./agents.md) / [Profiles](./profiles.md) — loadout and composition.

package/docs/documentation/cli.md

@@ -7,6 +7,8 @@ Global options:
 | `-V, --version` | Print the Outfitter version. |
 | `-h, --help`    | Show help for a command.     |
 
+See [Telemetry](./telemetry.md) for the pseudonymous analytics event contract and opt-out controls.
+
 ## `outfitter run [agent] [args...]`
 
 Resolve, compose, and launch an agent. `run` is the default command, so plain `outfitter` and `outfitter run` are equivalent.
@@ -29,6 +31,13 @@ outfitter run engineer --harness codex -- exec "review this repo"
 outfitter run persona-reviewer -- --print "summarize this repo"
 ```
 
+Because `run` is the default command, leading flags that Outfitter does not own are forwarded to the harness automatically. With a configured `default_agent`, the following forms pass flags directly to Pi:
+
+```bash
+outfitter -r            # equivalent to: outfitter run -- -r
+outfitter --resume      # equivalent to: outfitter run -- --resume
+```
+
 ## `outfitter setup [source]`
 
 Open the bundled Pi walkthrough using the original setup wording and sequence. Choose **Use the

package/docs/documentation/settings.md

@@ -40,6 +40,10 @@ remote_settings:
     ref: 9c47d1e2b8a05f36c4d7e90a12b3f8c5d6e71a04
 
 cache_directory: ./cache # optional; relative to this settings file
+
+# Pseudonymous product analytics consent; defaults to true when absent.
+telemetry:
+  enabled: false
 ```
 
 - `default_agent` / `default_harness` — which agent plain `outfitter` runs, and the harness it launches in.
@@ -48,6 +52,7 @@ cache_directory: ./cache # optional; relative to this settings file
 - `cache_directory` — the repository cache root used consistently by sync, remote settings, remote
   source resolution, and default-catalog setup. It defaults to `~/.agents/cache`; repositories live
   below its `repos/` directory.
+- `telemetry.enabled` — the primary and sole persistent control for pseudonymous product analytics. Edit it directly to enable or disable telemetry. See [Telemetry](./telemetry.md) for consent precedence, automatic identifier cleanup, the event contract, and the current inert-build status.
 
 ## Precedence