send-context 0.1.0 → 0.1.2

package/README.md

@@ -2,18 +2,21 @@
 
 > Relay an AI coding-agent session from one developer to another through an encrypted, ephemeral link.
 
+[![npm version](https://img.shields.io/npm/v/send-context.svg)](https://www.npmjs.com/package/send-context)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
 `send-context` is an agent-agnostic CLI for passing live context between AI coding agents — across machines, across people, across tools. A developer in one timezone exports their session; a teammate in another runs one command to pick up exactly where they left off, with the context injected straight into *their* agent.
 
 The session is distilled into a structured **Context Handoff Skill** document, encrypted on your machine, and stored behind a short-lived link. The transport layer only ever sees ciphertext.
 
 ```
-  pi / Claude Code / OpenCode                          pi / Claude Code / OpenCode
-            │                                                      ▲
-            │ extract + format                       inject prompt │
-            ▼                                                      │
-   ┌─────────────────┐   encrypt    send-context://…    decrypt   ┌─────────────────┐
-   │  send-context export │ ───────────►  edge KV (24h) ────────► │ send-context receive │
-   └─────────────────┘            (ciphertext only)          └─────────────────┘
+   pi · Claude Code · OpenCode                        pi · Claude Code · OpenCode
+              │                                                   ▲
+              │ extract + format                    inject prompt │
+              ▼                                                   │
+   ┌───────────────────────┐  encrypt                  decrypt  ┌────────────────────────┐
+   │  send-context export  │ ────────►  edge KV (24h) ────────► │  send-context receive  │
+   └───────────────────────┘         (ciphertext only)          └────────────────────────┘
 ```
 
 ## Features
@@ -27,7 +30,7 @@ The session is distilled into a structured **Context Handoff Skill** document, e
 
 ## How it works
 
-1. **Export** detects the active agent, extracts its session, and lets you curate what to send. You add a short written brief and pick which raw messages to attach.
+1. **Export** detects the active agent and extracts its session. With a `GEMINI_API_KEY` set, it distills the session into the handoff brief automatically; otherwise it guides you through writing the brief and picking which raw messages to attach.
 2. The brief is rendered into the Context Handoff Skill template, encrypted with a password you choose, and uploaded. You get a `send-context://` link.
 3. **Receive** downloads the blob, decrypts it locally, wraps it in an injection prompt, and spawns the receiving agent with that prompt as its opening message.
 
@@ -40,22 +43,33 @@ The session is distilled into a structured **Context Handoff Skill** document, e
 
 - Node.js 20+
 - One of: `pi`, `claude`, or `opencode` with at least one session in the project directory
+- A Google Gemini API key (optional) — set `GEMINI_API_KEY` to auto-distill sessions instead of writing the brief by hand
 - [Deno](https://deno.com) — only if you want to deploy or run the transport worker yourself
 
 ### Install
 
 ```bash
-npm install
-npm run build      # compiles src/ to dist/
-node dist/index.js --help
+npm install -g send-context
+send-context --help
 ```
 
-To install the `send-context` command globally:
+Or run it without installing:
 
 ```bash
-npm install -g .
+npx send-context --help
 ```
 
+<details>
+<summary>From source</summary>
+
+```bash
+git clone https://github.com/shafiqimtiaz/context-handoff.git
+cd context-handoff
+npm install && npm run build
+node dist/index.js --help
+```
+</details>
+
 ## Deploy the transport
 
 The transport runs on **Deno Deploy + Deno KV** (`worker/main.ts`). It stores only encrypted payloads, each with a native 24-hour TTL.
@@ -82,27 +96,46 @@ deno task deploy     # deploys --prod, prints your *.deno.net host
 ### Send a context handoff
 
 ```bash
-SEND_CONTEXT_WORKER=your-project.deno.net node dist/index.js export
+SEND_CONTEXT_WORKER=your-project.deno.net send-context export
 # or pass the host and agent explicitly:
-node dist/index.js export --worker your-project.deno.net --agent pi
+send-context export --worker your-project.deno.net --agent pi
 ```
 
-You'll be guided through picking the agent, writing the brief, curating the appendix, and setting a password. The command prints a link:
+Without a Gemini key, you'll be guided through picking the agent, writing the brief, curating the appendix, and setting a password — see [Distill with Gemini](#distill-with-gemini-recommended) to automate the brief. The command prints a link:
 
 ```
 send-context://your-project.deno.net/<id>#<password>
 ```
 
+#### Distill with Gemini (recommended)
+
+Raw sessions are noisy. Set `GEMINI_API_KEY` and `export` runs the session through Gemini first, which distills it into the five handoff sections automatically and drops the raw appendix — so the receiver gets a dense brief, not a chat log. The manual section/appendix prompts are skipped.
+
+```bash
+GEMINI_API_KEY=… SEND_CONTEXT_WORKER=your-project.deno.net send-context export
+# optional: override the model (default gemini-2.5-flash)
+GEMINI_MODEL=gemini-2.5-pro GEMINI_API_KEY=… send-context export
+```
+
+If the key is absent or the call fails, `export` falls back to the manual flow — Gemini is an enhancement, not a hard dependency. The key never leaves your machine; only the encrypted, distilled brief is uploaded. It uses Google's OpenAI-compatible endpoint, so no extra SDK is installed.
+
+Set `SEND_CONTEXT_PASSWORD` to skip the password prompt too. With Gemini distillation on and a single detected agent, that makes `export` fully non-interactive — no TTY needed:
+
+```bash
+GEMINI_API_KEY=… SEND_CONTEXT_PASSWORD=… \
+  SEND_CONTEXT_WORKER=your-project.deno.net send-context export --agent pi
+```
+
 ### Receive a context handoff
 
 ```bash
 # Launch an agent with the context injected:
-node dist/index.js receive 'send-context://…/<id>#<password>' -- pi "continue"
-node dist/index.js receive 'send-context://…/<id>#<password>' -- claude "continue"
-node dist/index.js receive 'send-context://…/<id>#<password>' -- opencode run "continue"
+send-context receive 'send-context://…/<id>#<password>' -- pi "continue"
+send-context receive 'send-context://…/<id>#<password>' -- claude "continue"
+send-context receive 'send-context://…/<id>#<password>' -- opencode run "continue"
 
 # Or just print the decrypted context handoff document:
-node dist/index.js receive 'send-context://…/<id>#<password>'
+send-context receive 'send-context://…/<id>#<password>'
 ```
 
 ## Supported agents
@@ -150,4 +183,5 @@ worker/
 
 - **CLI:** TypeScript, [commander](https://github.com/tj/commander.js), [@clack/prompts](https://github.com/bombshell-dev/clack)
 - **Crypto:** Node.js built-in `crypto` (AES-256-GCM, scrypt)
+- **Distillation (optional):** Google Gemini via its OpenAI-compatible Chat Completions endpoint
 - **Transport:** Deno Deploy + Deno KV

package/dist/commands/export.js

@@ -38,6 +38,7 @@ const p = __importStar(require("@clack/prompts"));
 const index_js_1 = require("../adapters/index.js");
 const types_js_1 = require("../adapters/types.js");
 const formatter_js_1 = require("../core/formatter.js");
+const distiller_js_1 = require("../core/distiller.js");
 const crypto_js_1 = require("../core/crypto.js");
 const transport_js_1 = require("../core/transport.js");
 const link_js_1 = require("../core/link.js");
@@ -71,12 +72,30 @@ async function runExport(opts) {
         process.exitCode = 1;
         return;
     }
-    const sections = await promptSections();
-    if (sections === null)
-        return;
-    const appendix = await curateAppendix(messages);
-    if (appendix === null)
-        return;
+    let sections;
+    let appendix;
+    if ((0, distiller_js_1.geminiAvailable)()) {
+        spin.start("Distilling session with Gemini");
+        try {
+            sections = await (0, distiller_js_1.distillSession)(messages);
+            appendix = [];
+            spin.stop("Distilled into a handoff brief.");
+        }
+        catch (err) {
+            spin.stop("Distillation failed — falling back to manual.");
+            p.log.warn(String(err.message));
+            const manual = await runManual(messages);
+            if (manual === null)
+                return;
+            ({ sections, appendix } = manual);
+        }
+    }
+    else {
+        const manual = await runManual(messages);
+        if (manual === null)
+            return;
+        ({ sections, appendix } = manual);
+    }
     const markdown = (0, formatter_js_1.formatToHandoffSkill)({
         sourceAgent: adapter.getName(),
         timestamp: new Date().toISOString(),
@@ -84,14 +103,9 @@ async function runExport(opts) {
         appendix,
         sections,
     });
-    const password = await p.password({
-        message: "Set a password (the receiver needs it to decrypt):",
-        validate: (v) => (v.length < 4 ? "Use at least 4 characters." : undefined),
-    });
-    if (p.isCancel(password)) {
-        cancelled();
+    const password = await resolvePassword();
+    if (password === null)
         return;
-    }
     const payload = (0, crypto_js_1.encrypt)(markdown, password);
     spin.start("Uploading encrypted handoff");
     let id;
@@ -136,6 +150,35 @@ async function resolveAgent(preset) {
     }
     return choice;
 }
+async function resolvePassword() {
+    const fromEnv = process.env.SEND_CONTEXT_PASSWORD;
+    if (fromEnv) {
+        if (fromEnv.length < 4) {
+            p.cancel("SEND_CONTEXT_PASSWORD must be at least 4 characters.");
+            process.exitCode = 1;
+            return null;
+        }
+        return fromEnv;
+    }
+    const password = await p.password({
+        message: "Set a password (the receiver needs it to decrypt):",
+        validate: (v) => (v.length < 4 ? "Use at least 4 characters." : undefined),
+    });
+    if (p.isCancel(password)) {
+        cancelled();
+        return null;
+    }
+    return password;
+}
+async function runManual(messages) {
+    const sections = await promptSections();
+    if (sections === null)
+        return null;
+    const appendix = await curateAppendix(messages);
+    if (appendix === null)
+        return null;
+    return { sections, appendix };
+}
 async function promptSections() {
     const wants = await p.confirm({
         message: "Add a written summary (objective, blockers, next steps)? Recommended.",

package/dist/core/distiller.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.geminiAvailable = geminiAvailable;
+exports.distillSession = distillSession;
+const jsonrepair_1 = require("jsonrepair");
+/**
+ * Optional Gemini pass that distills a raw session into the structured
+ * Context Handoff sections, so the sender ships a dense brief instead of
+ * noisy chat logs. Uses Google's OpenAI-compatible Chat Completions endpoint,
+ * so no SDK is needed — just Node's built-in fetch.
+ */
+const GEMINI_ENDPOINT = "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions";
+const DEFAULT_MODEL = "gemini-2.5-flash";
+const SYSTEM_PROMPT = `You distill an AI coding-agent session into a dense handoff brief for another developer's agent. Strip conversational noise; keep only what the receiving agent needs to continue. Be concrete and terse.
+
+Respond with ONLY a JSON object of this exact shape:
+{
+  "objective": "the primary goal, one or two sentences",
+  "currentState": "where things stand right now and any blockers",
+  "completedSteps": "what is already done — one '-' bullet per line",
+  "failedApproaches": "approaches that were tried and did not work and must not be retried — '-' bullets, or 'None.'",
+  "nextSteps": "the concrete next actions the receiving agent should take — '-' bullets"
+}
+
+Leave a field as an empty string only when the session genuinely lacks that information.`;
+function geminiAvailable() {
+    return Boolean(process.env.GEMINI_API_KEY);
+}
+async function distillSession(messages) {
+    const apiKey = process.env.GEMINI_API_KEY;
+    if (!apiKey)
+        throw new Error("GEMINI_API_KEY is not set.");
+    const model = process.env.GEMINI_MODEL ?? DEFAULT_MODEL;
+    const transcript = messages
+        .map((m) => `### ${m.role.toUpperCase()}\n${m.content.trim()}`)
+        .join("\n\n");
+    const res = await fetch(GEMINI_ENDPOINT, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify({
+            model,
+            messages: [
+                { role: "system", content: SYSTEM_PROMPT },
+                { role: "user", content: `Distill this session:\n\n${transcript}` },
+            ],
+            response_format: { type: "json_object" },
+            temperature: 0.2,
+        }),
+    });
+    if (!res.ok) {
+        throw new Error(`Gemini request failed (${res.status}): ${await res.text()}`);
+    }
+    const data = (await res.json());
+    const content = data.choices?.[0]?.message?.content;
+    if (!content)
+        throw new Error("Gemini returned no content.");
+    return parseSections(content);
+}
+function parseSections(content) {
+    const obj = JSON.parse(extractJson(content));
+    return {
+        objective: str(obj.objective),
+        currentState: str(obj.currentState),
+        completedSteps: str(obj.completedSteps),
+        failedApproaches: str(obj.failedApproaches),
+        nextSteps: str(obj.nextSteps),
+    };
+}
+function extractJson(content) {
+    const fenced = content.match(/```(?:json)?\s*([\s\S]*?)```/);
+    const body = fenced ? fenced[1].trim() : content;
+    // Isolate the JSON from any surrounding prose, then let jsonrepair fix the
+    // common ways models still mangle it: trailing commas, single quotes,
+    // unquoted keys, truncation (missing closing brackets), and so on.
+    const start = body.indexOf("{");
+    const candidate = start === -1 ? body : (firstBalancedObject(body) ?? body.slice(start));
+    return (0, jsonrepair_1.jsonrepair)(candidate);
+}
+// Return the first brace-balanced JSON object, ignoring any prose or extra
+// objects the model appends after it (thinking models often do). Tracks string
+// literals and escapes so braces inside strings don't throw off the depth count.
+function firstBalancedObject(text) {
+    const start = text.indexOf("{");
+    if (start === -1)
+        return null;
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    for (let i = start; i < text.length; i++) {
+        const ch = text[i];
+        if (inString) {
+            if (escaped)
+                escaped = false;
+            else if (ch === "\\")
+                escaped = true;
+            else if (ch === '"')
+                inString = false;
+            continue;
+        }
+        if (ch === '"')
+            inString = true;
+        else if (ch === "{")
+            depth++;
+        else if (ch === "}" && --depth === 0)
+            return text.slice(start, i + 1);
+    }
+    return null;
+}
+function str(v) {
+    return typeof v === "string" ? v.trim() : "";
+}

package/dist/index.js

@@ -5,10 +5,12 @@ const commander_1 = require("commander");
 const export_js_1 = require("./commands/export.js");
 const receive_js_1 = require("./commands/receive.js");
 const program = new commander_1.Command();
+// Single source of truth: read the version release-it bumps in package.json.
+const { version } = require("../package.json");
 program
     .name("send-context")
     .description("Relay AI coding-agent session context between developers via an encrypted, ephemeral link.")
-    .version("0.1.0")
+    .version(version)
     .enablePositionalOptions();
 program
     .command("export")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "send-context",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Agent-agnostic CLI to relay AI coding-agent session context between developers via an encrypted, ephemeral edge link.",
   "license": "MIT",
   "type": "commonjs",
@@ -35,17 +35,20 @@
     "dev": "tsx src/index.ts",
     "start": "node dist/index.js",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "release": "release-it"
   },
   "engines": {
     "node": ">=20"
   },
   "dependencies": {
     "@clack/prompts": "^0.7.0",
-    "commander": "^12.1.0"
+    "commander": "^12.1.0",
+    "jsonrepair": "^3.14.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
+    "release-it": "^20.2.0",
     "tsx": "^4.19.0",
     "typescript": "^5.6.0"
   }