overlord-cli 0.2605211850.1 → 0.2605230834.0

package/README.md

@@ -65,6 +65,8 @@ ovld prompt "Draft a fix for the onboarding flow"
 ovld version
 ovld update
 ovld protocol discover-project
+ovld protocol discover-project --project-id <project-id>
+ovld protocol discover-project --working-directory /path/to/repo --device-fingerprint "$OVERLORD_DEVICE_FINGERPRINT"
 ovld protocol attach --ticket-id <ticket_id>
 ovld protocol search-tickets --query "auth refactor" --status next-up,execute
 ovld protocol update --session-key <session-key> --ticket-id <ticket_id> --summary "Working on it" --phase execute

package/bin/_cli/add-cwd.mjs

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+
+// `ovld add-cwd` — interactively add the current working directory as a
+// project resource. Lists the user's projects, prompts for a selection,
+// registers cwd as a primary resource for this device, and writes the
+// project entry into the directory's overlord.json file.
+
+import os from 'node:os';
+import path from 'node:path';
+import readline from 'node:readline';
+import { stdin as input, stdout as output } from 'node:process';
+
+import { buildAuthHeaders, resolveAuth } from './credentials.mjs';
+import { upsertLocalOverlordConfig } from './local-config.mjs';
+import { parseNumberedSelection, sortProjects } from './new-ticket.mjs';
+import { readOrCreateDeviceFingerprint } from './runner.mjs';
+
+function parseFlags(args) {
+  const flags = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (!arg.startsWith('--')) continue;
+    const eqIdx = arg.indexOf('=');
+    if (eqIdx !== -1) {
+      flags[arg.slice(2, eqIdx)] = arg.slice(eqIdx + 1);
+      continue;
+    }
+    const key = arg.slice(2);
+    if (i + 1 < args.length && !args[i + 1].startsWith('--')) {
+      flags[key] = args[i + 1];
+      i++;
+    } else {
+      flags[key] = true;
+    }
+  }
+  return flags;
+}
+
+function projectLabel(project) {
+  const organizationName = String(project.organizationName ?? '').trim();
+  return organizationName ? `${project.name} — ${organizationName}` : project.name;
+}
+
+async function fetchProjects(platformUrl, bearerToken, localSecret, organizationId) {
+  const res = await fetch(`${platformUrl}/api/protocol/projects`, {
+    headers: buildAuthHeaders(bearerToken, localSecret, organizationId)
+  });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    throw new Error(
+      `Failed to list projects (${res.status}): ${data.error ?? JSON.stringify(data)}`
+    );
+  }
+  return Array.isArray(data.projects) ? sortProjects(data.projects) : [];
+}
+
+async function promptForProject(projects, cwd) {
+  if (!projects.length) {
+    throw new Error('No projects available. Create a project in Overlord first.');
+  }
+
+  const rl = readline.createInterface({ input, output });
+  const ask = q =>
+    new Promise((resolve, reject) => {
+      const onError = error => {
+        rl.off('error', onError);
+        reject(error);
+      };
+      rl.once('error', onError);
+      rl.question(q, answer => {
+        rl.off('error', onError);
+        resolve(answer);
+      });
+    });
+
+  try {
+    while (true) {
+      output.write(`\nCurrent directory:\n  ${cwd}\n\nProjects:\n`);
+      projects.forEach((p, i) => {
+        output.write(`  ${i + 1}. ${projectLabel(p)}\n`);
+      });
+      const answer = await ask(`\nSelect a project to register this directory with (1-${projects.length}, or 'q' to cancel): `);
+      if (answer.trim().toLowerCase() === 'q') {
+        return null;
+      }
+      const idx = parseNumberedSelection(answer, projects.length);
+      if (idx !== null) return projects[idx];
+      output.write(`Enter a number between 1 and ${projects.length}.\n`);
+    }
+  } finally {
+    rl.close();
+  }
+}
+
+export async function runAddCwdCommand(args) {
+  const flags = parseFlags(args);
+
+  if (flags.help === true || flags.h === true) {
+    console.log(`Usage: ovld add-cwd [--directory <path>] [--project-id <id>] [--primary]
+
+Registers a directory (defaulting to the current working directory) as a
+project resource for this device, and writes the project entry into the
+directory's overlord.json file.
+
+When --project-id is omitted, the command lists your projects and prompts
+you to pick one.
+
+By default the registered resource is marked primary for this device. Pass
+--primary=false to skip that behaviour.`);
+    return;
+  }
+
+  const directoryPath = path.resolve(
+    typeof flags.directory === 'string' && flags.directory.trim()
+      ? flags.directory.trim()
+      : process.cwd()
+  );
+
+  const isPrimary = !(flags.primary === 'false' || flags.primary === false);
+
+  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveAuth({});
+
+  const projects = await fetchProjects(platformUrl, bearerToken, localSecret, organizationId);
+  let project = null;
+  if (typeof flags['project-id'] === 'string' && flags['project-id'].trim()) {
+    const wanted = flags['project-id'].trim();
+    project = projects.find(p => p.id === wanted) ?? null;
+    if (!project) {
+      console.error(`Error: project ${wanted} not found among your projects.`);
+      process.exit(1);
+    }
+  } else {
+    project = await promptForProject(projects, directoryPath);
+    if (!project) {
+      output.write('Cancelled. No changes made.\n');
+      return;
+    }
+  }
+
+  const deviceFingerprint = readOrCreateDeviceFingerprint(flags);
+
+  const body = {
+    projectId: project.id,
+    directoryPath,
+    deviceFingerprint,
+    isPrimary,
+    deviceHostname: os.hostname(),
+    devicePlatform: process.platform
+  };
+
+  const res = await fetch(`${platformUrl}/api/protocol/add-project-resource`, {
+    method: 'POST',
+    headers: {
+      ...buildAuthHeaders(bearerToken, localSecret, organizationId),
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify(body)
+  });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    if (res.status === 409) {
+      output.write(
+        `\nDirectory is already registered for "${project.name}" on this device. Updating overlord.json only.\n`
+      );
+    } else {
+      console.error(
+        `Failed to register resource (${res.status}): ${data.error ?? JSON.stringify(data)}`
+      );
+      process.exit(1);
+    }
+  }
+
+  try {
+    const result = await upsertLocalOverlordConfig({
+      directoryPath,
+      project: { id: project.id, name: project.name }
+    });
+    output.write(`\nWrote ${result.filePath} (${result.action}).\n`);
+  } catch (err) {
+    output.write(
+      `\nWarning: could not update overlord.json: ${err instanceof Error ? err.message : err}\n`
+    );
+  }
+
+  if (data.resource?.id) {
+    output.write(`Registered resource ${data.resource.id} (primary=${data.resource.isPrimary}).\n`);
+  } else if (res.ok) {
+    output.write(`Registered ${directoryPath} for project "${project.name}".\n`);
+  }
+}

