@unpolarize/code-sessions 0.1.0 → 0.2.0

package/src/insights/heuristics.ts

@@ -1,4 +1,4 @@
-import type { Signal, Turn } from '@unpolarize/code-sessions-schema';
+import type { Intent, Signal, Turn } from '@unpolarize/code-sessions-schema';
 
 /**
  * Deterministic, LLM-free signal derivation. Runs regardless of provider so the
@@ -104,3 +104,50 @@ export function deriveTags(turns: Turn[]): string[] {
   for (const t of turns) for (const c of t.tool_calls) tags.add(c.name);
   return [...tags].slice(0, 12);
 }
+
+/** Map an edited file path to a coarse project id (…/projects/<id>, …/docs → docs). */
+export function projectIdFromPath(p: string): string | null {
+  const segs = p.split('/').filter(Boolean);
+  const i = segs.indexOf('projects');
+  if (i >= 0 && segs[i + 1] === 'ai' && segs[i + 2]) return `ai/${segs[i + 2]}`;
+  if (i >= 0 && segs[i + 1]) return segs[i + 1]!;
+  if (segs.includes('docs')) return 'docs';
+  return null;
+}
+
+/** Projects the session touched, from Edit/Write/Read tool file paths. */
+export function deriveProjects(turns: Turn[]): string[] {
+  const set = new Set<string>();
+  for (const t of turns) {
+    for (const c of t.tool_calls) {
+      const fp = (c.input as { file_path?: string; path?: string } | undefined)?.file_path
+        ?? (c.input as { path?: string } | undefined)?.path;
+      if (typeof fp === 'string') {
+        const id = projectIdFromPath(fp);
+        if (id) set.add(id);
+      }
+    }
+  }
+  return [...set].sort().slice(0, 12);
+}
+
+const INTENT_PATTERNS: [Intent, RegExp][] = [
+  ['bugfix', /\b(fix|bug|broken|error|crash|regression|failing|stack ?trace)\b/i],
+  ['feature', /\b(add|implement|build|create|feature|support|introduce|new )\b/i],
+  ['refactor', /\b(refactor|clean ?up|simplify|rename|restructure|extract|dedupe)\b/i],
+  ['research', /\b(research|investigate|explore|compare|evaluate|find out|how (do|does|to)|why)\b/i],
+  ['docs', /\b(document|docs|readme|write[ -]?up|notes|comment)\b/i],
+  ['review', /\b(review|audit|critique|check|inspect)\b/i],
+  ['ops', /\b(deploy|release|publish|install|configure|ci\/?cd|pipeline|infra)\b/i],
+];
+
+/** Classify the session's intent from the first substantive user prompt. */
+export function deriveIntent(turns: Turn[]): Intent | undefined {
+  const firstUser = turns.find((t) => t.role === 'user' && t.text.trim().length > 0);
+  if (!firstUser) return undefined;
+  const text = firstUser.text;
+  for (const [intent, re] of INTENT_PATTERNS) {
+    if (re.test(text)) return intent;
+  }
+  return 'other';
+}

package/src/insights/labeler.test.ts

@@ -52,8 +52,11 @@ describe('labelSession', () => {
       expect(ins!.generated_at).toBe('2026-06-20T09:00:00Z');
       expect(existsSync(insightsFile(dir))).toBe(true);
 
+      expect(ins!.intent).toBe('bugfix');
+      expect(ins!.tags).toContain('Edit'); // tags live on the insights record
       const env = JSON.parse(readFileSync(envelopeFile(dir), 'utf8'));
-      expect(env.labels).toContain('Edit');
+      expect(env.labels).toContain('intent:bugfix'); // envelope labels = intent/topic/projects
+      expect(env.labels.some((l: string) => l.startsWith('intent:'))).toBe(true);
     });
   });
 

package/src/insights/labeler.ts

@@ -11,7 +11,7 @@ import type { CodeSessionsConfig } from '../config';
 import { envelopeFile, insightsFile } from '../store/paths';
 import { listSessionDirs } from '../store/scan';
 import { readTurns } from '../store/writer';
-import { deriveSignals, deriveTags, guessTopic } from './heuristics';
+import { deriveIntent, deriveProjects, deriveSignals, deriveTags, guessTopic } from './heuristics';
 import { FakeProvider, type LabelResult, type Provider } from './provider';
 import { LlmProvider, claudeRunner, grokRunner, ollamaRunner } from './llm';
 
