atris 3.2.0 → 3.5.0

package/commands/context-sync.js

@@ -281,6 +281,11 @@ async function businessLog(slug) {
 }
 
 
+/**
+ * Convert ISO timestamp to human-readable relative time (e.g., "5m ago").
+ * @param {string} isoString - ISO 8601 timestamp
+ * @returns {string|null} Relative time string, or null if no input
+ */
 function _timeSince(isoString) {
   if (!isoString) return null;
   const diff = Date.now() - new Date(isoString).getTime();

package/commands/lifecycle.js

@@ -3,6 +3,10 @@ const path = require('path');
 const { loadCredentials } = require('../utils/auth');
 const { apiRequestJson } = require('../utils/api');
 
+/**
+ * Resolve business slug from CLI arg or local .atris/business.json.
+ * @returns {string|null} The resolved slug, or null if not found.
+ */
 function resolveSlug() {
   let slug = process.argv[3];
   if (!slug || slug.startsWith('-')) {
@@ -18,6 +22,10 @@ function resolveSlug() {
   return slug;
 }
 
+/**
+ * Pause a workspace to save compute (storage only mode).
+ * @returns {Promise<void>}
+ */
 async function sleepAtris() {
   const slug = resolveSlug();
 
@@ -45,6 +53,10 @@ async function sleepAtris() {
   console.log('Compute paused. Storage only — pennies/day.');
 }
 
+/**
+ * Wake a sleeping workspace so agents resume automatically.
+ * @returns {Promise<void>}
+ */
 async function wakeAtris() {
   const slug = resolveSlug();
 

package/commands/plugin.js

@@ -6,6 +6,11 @@ const { findAllSkills, parseFrontmatter } = require('./skill');
 
 // --- Recursive Copy Helper ---
 
+/**
+ * Recursively copy a directory, skipping .DS_Store and .git.
+ * @param {string} src - Source directory path
+ * @param {string} dest - Destination directory path
+ */
 function copyRecursive(src, dest) {
   fs.mkdirSync(dest, { recursive: true });
   const entries = fs.readdirSync(src);
@@ -23,6 +28,12 @@ function copyRecursive(src, dest) {
 
 // --- Generate plugin.json manifest ---
 
+/**
+ * Generate plugin.json manifest from discovered skills.
+ * @param {Array} skills - Array of skill objects
+ * @param {string} projectDir - Project root directory
+ * @returns {Object} Plugin manifest object
+ */
 function generateManifest(skills, projectDir) {
   let pkg = {};
   const pkgPath = path.join(projectDir, 'package.json');
@@ -44,6 +55,10 @@ function generateManifest(skills, projectDir) {
 
 // --- Generate /atris-setup command ---
 
+/**
+ * Generate the /atris-setup skill markdown for workspace bootstrapping.
+ * @returns {string} Skill markdown content
+ */
 function generateSetupCommand() {
   return `---
 description: Set up Atris authentication and connect integrations (Gmail, Calendar, Slack, Notion, Drive)
@@ -113,6 +128,11 @@ Tell the user which integrations are connected and which still need setup. They
 
 // --- Generate README.md ---
 
+/**
+ * Generate README.md for the plugin package.
+ * @param {Array} skills - Array of discovered skills
+ * @returns {string} README markdown content
+ */
 function generateREADME(skills) {
   const skillList = skills.map(s => {
     const fm = s.frontmatter || {};
@@ -149,6 +169,10 @@ ${skillList}
 
 // --- BUILD subcommand ---
 
+/**
+ * Build the plugin package from atris/skills into dist/.
+ * @param {...string} args - CLI arguments
+ */
 function buildPlugin(...args) {
   const projectDir = process.cwd();
   const atrisDir = path.join(projectDir, 'atris');

package/commands/pull.js

@@ -9,6 +9,7 @@ const { parseJournalSections, mergeSections, reconstructJournal } = require('../
 const { loadBusinesses } = require('./business');
 const { loadManifest, saveManifest, computeFileHash, buildManifest, computeLocalHashes, threeWayCompare } = require('../lib/manifest');
 const { normalizeWikiOnlyPrefix } = require('../lib/wiki');
+const { emitSyncEvent, startTimer } = require('../lib/sync-telemetry');
 
 function pruneEmptyParentDirs(filePath, stopDir) {
   let current = path.dirname(filePath);
@@ -114,6 +115,7 @@ async function pullAtris() {
 
 
 async function pullBusiness(slug) {
+  const elapsedMs = startTimer();
   const creds = loadCredentials();
   if (!creds || !creds.token) {
     console.error('Not logged in. Run: atris login');
@@ -223,6 +225,11 @@ async function pullBusiness(slug) {
     process.exit(1);
   }
 
+  // Telemetry helper — captures wall-clock time including wake.
+  let _coldWake = false;
+  const emit = (outcome, extras = {}) =>
+    emitSyncEvent(creds.token, businessId, workspaceId, 'pull', outcome, elapsedMs(), extras);
+
   // Auto-wake the EC2 computer if --auto-wake is set.
   // Without this, pull silently serves stale data from agent_files cache when
   // the computer is asleep — the bug that confused us all night.
@@ -232,6 +239,7 @@ async function pullBusiness(slug) {
     const computerStatus = statusResult.ok && statusResult.data ? statusResult.data.status : 'unknown';
     if (computerStatus !== 'running' || !(statusResult.data && statusResult.data.endpoint)) {
       process.stdout.write('  Waking EC2 computer... ');
+      _coldWake = true;
       await apiRequestJson(`/business/${businessId}/ai-computer/wake`, { method: 'POST', token: creds.token });
       const wakeStart = Date.now();
       while (Date.now() - wakeStart < 90000) {
@@ -355,20 +363,30 @@ async function pullBusiness(slug) {
 
   if (!result.ok) {
     const msg = result.errorMessage || result.error || `HTTP ${result.status}`;
+    let outcome = 'status_unknown';
     if (result.status === 0 || (typeof msg === 'string' && msg.toLowerCase().includes('timeout'))) {
       console.error(`\n  Workspace timed out (large workspaces can take 60s+). Try: atris pull ${slug} --timeout=600`);
+      outcome = 'hang';
     } else if (result.status === 502) {
       console.error(`\n  Computer didn't respond in time. It may be waking up or the workspace is large.`);
       console.error(`  Try again in 30s, or use: atris pull ${slug} --only=team/,context/`);
+      outcome = 'cold_wake';
     } else if (result.status === 409) {
       console.error(`\n  Computer is sleeping. Wake it first, then pull again.`);
+      outcome = 'cold_wake';
     } else if (result.status === 403) {
       console.error(`\n  Access denied. You're not a member of "${slug}".`);
+      outcome = 'access_denied';
     } else if (result.status === 404) {
       console.error(`\n  Business "${slug}" not found.`);
+      outcome = 'status_unknown';
+    } else if (result.status === 429) {
+      console.error(`\n  Pull failed: ${msg}`);
+      outcome = 'rate_limited';
     } else {
       console.error(`\n  Pull failed: ${msg}`);
     }
+    await emit(outcome, { error_detail: `${result.status}: ${msg}`.slice(0, 500) });
     process.exit(1);
   }
 
@@ -379,7 +397,10 @@ async function pullBusiness(slug) {
     // mirror sweep so a genuinely-emptied cloud can clear local files. The
     // sweep itself has a safety guard that refuses to wipe local content
     // when remote reports empty (the snapshot-glitch case), so this is safe.
-    if (!force) return;
+    if (!force) {
+      await emit(_coldWake ? 'cold_wake' : 'success', { files_unchanged: 0 });
+      return;
+    }
   } else {
     console.log(`  Processing ${files.length} files...`);
   }
@@ -702,6 +723,24 @@ async function pullBusiness(slug) {
     }
   }
 
+  // Telemetry — only count files where content actually came over the wire
+  // (smart-pull skips unchanged files and just sends a hash). Counting all
+  // remoteFiles here would dwarf the real signal once smart-pull steady-state
+  // is normal (< 1% of files transferred per pull).
+  let bytesTransferred = 0;
+  let filesTransferred = 0;
+  for (const filePath of Object.keys(remoteContent)) {
+    const f = remoteFiles[filePath];
+    if (f && typeof f.size === 'number') bytesTransferred += f.size;
+    filesTransferred++;
+  }
+  const totalRemote = Object.keys(remoteFiles).length;
+  await emit(_coldWake ? 'cold_wake' : 'success', {
+    files_pushed: filesTransferred,
+    files_unchanged: Math.max(0, totalRemote - filesTransferred),
+    bytes_transferred: bytesTransferred,
+    bytes_changed: bytesTransferred,
+  });
 }
 
 

package/commands/push.js

@@ -6,9 +6,12 @@ const { apiRequestJson } = require('../utils/api');
 const { loadBusinesses, saveBusinesses } = require('./business');
 const { loadManifest, saveManifest, buildManifest, computeLocalHashes } = require('../lib/manifest');
 const { normalizeWikiOnlyPrefix } = require('../lib/wiki');
+const { emitSyncEvent, startTimer } = require('../lib/sync-telemetry');
 
 async function pushAtris() {
+  const elapsedMs = startTimer();
   let slug = process.argv[3];
+  let _coldWake = false;
 
   // Auto-detect business from .atris/business.json in current dir
   if (!slug || slug.startsWith('-')) {
@@ -105,6 +108,11 @@ async function pushAtris() {
 
   if (!workspaceId) { console.error(`Business "${slug}" has no workspace.`); process.exit(1); }
 
+  // Telemetry helper — emits one event with the elapsed wall-clock time.
+  // Awaited (not fire-and-forget) because process.exit kills in-flight requests.
+  const emit = (outcome, extras = {}) =>
+    emitSyncEvent(creds.token, businessId, workspaceId, 'push', outcome, elapsedMs(), extras);
+
   // Auto-wake the EC2 computer if --auto-wake is set, otherwise check status and warn.
   // Without this, push silently routes to agent_files cache when computer is asleep
   // (the silent fallback footgun from tonight's debugging).
@@ -114,6 +122,7 @@ async function pushAtris() {
     const computerStatus = statusResult.ok && statusResult.data ? statusResult.data.status : 'unknown';
     if (computerStatus !== 'running' || !(statusResult.data && statusResult.data.endpoint)) {
       process.stdout.write('  Waking EC2 computer... ');
+      _coldWake = true;
       await apiRequestJson(`/business/${businessId}/ai-computer/wake`, { method: 'POST', token: creds.token });
       const wakeStart = Date.now();
       while (Date.now() - wakeStart < 90000) {
@@ -204,6 +213,7 @@ async function pushAtris() {
         console.log('');
         console.log('    Run `atris pull` first, then push your changes.');
         console.log('    To override (force-push, may clobber cloud edits): atris push --force');
+        await emit('drift', { error_detail: `${driftFiles.length} file(s) drifted` });
         process.exit(1);
       }
       console.log('fresh');
@@ -218,6 +228,7 @@ async function pushAtris() {
       console.log('  ✗ Could not verify cloud freshness. Refusing to push.');
       console.log('    The workspace may be unreachable or the snapshot endpoint is broken.');
       console.log('    To bypass and force-push anyway: atris push --force');
+      await emit('status_unknown', { error_detail: `snapshot status ${snapshotResult.status || 'unknown'}` });
       process.exit(1);
     }
   }
@@ -256,6 +267,7 @@ async function pushAtris() {
 
   if (filesToPush.length === 0 && deletedPaths.length === 0) {
     console.log('\n  Already up to date.\n');
+    await emit('success', { files_unchanged: filteredLocalCount });
     return;
   }
 
@@ -304,17 +316,21 @@ async function pushAtris() {
             pushed = allowed.length;
           } else {
             console.error(`\n  Push failed: ${retry.errorMessage || retry.error || retry.status}`);
+            await emit('access_denied', { error_detail: `403 retry failed: ${retry.status}` });
             process.exit(1);
           }
         } else {
           console.error('\n  Access denied: you can only push to your team/ folder.');
+          await emit('access_denied');
           process.exit(1);
         }
       } else if (result.status === 409) {
         console.error('\n  Computer is sleeping. Wake it first.');
+        await emit('cold_wake', { error_detail: 'computer sleeping (409)' });
         process.exit(1);
       } else {
         console.error(`\n  Push failed: ${result.errorMessage || result.error || result.status}`);
+        await emit('status_unknown', { error_detail: `sync status ${result.status}` });
         process.exit(1);
       }
     } else {
@@ -333,6 +349,7 @@ async function pushAtris() {
   //   - manifest update only counts confirmed-deleted paths
   const deletedConfirmed = [];
   const deleteFailed = [];
+  let _rateLimitedDeletes = 0;
   for (let i = 0; i < deletedPaths.length; i++) {
     const filePath = deletedPaths[i];
     if (i > 0) {
@@ -345,6 +362,7 @@ async function pushAtris() {
     );
     if (deleteResult.status === 429) {
       // Rate limit — wait 20s, retry once
+      _rateLimitedDeletes++;
       await new Promise((r) => setTimeout(r, 20000));
       deleteResult = await apiRequestJson(
         `/business/${businessId}/workspaces/${workspaceId}/file?path=${encodeURIComponent(filePath)}`,
@@ -406,6 +424,32 @@ async function pushAtris() {
     delete updatedFiles[filePath];
   }
   saveManifest(resolvedSlug || slug, buildManifest(updatedFiles, null));
+
+  // Telemetry — outcome reflects actual run quality, not just exit-code-zero.
+  // Partial delete failures or rate-limit retries mean the run was NOT a clean win;
+  // labeling them success would poison the RL signal.
+  const bytesChanged = filesToPush.reduce((acc, f) => acc + (f.content ? Buffer.byteLength(f.content, 'utf8') : 0), 0);
+  let finalOutcome;
+  let finalDetail;
+  if (deleteFailed.length > 0) {
+    finalOutcome = 'status_unknown';
+    finalDetail = `${deleteFailed.length} delete(s) failed (statuses: ${[...new Set(deleteFailed.map(f => f.status))].join(',')})`;
+  } else if (_rateLimitedDeletes > 0) {
+    finalOutcome = 'rate_limited';
+    finalDetail = `${_rateLimitedDeletes} delete(s) hit 429 (recovered)`;
+  } else if (_coldWake) {
+    finalOutcome = 'cold_wake';
+  } else {
+    finalOutcome = 'success';
+  }
+  await emit(finalOutcome, {
+    files_pushed: pushed,
+    files_deleted: deleted,
+    files_unchanged: unchangedCount,
+    bytes_changed: bytesChanged,
+    bytes_transferred: bytesChanged,
+    error_detail: finalDetail,
+  });
 }
 
 module.exports = { pushAtris };

package/commands/serve.js

@@ -354,6 +354,7 @@ async function serveAtris(options = {}) {
 
 module.exports = {
   serveAtris,
+  streamSession,
   // exported for testing
   safePath,
   applyOp,