package/bin/_cli/index.mjs

@@ -32,6 +32,7 @@ Usage:
   ${primaryCommand} attach [ticketId] [agent]  Search tickets and launch an agent (interactive)
   ${primaryCommand} create "<objective>"       Create a ticket with numbered project selection; supports --agent/--model/--delegate
   ${primaryCommand} prompt "<objective>"       Create a ticket, then launch an agent on it
+  ${primaryCommand} add-cwd                   Register the current directory as a project resource (interactive)
   ${primaryCommand} auth <subcommand>          Login, logout, repair, or check auth status
   ${primaryCommand} tickets <subcommand>       Create or list tickets
   ${primaryCommand} ticket <subcommand>        Work with a single ticket
@@ -105,6 +106,12 @@ export async function runCli({ primaryCommand }) {
     return;
   }
 
+  if (command === 'add-cwd') {
+    const { runAddCwdCommand } = await import('./add-cwd.mjs');
+    await runAddCwdCommand(rest);
+    return;
+  }
+
   // Auth group
   if (command === 'auth') {
     await runAuthCommand(rest[0], rest.slice(1));

package/bin/_cli/protocol.mjs

@@ -212,12 +212,49 @@ async function uploadToSignedUrl(uploadUrl, bytes, contentType, timeoutMs = DEFA
   }
 }
 
