@unpolarize/code-sessions 0.1.0 → 0.3.0

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`;
+}