@aiwg/cli 2026.7.20 → 2026.7.21

package/dist/src/cli/skill-usage.js

@@ -1,12 +1,16 @@
 import { mkdir, readFile, rename, stat, writeFile, appendFile, readdir } from 'fs/promises';
-import { existsSync } from 'fs';
+import { createReadStream, existsSync } from 'fs';
 import { createHash } from 'crypto';
+import { createInterface } from 'readline';
 import path from 'path';
 import os from 'os';
 import { readAiwgConfig } from '../config/aiwg-config.js';
 import { PROJECT_AIWG_LOCATION_FILE, projectAiwgPath } from '../config/project-artifacts.js';
 const DEFAULT_MAX_BYTES = 1_048_576;
 const DEFAULT_REPORT_LIMIT = 20;
+const MAX_TRANSCRIPT_LINE_BYTES = 1_048_576;
+const MAX_TRANSCRIPT_BYTES = 256 * 1_048_576;
+const MAX_TRANSCRIPT_RECORDS = 1_000_000;
 export async function maybeAppendSkillUsage(input) {
     const env = input.env ?? process.env;
     const resolved = await resolveSkillUsageSettings(input.cwd, env);
@@ -43,15 +47,38 @@ export async function ingestSkillUsageTranscript(options) {
     const contextCwd = options.projectRoot ?? options.cwd;
     const resolved = await resolveSkillUsageSettings(contextCwd, env);
     if (!resolved.enabled || resolved.scopes.length === 0) {
-        return { events: [], appended: 0, skipped: 0, paths: [] };
+        return {
+            events: [], appended: 0, skipped: 0, paths: [],
+            receipt: {
+                source_generation: '', provider: normalizeProvider(options.provider),
+                records_read: 0, events_extracted: 0, events_appended: 0,
+                duplicates_skipped: 0, malformed_skipped: 0,
+            },
+        };
+    }
+    const provider = normalizeProvider(options.provider);
+    if (provider !== 'claude-code') {
+        throw new Error(`unsupported skill-usage transcript provider: ${provider}`);
     }
-    const raw = await readFile(options.transcriptPath, 'utf8');
-    const lines = raw.split('\n').map(line => line.trim()).filter(Boolean);
+    const sourceStat = await stat(options.transcriptPath);
+    const sourceGeneration = digest([
+        provider, String(sourceStat.size), String(sourceStat.mtimeMs),
+    ].join('\0'));
     const version = await readAiwgVersion(options.frameworkRoot);
     const context = await resolvePathContext(contextCwd);
     const extracted = [];
     let skipped = 0;
-    for (const line of lines) {
+    let recordsRead = 0;
+    let bytesRead = 0;
+    for await (const line of streamTranscriptLines(options.transcriptPath)) {
+        recordsRead += 1;
+        bytesRead += Buffer.byteLength(line) + 1;
+        if (recordsRead > MAX_TRANSCRIPT_RECORDS || bytesRead > MAX_TRANSCRIPT_BYTES) {
+            throw new Error('skill-usage transcript exceeds bounded ingestion limits');
+        }
+        if (Buffer.byteLength(line) > MAX_TRANSCRIPT_LINE_BYTES) {
+            throw new Error('skill-usage transcript record exceeds bounded line limit');
+        }
         let parsed;
         try {
             parsed = JSON.parse(line);
@@ -65,22 +92,50 @@ export async function ingestSkillUsageTranscript(options) {
             skipped += 1;
         }
         else {
-            extracted.push(...events);
+            extracted.push(...events.map(event => ({
+                ...event,
+                occurredAt: sourceOccurrenceTime(parsed),
+                nativeEventId: sourceNativeEventId(parsed),
+                position: recordsRead,
+                contentDigest: digest(line),
+            })));
         }
     }
     const persisted = [];
     const paths = resolved.scopes
         .map(scope => resolveUsagePath(scope, context.projectRoot, env))
         .filter((p) => Boolean(p));
+    const knownEventIdsByPath = new Map();
+    for (const filePath of paths) {
+        const knownEventIds = new Set();
+        for (const event of await readJsonlEvents(filePath)) {
+            if (event.event_id)
+                knownEventIds.add(event.event_id);
+        }
+        knownEventIdsByPath.set(filePath, knownEventIds);
+    }
+    let duplicatesSkipped = 0;
     for (const scope of resolved.scopes) {
         const filePath = resolveUsagePath(scope, context.projectRoot, env);
         if (!filePath)
             continue;
+        const knownEventIds = knownEventIdsByPath.get(filePath) ?? new Set();
         for (const item of extracted) {
+            const eventId = digest([
+                sourceGeneration,
+                item.nativeEventId ?? String(item.position),
+                item.contentDigest,
+                item.artifact.kind,
+                item.artifact.id,
+            ].join('\0'));
+            if (knownEventIds.has(eventId)) {
+                duplicatesSkipped += 1;
+                continue;
+            }
             const event = buildUsageEvent({
                 env,
                 source: 'transcript',
-                provider: normalizeProvider(options.provider),
+                provider,
                 artifact: item.artifact,
                 action: item.action,
                 outcome: 'unknown',
@@ -88,8 +143,13 @@ export async function ingestSkillUsageTranscript(options) {
                 cwd: context.projectRoot ?? contextCwd,
                 context,
                 scope,
+                occurredAt: item.occurredAt,
+                eventId,
+                sourceGeneration,
+                nativeEventId: item.nativeEventId,
             });
             persisted.push(event);
+            knownEventIds.add(eventId);
             if (!options.dryRun) {
                 await appendBoundedJsonl(filePath, event, resolved.maxBytes);
             }
@@ -100,6 +160,15 @@ export async function ingestSkillUsageTranscript(options) {
         appended: options.dryRun ? 0 : persisted.length,
         skipped,
         paths,
+        receipt: {
+            source_generation: sourceGeneration,
+            provider,
+            records_read: recordsRead,
+            events_extracted: extracted.length,
+            events_appended: options.dryRun ? 0 : persisted.length,
+            duplicates_skipped: duplicatesSkipped,
+            malformed_skipped: skipped,
+        },
     };
 }
 export async function readSkillUsageReport(options) {
@@ -131,6 +200,10 @@ export async function readSkillUsageReport(options) {
             limit: 5,
         }),
         paths,
+        window: {
+            retained_segments: paths.reduce((count, filePath) => count + retainedUsagePaths(filePath).filter(existsSync).length, 0),
+            truncated_before: paths.some(filePath => existsSync(`${filePath}.1`)),
+        },
     };
 }
 export async function printSkillUsageReport(options) {
@@ -205,10 +278,17 @@ function classifyCliUsage(command, args) {
     return { kind: 'command', id: command, action: 'invoke' };
 }
 function buildUsageEvent(input) {
+    const observedTimestamp = new Date().toISOString();
     const event = {
-        schema_version: 1,
+        schema_version: input.eventId ? 2 : 1,
         event_type: 'aiwg.skill_usage',
-        timestamp: new Date().toISOString(),
+        timestamp: input.occurredAt ?? observedTimestamp,
+        ...(input.eventId ? {
+            observed_timestamp: observedTimestamp,
+            event_id: input.eventId,
+            source_generation: input.sourceGeneration,
+            native_event_id: input.nativeEventId,
+        } : {}),
         invocation_id: input.env.AIWG_INVOCATION_ID,
         source: input.source,
         provider: input.provider,
@@ -294,6 +374,25 @@ function normalizeProvider(value) {
         return 'claude-code';
     return normalized || 'unknown';
 }
+function sourceOccurrenceTime(value) {
+    if (!isRecord(value))
+        return undefined;
+    for (const key of ['timestamp', 'created_at', 'createdAt', 'time']) {
+        const candidate = value[key];
+        if (typeof candidate === 'string' && !Number.isNaN(Date.parse(candidate))) {
+            return new Date(candidate).toISOString();
+        }
+    }
+    return undefined;
+}
+function sourceNativeEventId(value) {
+    if (!isRecord(value))
+        return undefined;
+    return firstString(value, ['uuid', 'event_id', 'eventId', 'id', 'message_id']);
+}
+function digest(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
 function isArtifactKind(value) {
     return value === 'skill' ||
         value === 'agent' ||
@@ -393,15 +492,20 @@ function resolveUsagePath(scope, projectRoot, env) {
 }
 async function appendBoundedJsonl(filePath, event, maxBytes) {
     await mkdir(path.dirname(filePath), { recursive: true });
-    await rotateIfNeeded(filePath, maxBytes);
-    await appendFile(filePath, JSON.stringify(event) + '\n', 'utf8');
-}
-async function rotateIfNeeded(filePath, maxBytes) {
+    const line = JSON.stringify(event) + '\n';
+    const lineBytes = Buffer.byteLength(line);
+    if (maxBytes > 0 && lineBytes > maxBytes)
+        event.oversized_record = true;
+    const finalLine = JSON.stringify(event) + '\n';
+    await rotateIfNeeded(filePath, maxBytes, Buffer.byteLength(finalLine));
+    await appendFile(filePath, finalLine, 'utf8');
+}
+async function rotateIfNeeded(filePath, maxBytes, appendBytes) {
     if (maxBytes <= 0)
         return;
     try {
         const current = await stat(filePath);
-        if (current.size <= maxBytes)
+        if (current.size === 0 || current.size + appendBytes <= maxBytes)
             return;
         const rotated = `${filePath}.1`;
         if (existsSync(rotated)) {
@@ -415,18 +519,36 @@ async function rotateIfNeeded(filePath, maxBytes) {
     }
 }
 async function readJsonlEvents(filePath) {
+    const events = [];
+    for (const retainedPath of retainedUsagePaths(filePath)) {
+        try {
+            for await (const line of streamTranscriptLines(retainedPath)) {
+                if (line.trim())
+                    events.push(JSON.parse(line));
+            }
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    return events;
+}
+function retainedUsagePaths(filePath) {
+    return [`${filePath}.1`, filePath];
+}
+async function* streamTranscriptLines(filePath) {
+    const input = createReadStream(filePath, { encoding: 'utf8' });
+    const lines = createInterface({ input, crlfDelay: Infinity });
     try {
-        const raw = await readFile(filePath, 'utf8');
-        return raw
-            .split('\n')
-            .map(line => line.trim())
-            .filter(Boolean)
-            .map(line => JSON.parse(line));
+        for await (const line of lines) {
+            if (line.trim())
+                yield line;
+        }
     }
-    catch (error) {
-        if (error.code === 'ENOENT')
-            return [];
-        throw error;
+    finally {
+        lines.close();
+        input.destroy();
     }
 }
 function summarizeEvents(events) {

package/dist/src/extensions/commands/definitions.js

@@ -907,6 +907,34 @@ export const sessionCommand = {
         },
     },
 };
+// Session Catalog Command (#1903)
+export const sessionsCommand = {
+    id: 'sessions',
+    type: 'skill',
+    name: 'Sessions',
+    description: 'Manage the normalized session catalog with versioned JSON, deterministic pagination, previews, and health checks',
+    version: '1.0.0',
+    capabilities: ['cli', 'session-catalog', 'session-import', 'session-lifecycle', 'doctor'],
+    keywords: ['sessions', 'catalog', 'import', 'source', 'tag', 'reindex', 'delete'],
+    category: 'project',
+    platforms: {
+        claude: 'full',
+        generic: 'full',
+    },
+    deployment: {
+        pathTemplate: '.{platform}/commands/{id}.md',
+        core: true,
+    },
+    metadata: {
+        type: 'skill',
+        triggerPhrases: ['list sessions', 'import sessions', 'session catalog', 'sessions doctor'],
+        commandHint: {
+            template: 'utility',
+            argumentHint: '<sources|import|list|show|tag|relocate|reindex|delete|doctor> [--json] [--dry-run]',
+            allowedTools: ['Bash'],
+        },
+    },
+};
 // Sandbox Management Commands (#917)
 export const sandboxCommand = {
     id: 'sandbox',
@@ -3458,6 +3486,7 @@ export const commandDefinitions = [
     feedbackCommand,
     // Session (#884)
     sessionCommand,
+    sessionsCommand,
 ];
 // ============================================
 // Helper Functions

package/dist/src/extensions/manifest.js

@@ -39,6 +39,7 @@ export const ProjectLocalTypeSchema = z.enum([
  * underscore + hyphen, optional trailing slash.
  */
 const safeRelativePath = z.string().regex(/^[a-zA-Z0-9_-]+(?:\/[a-zA-Z0-9_-]+)*\/?$/, 'must be a relative path (alphanumeric + _-, no leading slash, no ..)');
+const safeModuleFile = z.string().regex(/^[a-zA-Z0-9_-]+(?:\/[a-zA-Z0-9_-]+)*\.mjs$/, 'must be a relative .mjs path (alphanumeric + _-, no leading slash, no ..)');
 // Single-char ids are allowed; multi-char ids must end with alphanumeric
 // (no trailing hyphen). This pattern: `[a-z0-9]([a-z0-9-]*[a-z0-9])?`
 const bundleNamePattern = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
@@ -129,6 +130,31 @@ export const ProviderConfigSchema = z.object({
     aliases: z.array(z.string().min(1).max(64)).max(20).optional(),
     capabilities: ProviderCapabilityOverridesSchema.optional(),
 }).strict();
+export const CliCommandsSchema = z.object({
+    namespace: z.string()
+        .min(1)
+        .max(64)
+        .regex(bundleNamePattern, 'kebab-case alphanumeric, no leading/trailing hyphen'),
+    description: z.string().min(1).max(512),
+    entry: safeRelativePath.optional(),
+    subcommands: z.record(z.string()
+        .min(1)
+        .max(64)
+        .regex(bundleNamePattern, 'kebab-case alphanumeric, no leading/trailing hyphen'), z.object({
+        file: safeModuleFile,
+        description: z.string().min(1).max(512),
+        hook_event: z.enum([
+            'Stop',
+            'SessionStart',
+            'SessionEnd',
+            'PreToolUse',
+            'PostToolUse',
+            'FeatureComplete',
+        ]).optional(),
+    }).strict()).refine((commands) => Object.keys(commands).length > 0, {
+        message: 'at least one CLI subcommand is required',
+    }),
+}).strict();
 // ============================================
 // Top-level BundleManifestSchema
 // ============================================
@@ -162,6 +188,9 @@ export const BundleManifestSchema = z.object({
     // Optional patterns shared with existing extension validation
     deprecation: DeprecationSchema.optional(),
     memory: MemoryFootprintSchema.optional(),
+    // Expandable CLI namespace contributed by an addon-shaped bundle.
+    // The same block is accepted by bundled addon manifests.
+    cli_commands: CliCommandsSchema.optional(),
 })
     .strict()
     .refine((m) => {