+// ---------------------------------------------------------------------------
+// Session file persistence — auto-resolve session key between CLI calls
+// ---------------------------------------------------------------------------
+
+function getSessionFilePath() {
+  return path.join(os.tmpdir(), `.overlord-session-${Buffer.from(process.cwd()).toString('base64url')}`);
+}
+
+function persistSession(sessionKey, ticketId) {
+  try {
+    fs.writeFileSync(
+      getSessionFilePath(),
+      JSON.stringify({ sessionKey, ticketId, ts: Date.now() }),
+      'utf8'
+    );
+  } catch { /* best-effort */ }
+}
+
+function readPersistedSession() {
+  try {
+    const raw = fs.readFileSync(getSessionFilePath(), 'utf8');
+    const data = JSON.parse(raw);
+    if (data.sessionKey && data.ticketId) return data;
+  } catch { /* missing or corrupt — ignore */ }
+  return null;
+}
+
 /** Read SESSION_KEY and TICKET_ID from env if flags not provided */
 function resolveSessionFlags(flags) {
-  return {
-    sessionKey: String(flags['session-key'] ?? process.env.SESSION_KEY ?? ''),
-    ticketId: String(flags['ticket-id'] ?? process.env.TICKET_ID ?? '')
-  };
+  const sessionKey = String(flags['session-key'] ?? process.env.SESSION_KEY ?? '');
+  const ticketId = String(flags['ticket-id'] ?? process.env.TICKET_ID ?? '');
+
+  if (sessionKey && ticketId) return { sessionKey, ticketId };
+
+  const persisted = readPersistedSession();
+  if (persisted) {
+    return {
+      sessionKey: sessionKey || persisted.sessionKey,
+      ticketId: ticketId || persisted.ticketId
+    };
+  }
+
+  return { sessionKey, ticketId };
 }
 
 /** Resolve request timeout from --timeout flag or OVERLORD_TIMEOUT env var. */
