@ascenda-one/github-collector 0.1.18 → 0.1.19

package/README.md

@@ -52,6 +52,11 @@ separately revocable.
 
 ## Use in GitHub Actions
 
+Ready to copy: [`examples/workflow.yml`](./examples/workflow.yml). Both secrets
+come from pairing a collector identity of its own —
+`npx -y @ascenda-one/claude-code-hooks pair --tool-type github_collector` — which
+prints the installation id and names the token file to read.
+
 ```yaml
 name: ascenda-collaboration
 on:

package/dist/cli.js

@@ -583,7 +583,61 @@ var require_out = __commonJS({
   "../packages/tool-contract/out/index.js"(exports) {
     "use strict";
     Object.defineProperty(exports, "__esModule", { value: true });
-    exports.backendMetricKeys = exports.METRIC_KEYS = exports.ASCENDA_SEMANTIC_PROVENANCE = exports.ASCENDA_HISTORICAL_CONSENT_SCOPE = exports.ASCENDA_COLLABORATION_CONSENT_SCOPE = exports.ASCENDA_SEMANTIC_CONSENT_SCOPE = exports.ASCENDA_PROVENANCE = exports.ASCENDA_CONSENT_SCOPE = exports.EVENT_WORKLOAD_CATEGORY = exports.TOOL_EVENT_DELIVERED_STATUSES = exports.IDEMPOTENCY_KEY_MAX_LENGTH = exports.EVENT_METADATA_FIELDS = exports.COLLABORATION_EVENT_TYPES = exports.SEMANTIC_WORK_SIGNAL_EVENT_TYPES = void 0;
+    exports.backendMetricKeys = exports.METRIC_KEYS = exports.ASCENDA_SEMANTIC_PROVENANCE = exports.ASCENDA_HISTORICAL_CONSENT_SCOPE = exports.ASCENDA_COLLABORATION_CONSENT_SCOPE = exports.ASCENDA_SEMANTIC_CONSENT_SCOPE = exports.ASCENDA_PROVENANCE = exports.ASCENDA_CONSENT_SCOPE = exports.EVENT_WORKLOAD_CATEGORY = exports.TOOL_EVENT_DELIVERED_STATUSES = exports.IDEMPOTENCY_KEY_MAX_LENGTH = exports.EVENT_METADATA_FIELDS = exports.COLLABORATION_EVENT_TYPES = exports.SEMANTIC_WORK_SIGNAL_EVENT_TYPES = exports.ASCENDA_ELAPSED_QUANTITIES = exports.ASCENDA_ACTIVE_TIME_QUANTITIES = exports.ASCENDA_TOOL_TYPES = exports.ASCENDA_TELEMETRY_SOURCES = void 0;
+    exports.combineDisjointHalves = combineDisjointHalves;
+    exports.requireComparableQuantities = requireComparableQuantities;
+    exports.ASCENDA_TELEMETRY_SOURCES = [
+      "vscode_extension",
+      "cursor_mcp",
+      "claude_code",
+      "copilot_otel",
+      "cli_agent",
+      "mcp_server",
+      "activity_signals",
+      "code_forge"
+    ];
+    exports.ASCENDA_TOOL_TYPES = [
+      "vscode_extension",
+      "cursor_mcp",
+      "claude_code",
+      "copilot_otel",
+      "cli_agent",
+      "mcp_server",
+      "github_collector",
+      "other"
+    ];
+    exports.ASCENDA_ACTIVE_TIME_QUANTITIES = [
+      "coverage",
+      "hands_on",
+      "supervising",
+      "block_coverage",
+      "hands_on_agent_hours",
+      "supervising_agent_hours"
+    ];
+    exports.ASCENDA_ELAPSED_QUANTITIES = {
+      coverage: true,
+      hands_on: true,
+      supervising: true,
+      block_coverage: true,
+      hands_on_agent_hours: false,
+      supervising_agent_hours: false
+    };
+    var DISJOINT_HALVES = [
+      ["hands_on", "supervising", "coverage"],
+      ["supervising", "hands_on", "coverage"]
+    ];
+    function combineDisjointHalves(left, leftQuantity, right, rightQuantity) {
+      const pair = DISJOINT_HALVES.find(([a, b]) => a === leftQuantity && b === rightQuantity);
+      if (!pair) {
+        throw new Error(`'combine-disjoint' combines active-time quantities '${leftQuantity}' and '${rightQuantity}', which do not partition a common whole.`);
+      }
+      return { total: left + right, quantity: pair[2] };
+    }
+    function requireComparableQuantities(left, right, operation) {
+      if (left !== right) {
+        throw new Error(`'${operation}' combines active-time quantities '${left}' and '${right}', which measure different things. See docs/ACTIVE_TIME.md, 'The quantity is the label, not the gap'.`);
+      }
+    }
     exports.SEMANTIC_WORK_SIGNAL_EVENT_TYPES = [
       "approach_churn_detected",
       "goal_drift_detected",
@@ -1167,12 +1221,11 @@ var require_stateStore = __commonJS({
     exports.shouldAnnounceFailure = shouldAnnounceFailure;
     exports.markFailureNotified = markFailureNotified;
     var fs = __importStar(__require("fs"));
-    var os = __importStar(__require("os"));
     var path = __importStar(__require("path"));
     var tokenStore_1 = require_tokenStore();
     function defaultStateFilePath(toolInstallationId) {
       const dir = process.env.ASCENDA_STATE_DIR?.trim();
-      const base2 = dir ? dir : path.join(os.homedir(), ".ascenda", "state");
+      const base2 = dir ? dir : path.join((0, tokenStore_1.ascendaHome)(), "state");
       return path.join(base2, `${(0, tokenStore_1.sanitizeFilePart)(toolInstallationId)}.json`);
     }
     function unresolvedToolInstallationId(toolType) {
@@ -1494,6 +1547,25 @@ var require_outbox = __commonJS({
   }
 });
 
+// ../packages/tool-kit/out/timeProvider.js
+var require_timeProvider = __commonJS({
+  "../packages/tool-kit/out/timeProvider.js"(exports) {
+    "use strict";
+    Object.defineProperty(exports, "__esModule", { value: true });
+    exports.systemTimeProvider = void 0;
+    exports.fixedTimeProvider = fixedTimeProvider;
+    exports.systemTimeProvider = {
+      now: () => Date.now()
+    };
+    function fixedTimeProvider(instant) {
+      const ms = typeof instant === "number" ? instant : new Date(instant).valueOf();
+      if (!Number.isFinite(ms))
+        throw new TypeError(`fixedTimeProvider: not a usable instant: ${String(instant)}`);
+      return { now: () => ms };
+    }
+  }
+});
+
 // ../packages/tool-kit/out/eventSender.js
 var require_eventSender = __commonJS({
   "../packages/tool-kit/out/eventSender.js"(exports) {
@@ -1506,6 +1578,7 @@ var require_eventSender = __commonJS({
     var eventLog_1 = require_eventLog();
     var http_1 = require_http();
     var outbox_1 = require_outbox();
+    var timeProvider_1 = require_timeProvider();
     var tokenStore_1 = require_tokenStore();
     var stateStore_1 = require_stateStore();
     var payload_1 = require_payload();
@@ -1542,9 +1615,12 @@ var require_eventSender = __commonJS({
       lastDrain;
       /** One outbox pass per sender, i.e. per hook process. The hook is on the user's critical path. */
       outboxServiced = false;
+      /** Resolved once, so every clock read in one pass sees the same instant. */
+      time;
       constructor(config) {
         this.config = config;
         this.eventWriteToken = config.eventWriteToken;
+        this.time = config.timeProvider ?? timeProvider_1.systemTimeProvider;
       }
       async send(mapped) {
         return this.post(buildEventPayload(this.config, mapped));
@@ -1695,7 +1771,7 @@ var require_eventSender = __commonJS({
        * journal's detail says so instead of implying it was kept.
        */
       enqueue(payload) {
-        return (0, outbox_1.appendToOutbox)(this.outboxFilePath(), payload);
+        return (0, outbox_1.appendToOutbox)(this.outboxFilePath(), payload, new Date(this.time.now()));
       }
       /**
        * One pass over the outbox: claim it, apply the bounds, and — when sending
@@ -1718,7 +1794,7 @@ var require_eventSender = __commonJS({
           return void 0;
         this.outboxServiced = true;
         const sendEnabled = this.config.outboxDrain ?? (0, outbox_1.outboxDrainEnabled)();
-        const claimed = (0, outbox_1.claimOutbox)(this.outboxFilePath());
+        const claimed = (0, outbox_1.claimOutbox)(this.outboxFilePath(), this.time.now());
         if (!claimed) {
           this.lastDrain = { found: 0, discarded: 0, delivered: 0, remaining: 0, sendEnabled };
           return void 0;
@@ -1727,7 +1803,7 @@ var require_eventSender = __commonJS({
         const { kept, discarded } = (0, outbox_1.enforceOutboxBounds)(claimed.entries, {
           maxEntries: this.config.outboxMaxEntries ?? outbox_1.DEFAULT_OUTBOX_MAX_ENTRIES,
           maxAgeMs: this.config.outboxMaxAgeMs ?? outbox_1.DEFAULT_OUTBOX_MAX_AGE_MS
-        });
+        }, this.time.now());
         if (claimed.unreadable > 0) {
           discarded.count += claimed.unreadable;
           discarded.reasons.unreadable = claimed.unreadable;
@@ -3149,9 +3225,9 @@ var require_turnState = __commonJS({
     exports.recordTurnStart = recordTurnStart;
     exports.consumeTurnDurationMs = consumeTurnDurationMs;
     var fs = __importStar(__require("fs"));
-    var os = __importStar(__require("os"));
     var path = __importStar(__require("path"));
-    var stateDir = () => process.env.ASCENDA_STATE_DIR ?? path.join(os.homedir(), ".ascenda", "state");
+    var tokenStore_1 = require_tokenStore();
+    var stateDir = () => process.env.ASCENDA_STATE_DIR ?? path.join((0, tokenStore_1.ascendaHome)(), "state");
     function turnFile(agent, sessionId) {
       return path.join(stateDir(), `${sanitize(agent)}-turn-${sanitize(sessionId)}`);
     }
@@ -3318,8 +3394,8 @@ var require_out2 = __commonJS({
     "use strict";
     Object.defineProperty(exports, "__esModule", { value: true });
     exports.consumeTurnDurationMs = exports.writeTopLevelCredentials = exports.writeMachineCredentials = exports.writeHostCredentials = exports.removeHostCredentials = exports.readMachineCredentials = exports.readHostCredentials = exports.credentialsFilePath = exports.writeHookSettings = exports.runCliAgentSetup = exports.isCliAgentManagementCommand = exports.findStaleHookCommands = exports.cliAgentHookBinPath = exports.resolveContextHashes = exports.resolveCliAgentInstallationId = exports.loadCliAgentConfig = exports.deliverHookEvents = exports.MissingInstallationIdError = exports.DEFAULT_API_BASE_URL = exports.resolveEventLogPath = exports.expandUserPath = exports.appendEventLog = exports.EVENT_LOG_ENV_VAR = exports.buildEventPayload = exports.AscendaSemanticEventError = exports.AscendaEventSender = exports.mintIdempotencyKey = exports.looksLikeCorrection = exports.outcomeForHook = exports.inferOutcome = exports.getNestedNumber = exports.getNestedString = exports.getNested = exports.getNumber = exports.getString = exports.localHourAt = exports.utcOffsetMinutesAt = exports.BUSINESS_DAY = exports.isOutsideBusinessHours = exports.isAfterHours = exports.bucketDurationMs = exports.bucketLinesChanged = exports.classifyModelClass = exports.autonomyBand = exports.invitesDebrief = exports.classifyWorkMilestone = exports.isReworkGitAction = exports.classifyGitAction = exports.isVerificationCommand = exports.classifyCommand = void 0;
-    exports.postToolEvent = exports.renewToolToken = exports.getPairingStatus = exports.createPairingSession = exports.AscendaApiError = exports.liveBusSocketCandidates = exports.liveBusSocketPath = exports.bucketPromptSize = exports.emitLiveSignal = exports.recordForgeProjectAlias = exports.forgeFullNameFromConfig = exports.readForgeFullName = exports.parseForgeFullName = exports.forgeProjectHash = exports.workContextRegistryFilePath = exports.readWorkContextRegistry = exports.recordWorkContextAlias = exports.recordWorkContext = exports.readBranchName = exports.normalizeBranchName = exports.deriveBranchHashForCwd = exports.deriveBranchHash = exports.deriveWorkContext = exports.hashWithMachineSalt = exports.readOrCreateMachineSalt = exports.machineSaltFilePath = exports.enforceOutboxBounds = exports.claimOutbox = exports.readOutboxSummary = exports.appendToOutbox = exports.defaultOutboxFilePath = exports.outboxDrainEnabled = exports.DEFAULT_OUTBOX_DRAIN_BATCH_SIZE = exports.DEFAULT_OUTBOX_MAX_AGE_MS = exports.DEFAULT_OUTBOX_MAX_ENTRIES = exports.OUTBOX_DRAIN_ENV_VAR = exports.recordOutboxDiscard = exports.unresolvedToolInstallationId = exports.unresolvedStateFilePath = exports.markFailureNotified = exports.shouldAnnounceFailure = exports.recordSendOutcome = exports.readCollectorState = exports.defaultStateFilePath = exports.readTokenFile = exports.persistEventWriteToken = exports.listPersistedToolInstallationIds = exports.defaultTokenFilePath = exports.ascendaHome = exports.recordTurnStart = void 0;
-    exports.isRetryableStatus = exports.parseIngestResponse = exports.postToolEventsBatch = void 0;
+    exports.getPairingStatus = exports.createPairingSession = exports.AscendaApiError = exports.liveBusSocketCandidates = exports.liveBusSocketPath = exports.bucketPromptSize = exports.emitLiveSignal = exports.recordForgeProjectAlias = exports.forgeFullNameFromConfig = exports.readForgeFullName = exports.parseForgeFullName = exports.forgeProjectHash = exports.workContextRegistryFilePath = exports.readWorkContextRegistry = exports.recordWorkContextAlias = exports.recordWorkContext = exports.readBranchName = exports.normalizeBranchName = exports.deriveBranchHashForCwd = exports.deriveBranchHash = exports.deriveWorkContext = exports.hashWithMachineSalt = exports.readOrCreateMachineSalt = exports.machineSaltFilePath = exports.fixedTimeProvider = exports.systemTimeProvider = exports.enforceOutboxBounds = exports.claimOutbox = exports.readOutboxSummary = exports.appendToOutbox = exports.defaultOutboxFilePath = exports.outboxDrainEnabled = exports.DEFAULT_OUTBOX_DRAIN_BATCH_SIZE = exports.DEFAULT_OUTBOX_MAX_AGE_MS = exports.DEFAULT_OUTBOX_MAX_ENTRIES = exports.OUTBOX_DRAIN_ENV_VAR = exports.recordOutboxDiscard = exports.unresolvedToolInstallationId = exports.unresolvedStateFilePath = exports.markFailureNotified = exports.shouldAnnounceFailure = exports.recordSendOutcome = exports.readCollectorState = exports.defaultStateFilePath = exports.readTokenFile = exports.persistEventWriteToken = exports.listPersistedToolInstallationIds = exports.defaultTokenFilePath = exports.ascendaHome = exports.recordTurnStart = void 0;
+    exports.isRetryableStatus = exports.parseIngestResponse = exports.postToolEventsBatch = exports.postToolEvent = exports.renewToolToken = void 0;
     var commandClassifier_1 = require_commandClassifier();
     Object.defineProperty(exports, "classifyCommand", { enumerable: true, get: function() {
       return commandClassifier_1.classifyCommand;
@@ -3559,6 +3635,13 @@ var require_out2 = __commonJS({
     Object.defineProperty(exports, "enforceOutboxBounds", { enumerable: true, get: function() {
       return outbox_1.enforceOutboxBounds;
     } });
+    var timeProvider_1 = require_timeProvider();
+    Object.defineProperty(exports, "systemTimeProvider", { enumerable: true, get: function() {
+      return timeProvider_1.systemTimeProvider;
+    } });
+    Object.defineProperty(exports, "fixedTimeProvider", { enumerable: true, get: function() {
+      return timeProvider_1.fixedTimeProvider;
+    } });
     var salt_1 = require_salt();
     Object.defineProperty(exports, "machineSaltFilePath", { enumerable: true, get: function() {
       return salt_1.machineSaltFilePath;

package/examples/workflow.yml

@@ -0,0 +1,29 @@
+# Collaboration signals — review load and pull-request activity — for one
+# repository. Drop this at .github/workflows/ascenda-collaboration.yml.
+#
+# Both secrets come from pairing a collector identity on your machine:
+#   npx -y @ascenda-one/claude-code-hooks pair --tool-type github_collector
+# which prints the installation id and the path of the token file to read.
+#
+# This collector has its own tool type and rides workflow_telemetry, not
+# ide_telemetry: how you work with your team is separately revocable from
+# how you work in your editor.
+name: ascenda-collaboration
+
+on:
+  pull_request:
+    types: [opened, review_requested]
+  pull_request_review:
+    types: [submitted]
+
+jobs:
+  collect:
+    runs-on: ubuntu-latest
+    steps:
+      # Exits 0 on every path that is not a configuration error, including
+      # "nothing to emit" — a telemetry step must never turn a build red.
+      - run: npx @ascenda-one/github-collector
+        env:
+          ASCENDA_TOOL_INSTALLATION_ID: ${{ secrets.ASCENDA_TOOL_INSTALLATION_ID }}
+          ASCENDA_EVENT_WRITE_TOKEN: ${{ secrets.ASCENDA_EVENT_WRITE_TOKEN }}
+          ASCENDA_FORGE_LOGIN: ${{ github.actor }}

package/package.json

@@ -1,7 +1,7 @@
 {
   "publishConfig": { "access": "public" },
   "name": "@ascenda-one/github-collector",
-  "version": "0.1.18",
+  "version": "0.1.19",
   "description": "Code-forge collaboration collector for Ascenda work telemetry — first-person review and pull-request signals.",
   "repository": {
     "type": "git",