@@ -73,7 +73,7 @@ export async function labelSession(
   if (turns.length === 0) return undefined;
 
   const heuristicSignals = deriveSignals(turns);
-  let provided: LabelResult = { tags: [], signals: [] };
+  let provided: LabelResult = { tags: [], projects: [], signals: [] };
   try {
     provided = await provider.label({ sessionId: identity.sessionId, host: identity.host, turns });
   } catch {
@@ -81,7 +81,9 @@ export async function labelSession(
   }
 
   const topic = provided.topic ?? guessTopic(turns);
+  const intent = provided.intent ?? deriveIntent(turns);
   const tags = [...new Set([...provided.tags, ...deriveTags(turns)])].slice(0, 16);
+  const projects = [...new Set([...provided.projects, ...deriveProjects(turns)])].slice(0, 16);
   const signals = dedupeSignals([...heuristicSignals, ...provided.signals]);
 
   const insights: Insights = {
@@ -91,17 +93,22 @@ export async function labelSession(
     generated_at: opts.now ?? new Date().toISOString(),
     provider: provider.name,
     tags,
+    projects,
     signals,
   };
   if (topic) insights.topic = topic;
+  if (intent) insights.intent = intent;
   if (provided.summary) insights.summary = provided.summary;
 
   writeJsonAtomic(insightsFile(sessionDir), insights);
-  updateEnvelopeLabels(sessionDir, topic, tags);
+  updateEnvelopeLabels(sessionDir, { topic, intent, projects });
   return insights;
 }
 
-function updateEnvelopeLabels(sessionDir: string, topic: string | undefined, tags: string[]): void {
+function updateEnvelopeLabels(
+  sessionDir: string,
+  l: { topic?: string; intent?: string; projects: string[] },
+): void {
   const path = envelopeFile(sessionDir);
   if (!existsSync(path)) return;
   let env: SessionEnvelope;
@@ -110,7 +117,13 @@ function updateEnvelopeLabels(sessionDir: string, topic: string | undefined, tag
   } catch {
     return;
   }
-  env.labels = [...new Set([...(topic ? [topic] : []), ...tags])].slice(0, 16);
+  env.labels = [
+    ...new Set([
+      ...(l.intent ? [`intent:${l.intent}`] : []),
+      ...(l.topic ? [l.topic] : []),
+      ...l.projects.map((p) => `project:${p}`),
+    ]),
+  ].slice(0, 16);
   writeJsonAtomic(path, env);
 }
 

package/src/insights/llm.test.ts

@@ -54,7 +54,7 @@ describe('parseLabelJson', () => {
   });
 
   it('returns empty on non-JSON', () => {
-    expect(parseLabelJson('no json here')).toEqual({ tags: [], signals: [] });
+    expect(parseLabelJson('no json here')).toEqual({ tags: [], projects: [], signals: [] });
   });
 });
 

package/src/insights/llm.ts

@@ -1,5 +1,5 @@
 import { spawnSync } from 'node:child_process';
-import { SIGNAL_KINDS, type Signal } from '@unpolarize/code-sessions-schema';
+import { INTENTS, SIGNAL_KINDS, type Signal } from '@unpolarize/code-sessions-schema';
 import type { LabelRequest, LabelResult, Provider } from './provider';
 
 /** Runs a prompt against some agent CLI/API and returns its raw text output. */
@@ -27,10 +27,12 @@ export function buildPrompt(req: LabelRequest): string {
 
   return [
     'You label a coding-agent session. Respond with ONLY a JSON object, no prose:',
-    '{"topic": string, "tags": string[], "summary": string, "signals": [{"kind": one of ' +
+    '{"topic": string, "intent": one of ' +
+      INTENTS.join('|') +
+      ', "tags": string[], "projects": string[], "summary": string, "signals": [{"kind": one of ' +
       SIGNAL_KINDS.join('|') +
       ', "severity": "info"|"warn"|"critical", "note": string}]}',
-    'topic: 3-6 words. tags: tools/themes. summary: <=1 sentence. signals: only notable ones.',
+    'topic: 3-6 words. intent: what the user wanted. tags: tools/themes. projects: repo/dir names touched. summary: <=1 sentence. signals: only notable ones.',
     '',
     'Transcript:',
     transcript,
@@ -42,19 +44,25 @@ const KIND_SET = new Set<string>(SIGNAL_KINDS);
 export function parseLabelJson(out: string): LabelResult {
   const start = out.indexOf('{');
   const end = out.lastIndexOf('}');
-  if (start < 0 || end <= start) return { tags: [], signals: [] };
+  if (start < 0 || end <= start) return { tags: [], projects: [], signals: [] };
   let obj: Record<string, unknown>;
   try {
     obj = JSON.parse(out.slice(start, end + 1)) as Record<string, unknown>;
   } catch {
-    return { tags: [], signals: [] };
+    return { tags: [], projects: [], signals: [] };
   }
   const result: LabelResult = {
     tags: Array.isArray(obj.tags) ? obj.tags.filter((t): t is string => typeof t === 'string') : [],
+    projects: Array.isArray(obj.projects)
+      ? obj.projects.filter((t): t is string => typeof t === 'string')
+      : [],
     signals: coerceSignals(obj.signals),
   };
   if (typeof obj.topic === 'string') result.topic = obj.topic;
   if (typeof obj.summary === 'string') result.summary = obj.summary;
+  if (typeof obj.intent === 'string' && (INTENTS as readonly string[]).includes(obj.intent)) {
+    result.intent = obj.intent as LabelResult['intent'];
+  }
   return result;
 }
 

package/src/insights/provider.ts

@@ -1,5 +1,5 @@
-import type { Signal, Turn } from '@unpolarize/code-sessions-schema';
-import { deriveTags, guessTopic } from './heuristics';
+import type { Intent, Signal, Turn } from '@unpolarize/code-sessions-schema';
+import { deriveIntent, deriveProjects, deriveTags, guessTopic } from './heuristics';
 
 export interface LabelRequest {
   sessionId: string;
@@ -9,7 +9,9 @@ export interface LabelRequest {
 
 export interface LabelResult {
   topic?: string;
+  intent?: Intent;
   tags: string[];
+  projects: string[];
   signals: Signal[];
   summary?: string;
 }
@@ -26,10 +28,13 @@ export class FakeProvider implements Provider {
   async label(req: LabelRequest): Promise<LabelResult> {
     const result: LabelResult = {
       tags: deriveTags(req.turns),
+      projects: deriveProjects(req.turns),
       signals: [],
     };
     const topic = guessTopic(req.turns);
     if (topic) result.topic = topic;
+    const intent = deriveIntent(req.turns);
+    if (intent) result.intent = intent;
     const assistantText = req.turns.find((t) => t.role === 'assistant')?.text;
     if (assistantText) result.summary = assistantText.slice(0, 160);
     return result;

package/src/skills/index.ts

@@ -0,0 +1,2 @@
+export * from './templates';
+export * from './install';

package/src/skills/install.ts

@@ -0,0 +1,52 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { buildClaudeSkill, buildPromptFile } from './templates';
+
+export type SkillAgent = 'claude' | 'codex' | 'grok' | 'all';
+
+export interface SkillInstallResult {
+  installed: string[];
+}
+
+/** Resolve where each agent expects user skills/prompts. */
+function targetsFor(agent: SkillAgent, home: string): { agent: string; path: string; content: string }[] {
+  const out: { agent: string; path: string; content: string }[] = [];
+  const want = (a: string) => agent === 'all' || agent === a;
+  if (want('claude')) {
+    out.push({
+      agent: 'claude',
+      path: join(home, '.claude', 'skills', 'cs-label-session', 'SKILL.md'),
+      content: buildClaudeSkill(),
+    });
+  }
+  if (want('codex')) {
+    out.push({
+      agent: 'codex',
+      path: join(home, '.codex', 'prompts', 'cs-label-session.md'),
+      content: buildPromptFile(),
+    });
+  }
+  if (want('grok')) {
+    out.push({
+      agent: 'grok',
+      path: join(home, '.grok', 'prompts', 'cs-label-session.md'),
+      content: buildPromptFile(),
+    });
+  }
+  return out;
+}
+
+/** Install the CS labeling skill into the requested agents' skill/prompt dirs. */
+export function installSkills(
+  opts: { agent?: SkillAgent; home?: string } = {},
+): SkillInstallResult {
+  const home = opts.home ?? homedir();
+  const installed: string[] = [];
+  for (const t of targetsFor(opts.agent ?? 'all', home)) {
+    mkdirSync(dirname(t.path), { recursive: true });
+    writeFileSync(t.path, t.content);
+    installed.push(t.path);
+  }
+  return { installed };
+}

package/src/skills/skills.test.ts

@@ -0,0 +1,42 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { withTempDir } from '../test/tmp';
+import { buildClaudeSkill, buildLabelSkillBody } from './templates';
+import { installSkills } from './install';
+
+describe('skill templates', () => {
+  it('embeds the intent + signal taxonomy', () => {
+    const body = buildLabelSkillBody();
+    expect(body).toContain('feature | bugfix | refactor');
+    expect(body).toContain('stuck-loop');
+    expect(body).toContain('"projects"');
+  });
+
+  it('claude skill carries frontmatter', () => {
+    const s = buildClaudeSkill();
+    expect(s).toMatch(/^---\nname: cs-label-session/);
+  });
+});
+
+describe('installSkills', () => {
+  it('installs into all agents under the given home', () => {
+    withTempDir((home) => {
+      const res = installSkills({ agent: 'all', home });
+      expect(res.installed).toHaveLength(3);
+      expect(existsSync(join(home, '.claude', 'skills', 'cs-label-session', 'SKILL.md'))).toBe(true);
+      expect(existsSync(join(home, '.codex', 'prompts', 'cs-label-session.md'))).toBe(true);
+      expect(existsSync(join(home, '.grok', 'prompts', 'cs-label-session.md'))).toBe(true);
+      const claude = readFileSync(join(home, '.claude', 'skills', 'cs-label-session', 'SKILL.md'), 'utf8');
+      expect(claude).toContain('intent');
+    });
+  });
+
+  it('can target a single agent', () => {
+    withTempDir((home) => {
+      const res = installSkills({ agent: 'claude', home });
+      expect(res.installed).toHaveLength(1);
+      expect(res.installed[0]).toContain('.claude');
+    });
+  });
+});

package/src/skills/templates.ts

@@ -0,0 +1,48 @@
+import { INTENTS, SIGNAL_KINDS } from '@unpolarize/code-sessions-schema';
+
+/**
+ * The canonical "label a session" skill, generated from the CS labels taxonomy
+ * so it never drifts from the schema. Installed into each agent so it (or the
+ * daemon's configured provider) can label topics, intent, projects-touched, and
+ * signals, emitting the exact JSON the CS insights pipeline ingests.
+ */
+export function buildLabelSkillBody(): string {
+  return `You are labeling a coding-agent session for the code-sessions (CS) store.
+
+Read the provided session transcript and emit ONLY a single JSON object — no prose, no code fence:
+
+\`\`\`json
+{
+  "topic": "3-6 word summary of what the session was about",
+  "intent": "one of: ${INTENTS.join(' | ')}",
+  "tags": ["short", "themes", "or", "tool", "names"],
+  "projects": ["repo-or-dir-names-touched"],
+  "signals": [
+    { "kind": "one of: ${SIGNAL_KINDS.join(' | ')}", "severity": "info|warn|critical", "note": "why" }
+  ],
+  "summary": "one sentence"
+}
+\`\`\`
+
+Guidance:
+- **intent** = what the user wanted (a feature, a bug fixed, a refactor, research, docs, ops, a review, a chore).
+- **projects** = the projects/repos the session actually edited (from file paths it wrote to), not everything mentioned.
+- **signals** = only notable ones: stuck loops, error-recovery, unusually high cost, very long sessions, tool-heavy stretches, strong negative/positive affect.
+- Keep it terse and machine-parseable. Output the JSON and nothing else.`;
+}
+
+/** Claude SKILL.md with frontmatter. */
+export function buildClaudeSkill(): string {
+  return `---
+name: cs-label-session
+description: Label a coding session (topic, intent, tags, projects touched, signals) as JSON for the code-sessions store. Use when asked to classify or summarize a session.
+---
+
+${buildLabelSkillBody()}
+`;
+}
+
+/** Codex / Grok plain prompt file (no frontmatter). */
+export function buildPromptFile(): string {
+  return `# cs-label-session\n\n${buildLabelSkillBody()}\n`;
+}