@@ -944,6 +981,7 @@ async function protocolAttach(args) {
   console.log(JSON.stringify(data, null, 2));
 
   if (sessionKey) {
+    persistSession(sessionKey, ticketId);
     // Emit a machine-readable line for easy shell capture:
     // SESSION_KEY=$(ovld protocol attach --ticket-id ... | grep ^SESSION_KEY= | cut -d= -f2)
     process.stderr.write(`\nSESSION_KEY=${sessionKey}\n`);
@@ -1367,8 +1405,11 @@ async function protocolDeliver(args) {
 async function protocolAttachmentList(args) {
   const flags = parseFlags(args);
   const { sessionKey, ticketId } = resolveSessionFlags(flags);
+  const objectiveId = flags['objective-id'] ? String(flags['objective-id']) : '';
   if (!sessionKey) throw new Error('--session-key is required (or set SESSION_KEY)');
-  if (!ticketId) throw new Error('--ticket-id is required (or set TICKET_ID)');
+  if (!ticketId && !objectiveId) {
+    throw new Error('--objective-id or --ticket-id is required');
+  }
 
   const { platformUrl, bearerToken, localSecret, organizationId } =
     await resolveProtocolAuthForFlags(flags, ticketId);
@@ -1376,8 +1417,8 @@ async function protocolAttachmentList(args) {
 
   const body = {
     sessionKey,
-    ticketId,
-    ...(flags['objective-id'] ? { objectiveId: String(flags['objective-id']) } : {})
+    ...(ticketId ? { ticketId } : {}),
+    ...(objectiveId ? { objectiveId } : {})
   };
 
   const data = await apiPost(
@@ -1396,7 +1437,6 @@ async function protocolAttachmentPrepareUpload(args) {
   const flags = parseFlags(args);
   const { sessionKey, ticketId } = resolveSessionFlags(flags);
   if (!sessionKey) throw new Error('--session-key is required (or set SESSION_KEY)');
-  if (!ticketId) throw new Error('--ticket-id is required (or set TICKET_ID)');
   const objectiveId = requireFlag(flags, 'objective-id', undefined);
   const fileName = requireFlag(flags, 'file-name', undefined);
 
@@ -1406,7 +1446,7 @@ async function protocolAttachmentPrepareUpload(args) {
 
   const body = {
     sessionKey,
-    ticketId,
+    ...(ticketId ? { ticketId } : {}),
     objectiveId,
     fileName,
     ...(flags.label ? { label: String(flags.label) } : {}),
@@ -1433,7 +1473,6 @@ async function protocolAttachmentFinalizeUpload(args) {
   const flags = parseFlags(args);
   const { sessionKey, ticketId } = resolveSessionFlags(flags);
   if (!sessionKey) throw new Error('--session-key is required (or set SESSION_KEY)');
-  if (!ticketId) throw new Error('--ticket-id is required (or set TICKET_ID)');
   const objectiveId = requireFlag(flags, 'objective-id', undefined);
   const storagePath = requireFlag(flags, 'storage-path', undefined);
   const label = requireFlag(flags, 'label', undefined);
@@ -1444,7 +1483,7 @@ async function protocolAttachmentFinalizeUpload(args) {
 
   const body = {
     sessionKey,
-    ticketId,
+    ...(ticketId ? { ticketId } : {}),
     objectiveId,
     storagePath,
     label,
@@ -1471,7 +1510,6 @@ async function protocolAttachmentGetDownloadUrl(args) {
   const flags = parseFlags(args);
   const { sessionKey, ticketId } = resolveSessionFlags(flags);
   if (!sessionKey) throw new Error('--session-key is required (or set SESSION_KEY)');
-  if (!ticketId) throw new Error('--ticket-id is required (or set TICKET_ID)');
   if (!flags['attachment-id'] && !flags['storage-path']) {
     throw new Error('--attachment-id or --storage-path is required');
   }
@@ -1485,7 +1523,7 @@ async function protocolAttachmentGetDownloadUrl(args) {
 
   const body = {
     sessionKey,
-    ticketId,
+    ...(ticketId ? { ticketId } : {}),
     ...(flags['objective-id'] ? { objectiveId: String(flags['objective-id']) } : {}),
     ...(flags['attachment-id'] ? { attachmentId: String(flags['attachment-id']) } : {}),
     ...(flags['storage-path'] ? { storagePath: String(flags['storage-path']) } : {}),
@@ -1508,7 +1546,6 @@ async function protocolAttachmentUploadFile(args) {
   const flags = parseFlags(args);
   const { sessionKey, ticketId } = resolveSessionFlags(flags);
   if (!sessionKey) throw new Error('--session-key is required (or set SESSION_KEY)');
-  if (!ticketId) throw new Error('--ticket-id is required (or set TICKET_ID)');
   const objectiveId = requireFlag(flags, 'objective-id', undefined);
   const filePath = requireFlag(flags, 'file', undefined);
 
@@ -1537,7 +1574,7 @@ async function protocolAttachmentUploadFile(args) {
     '/api/protocol/attachments/prepare-upload',
     {
       sessionKey,
-      ticketId,
+      ...(ticketId ? { ticketId } : {}),
       objectiveId,
       fileName,
       label,
@@ -1564,7 +1601,7 @@ async function protocolAttachmentUploadFile(args) {
     '/api/protocol/attachments/finalize-upload',
     {
       sessionKey,
-      ticketId,
+      ...(ticketId ? { ticketId } : {}),
       objectiveId,
       storagePath,
       label,
@@ -1588,7 +1625,8 @@ async function protocolDiscoverProject(args) {
     await resolveProtocolAuthForFlags(flags);
   const timeoutMs = resolveTimeout(flags);
 
-  const workingDirectory = String(flags['working-directory'] ?? process.cwd());
+  const workingDirectory =
+    flags['working-directory'] !== undefined ? String(flags['working-directory']) : process.cwd();
 
   const data = await apiPost(
     platformUrl,
@@ -1596,7 +1634,14 @@ async function protocolDiscoverProject(args) {
     localSecret,
     organizationId,
     '/api/protocol/discover-project',
-    { workingDirectory },
+    {
+      ...(flags['project-id'] ? { projectId: String(flags['project-id']) } : { workingDirectory }),
+      ...(flags['device-fingerprint']
+        ? { deviceFingerprint: String(flags['device-fingerprint']) }
+        : {}),
+      ...(flags['device-hostname'] ? { deviceHostname: String(flags['device-hostname']) } : {}),
+      ...(flags['device-platform'] ? { devicePlatform: String(flags['device-platform']) } : {})
+    },
     timeoutMs
   );
   console.log(JSON.stringify(data, null, 2));
@@ -2019,6 +2064,7 @@ async function protocolConnect(args) {
   console.log(JSON.stringify(data, null, 2));
 
   if (sessionKey) {
+    persistSession(sessionKey, ticketId);
     process.stderr.write(`\nSESSION_KEY=${sessionKey}\n`);
   }
 }
@@ -2145,6 +2191,7 @@ async function protocolPrompt(args) {
   console.log(JSON.stringify(data, null, 2));
 
   if (sessionKey) {
+    if (ticketId) persistSession(sessionKey, ticketId);
     process.stderr.write(`\nSESSION_KEY=${sessionKey}\n`);
   }
   if (ticketId) {
@@ -2493,9 +2540,10 @@ Project discovery:
   You can also discover the project explicitly:
 
     ovld protocol discover-project
+    ovld protocol discover-project --project-id <project-uuid>
     ovld protocol discover-project --working-directory /path/to/repo
 
-  Use --project-id to override automatic resolution on prompt or ticket creation.
+  Use --project-id to override automatic resolution on discover, prompt, or ticket creation.
   Use --personal to create a private ticket without assigning any project.
 
 Subcommands:
@@ -2536,8 +2584,8 @@ Subcommands:
   update-project-resource     Update a resource directory's path, label, or primary status
 
 Environment fallback:
-  --session-key  <- SESSION_KEY
-  --ticket-id    <- TICKET_ID  (human-readable ticket_id, e.g. 1:899)
+  --session-key  <- SESSION_KEY or auto-persisted session from last attach/connect/prompt in this working directory
+  --ticket-id    <- TICKET_ID  or auto-persisted session (human-readable ticket_id, e.g. 1:899)
   auth/host     <- OVERLORD_URL, optional OVERLORD_ACCESS_TOKEN + OVERLORD_ORGANIZATION_ID, or shared OAuth credentials from ovld auth/Desktop login
   --timeout     <- OVERLORD_TIMEOUT
 
@@ -2563,7 +2611,11 @@ discover-project:
     Resolve the Overlord project that corresponds to the current (or given) working directory.
     Uses the caller's configured "Local working directory" for matching.
   Optional:
+    --project-id <uuid>       Resolve this project directly; skips working-directory matching
     --working-directory <path>  Directory to match (default: current working directory)
+    --device-fingerprint <fp>   Prefer resource directories for this registered device
+    --device-hostname <name>    Register/update device metadata when fingerprint is provided
+    --device-platform <platform>
   Returns:
     Project JSON with id, name, organizationId. Prints PROJECT_ID=<id> on stderr.
   Notes:
@@ -2860,19 +2912,20 @@ record-work:
 attachment-list:
   Required:
     --session-key <key>
-    --ticket-id <ticket_id>
+    one of: --objective-id <id> | --ticket-id <ticket_id>
   Optional:
-    --objective-id <id>       Filter to a single objective
+    --objective-id <id>       Filter to a single objective (also acts as ticket scope)
+    --ticket-id <ticket_id>   List every attachment for a ticket
   Returns:
     JSON array of { id, label, content_type, file_size, objective_id, storage_path, created_at }
 
 attachment-prepare-upload:
   Required:
     --session-key <key>
-    --ticket-id <ticket_id>
     --objective-id <id>
     --file-name <name>
   Optional:
+    --ticket-id <ticket_id>   Derived from --objective-id when omitted
     --label <text>
     --content-type <mime>
     --file-size <bytes>
@@ -2881,11 +2934,11 @@ attachment-prepare-upload:
 attachment-finalize-upload:
   Required:
     --session-key <key>
-    --ticket-id <ticket_id>
     --objective-id <id>
     --storage-path <path>
     --label <text>
   Optional:
+    --ticket-id <ticket_id>   Derived from --objective-id when omitted
     --content-type <mime>
     --file-size <bytes>
     --metadata-json <json>
@@ -2893,19 +2946,19 @@ attachment-finalize-upload:
 attachment-download-url:
   Required:
     --session-key <key>
-    --ticket-id <ticket_id>
     one of: --attachment-id <id> | --storage-path <path>
   Optional:
+    --ticket-id <ticket_id>   Derived from --attachment-id / --objective-id when omitted
     --objective-id <id>       Required when using --storage-path
     --expires-in <seconds>
 
 attachment-upload-file:
   Required:
     --session-key <key>
-    --ticket-id <ticket_id>
     --objective-id <id>
     --file <path>
   Optional:
+    --ticket-id <ticket_id>   Derived from --objective-id when omitted
     --file-name <name>        Defaults to basename of --file
     --label <text>            Defaults to file name
     --content-type <mime>     Defaults to application/octet-stream
@@ -2993,6 +3046,7 @@ fail-execution-launch:
 Examples:
   ovld protocol auth-status
   ovld protocol discover-project
+  ovld protocol discover-project --project-id <project-uuid>
   ovld protocol discover-project --working-directory /path/to/repo
   ovld protocol prompt --agent codex --objective "Implement feature X"   # auto-resolves project from cwd
   ovld protocol attach --ticket-id 1:899
@@ -3015,10 +3069,10 @@ Examples:
   ovld protocol hook-event --hook-type UserPromptSubmit --ticket-id <ticket_id> --prompt "User follow-up" --turn-index 1
   ovld protocol read-context --session-key <key> --ticket-id <ticket_id> --query arch --limit 5
   ovld protocol write-context --session-key <key> --ticket-id <ticket_id> --key "arch" --value '"monorepo"' --tags repo,agent
-  ovld protocol attachment-list --session-key <key> --ticket-id <ticket_id>
-  ovld protocol attachment-prepare-upload --session-key <key> --ticket-id <ticket_id> --objective-id <objective-id> --file-name spec.pdf --content-type application/pdf
-  ovld protocol attachment-upload-file --session-key <key> --ticket-id <ticket_id> --objective-id <objective-id> --file ./spec.pdf
-  ovld protocol attachment-download-url --session-key <key> --ticket-id <ticket_id> --attachment-id <attachment-id>
+  ovld protocol attachment-list --session-key <key> --objective-id <objective-id>
+  ovld protocol attachment-prepare-upload --session-key <key> --objective-id <objective-id> --file-name spec.pdf --content-type application/pdf
+  ovld protocol attachment-upload-file --session-key <key> --objective-id <objective-id> --file ./spec.pdf
+  ovld protocol attachment-download-url --session-key <key> --attachment-id <attachment-id>
   ovld protocol request-execution --ticket-id 1:899 --agent codex --requested-from manual_run
   ovld protocol claim-execution --device-fingerprint $OVERLORD_DEVICE_FINGERPRINT
   ovld protocol deliver --session-key <key> --ticket-id <ticket_id> --summary "Done"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "overlord-cli",
-  "version": "0.2605211850.1",
+  "version": "0.2605230834.0",
   "description": "Overlord CLI — launch AI agents on tickets from anywhere",
   "homepage": "https://www.ovld.ai/docs/",
   "type": "module",