overlord-cli 0.2608191441.0 → 0.2608191901.0

package/dist/connectors/core/scripts/overlord-mcp.mjs

@@ -80,14 +80,45 @@ function booleanProperty(description) {
   return { type: 'boolean', description };
 }
 
+function compactSearchResponse(response) {
+  const value = response?.structuredContent;
+  if (!value || value.version !== 3 || !Array.isArray(value.results)) return response;
+  const compact = {
+    ...value,
+    results: value.results.map(result => ({
+      ...result,
+      matches: Array.isArray(result.matches)
+        ? result.matches
+            .slice(0, 2)
+            .map(match => {
+              const compactMatch = { ...match };
+              delete compactMatch.snippet;
+              delete compactMatch.matchedTerms;
+              delete compactMatch.createdAt;
+              delete compactMatch.updatedAt;
+              return compactMatch;
+            })
+        : result.matches
+    }))
+  };
+  return {
+    ...response,
+    content: [{ type: 'text', text: JSON.stringify(compact, null, 2) }],
+    structuredContent: compact
+  };
+}
+
 const tools = [
   {
     name: 'overlord_resolve_project',
     title: 'Resolve Overlord project',
     description:
-      'Resolve a project by id, slug, name, or linked repository directory metadata exposed to the MCP client.',
+      "Resolve a project by id, slug, name, or linked repository directory metadata exposed to the MCP client. Names are matched case-insensitively across every workspace the caller can reach; a name matching in more than one returns a 'project_selection_required' result listing the candidates with their workspaces — ask the user, then retry with workspaceId.",
     inputSchema: objectSchema({
       projectId: stringProperty('Explicit Overlord project id, slug, or project name.'),
+      workspaceId: stringProperty(
+        "Optional workspace (id, slug, or name) narrowing an ambiguous projectId. Use this to retry after a 'project_selection_required' result."
+      ),
       directory: stringProperty(
         'Optional repository directory path when the MCP client can expose one with .overlord/project.json.'
       )
@@ -117,7 +148,12 @@ const tools = [
       "Read one project's board columns. Status names and order are defined per project, so two projects in the same workspace can label the same lifecycle differently; each status also carries a stable type (draft, next, execute, review, complete, blocked, cancelled) that does not vary by project.",
     inputSchema: objectSchema(
       {
-        projectId: stringProperty('Overlord project id, slug, or name.')
+        projectId: stringProperty(
+          "Overlord project id, slug, or name. An ambiguous name returns 'project_selection_required'; retry with workspaceId."
+        ),
+        workspaceId: stringProperty(
+          'Optional workspace (id, slug, or name) narrowing an ambiguous projectId.'
+        )
       },
       ['projectId']
     )
@@ -126,24 +162,46 @@ const tools = [
     name: 'overlord_search_missions',
     title: 'Search Overlord missions',
     description:
-      "Search missions across the caller's authorized workspaces in one organization. Returns applied filters and truncation metadata; complete and cancelled missions remain eligible by default.",
+      "Search mission anchors with their matching objectives and deliveries across authorized workspaces. An objective displayId can be passed directly to overlord_load_mission_context; matches are matched-only, not the full objective list. Artifacts are not indexed. Use absolute ISO from/to bounds (no relative dates or implicit window), inspect workspaceCounts, entityCounts, and truncatedCandidates before claiming completeness, and treat appliedFilters.mode 'fallback' as a recency listing. Compact detail is default; request full for child snippets and metadata.",
     inputSchema: objectSchema({
       query: stringProperty('Search query text.'),
       status: stringProperty(
         'Comma-separated status TYPES, such as draft,next,execute,review. Types are workspace-invariant (draft, next, execute, review, complete, blocked, cancelled). Project-defined status names are not accepted here.'
       ),
       projectId: stringProperty(
-        'Optional stable Overlord project UUID. Resolve a human project reference first.'
+        "Optional project reference: a stable UUID, a slug, or the project name as the user said it. Names are matched case-insensitively against the projects the caller can reach. If the name matches in more than one workspace the call returns a 'project_selection_required' result listing the candidates with their workspaces — ask the user which one, then retry with workspaceId set."
+      ),
+      workspaceId: stringProperty(
+        "Optional workspace (id, slug, or name) narrowing an ambiguous projectId. Use this to retry after a 'project_selection_required' result."
       ),
       resourceKey: stringProperty(
         'Optional logical resource key, matched by name within selected projects.'
       ),
-      dateField: stringProperty('Date column for an explicit range: createdAt or updatedAt.'),
+      dateField: stringProperty(
+        'Date column for an explicit range: createdAt, updatedAt, or dueDatetime. Use dueDatetime for questions about what is scheduled or due; missions with no due date are excluded from a dueDatetime range.'
+      ),
       from: stringProperty('Optional inclusive ISO-8601 date/time lower bound.'),
       to: stringProperty('Optional exclusive ISO-8601 date/time upper bound.'),
       limit: {
         type: 'number',
         description: 'Maximum result count. Defaults to 25.'
+      },
+      entityTypes: stringProperty(
+        'Optional comma-separated v3 entity types: mission, objective, delivery.'
+      ),
+      objectiveStates: stringProperty(
+        'Optional comma-separated v3 objective states for matching objectives.'
+      ),
+      matchesPerResult: {
+        type: 'number',
+        description:
+          'Optional v3 child-match cap per mission (default 3, max 10; compact returns at most 2).'
+      },
+      detail: {
+        type: 'string',
+        enum: ['compact', 'full'],
+        description:
+          'Result detail: compact (default) keeps child navigation fields and removes child snippets/metadata; full returns complete v3 child matches.'
       }
     })
   },
@@ -422,17 +480,6 @@ function requiredString(args, name) {
   return value;
 }
 
-function optionalProjectUuid(args) {
-  const projectId = optionalString(args, 'projectId');
-  if (!projectId) return null;
-  if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(projectId)) {
-    throw new Error(
-      'projectId must be a stable Overlord project UUID; resolve human references first'
-    );
-  }
-  return projectId;
-}
-
 /**
  * Forward mission/objective addressing to the CLI. The CLI owns the shared
  * `@overlord/contract` parser and derives a mission from a display id before it
@@ -453,12 +500,15 @@ function missionScopeFlags(args) {
   };
 }
 
-function callOverlordTool(name, args) {
+async function callOverlordTool(name, args) {
   if (name === 'overlord_resolve_project') {
     return runProtocol('discover-project', {
       ...(optionalString(args, 'projectId')
         ? { 'project-id': requiredString(args, 'projectId') }
         : {}),
+      ...(optionalString(args, 'workspaceId')
+        ? { 'workspace-id': requiredString(args, 'workspaceId') }
+        : {}),
       ...(optionalString(args, 'directory') ? { directory: requiredString(args, 'directory') } : {})
     });
   }
@@ -476,15 +526,27 @@ function callOverlordTool(name, args) {
   }
   if (name === 'overlord_list_project_statuses') {
     return runProtocol('statuses', {
-      'project-id': requiredString(args, 'projectId')
+      'project-id': requiredString(args, 'projectId'),
+      ...(optionalString(args, 'workspaceId')
+        ? { 'workspace-id': requiredString(args, 'workspaceId') }
+        : {})
     });
   }
   if (name === 'overlord_search_missions') {
-    return runProtocol('search-missions', {
-      'response-version': '2',
+    const detail = optionalString(args, 'detail') || 'compact';
+    if (detail !== 'compact' && detail !== 'full') {
+      throw new Error("detail must be 'compact' or 'full'");
+    }
+    const response = await runProtocol('search', {
+      'response-version': '3',
       ...(optionalString(args, 'query') ? { query: requiredString(args, 'query') } : {}),
       ...(optionalString(args, 'status') ? { status: requiredString(args, 'status') } : {}),
-      ...(optionalProjectUuid(args) ? { 'project-id': optionalProjectUuid(args) } : {}),
+      ...(optionalString(args, 'projectId')
+        ? { 'project-id': requiredString(args, 'projectId') }
+        : {}),
+      ...(optionalString(args, 'workspaceId')
+        ? { 'workspace-id': requiredString(args, 'workspaceId') }
+        : {}),
       ...(optionalString(args, 'resourceKey')
         ? { 'resource-key': requiredString(args, 'resourceKey') }
         : {}),
@@ -495,8 +557,18 @@ function callOverlordTool(name, args) {
       ...(optionalString(args, 'to') ? { to: requiredString(args, 'to') } : {}),
       ...(typeof args.limit === 'number' && Number.isFinite(args.limit)
         ? { limit: String(Math.trunc(args.limit)) }
+        : {}),
+      ...(optionalString(args, 'entityTypes')
+        ? { 'entity-types': requiredString(args, 'entityTypes') }
+        : {}),
+      ...(optionalString(args, 'objectiveStates')
+        ? { 'objective-states': requiredString(args, 'objectiveStates') }
+        : {}),
+      ...(typeof args.matchesPerResult === 'number' && Number.isFinite(args.matchesPerResult)
+        ? { 'matches-per-result': String(Math.trunc(args.matchesPerResult)) }
         : {})
     });
+    return detail === 'compact' ? compactSearchResponse(response) : response;
   }
   if (name === 'overlord_create_mission') {
     return runProtocol('create', {

package/dist/index.js

@@ -6675,7 +6675,15 @@ var init_resource_paths = __esm({
   }
 });
 
+// ../packages/contract/dist/search.js
+var init_search = __esm({
+  "../packages/contract/dist/search.js"() {
+    "use strict";
+  }
+});
+
 // ../packages/contract/dist/index.js
+var MY_MISSIONS_COLUMNS, MY_MISSIONS_COLUMN_TYPES;
 var init_dist2 = __esm({
   "../packages/contract/dist/index.js"() {
     "use strict";
@@ -6683,6 +6691,14 @@ var init_dist2 = __esm({
     init_launch_variables();
     init_objective_ref();
     init_resource_paths();
+    init_search();
+    MY_MISSIONS_COLUMNS = [
+      { type: "next", label: "Next" },
+      { type: "execute", label: "Executing" },
+      { type: "review", label: "Review" },
+      { type: "complete", label: "Completed" }
+    ];
+    MY_MISSIONS_COLUMN_TYPES = MY_MISSIONS_COLUMNS.map((column) => column.type);
   }
 });
 
@@ -19496,7 +19512,8 @@ function discoverProjectJsonFromFilesystem({
 }
 async function resolveProjectByIdOrName({
   backend,
-  projectRef
+  projectRef,
+  workspaceRef
 }) {
   const trimmed8 = projectRef.trim();
   try {
@@ -19505,11 +19522,45 @@ async function resolveProjectByIdOrName({
     if (!(error instanceof CliError) || !/project not found/i.test(error.message)) throw error;
   }
   const projects = await listAccessibleProjects({ backend });
-  const match = projects.find((project) => project.name === trimmed8) ?? projects.find((project) => project.slug === trimmed8);
-  if (!match) {
+  const needle = trimmed8.toLowerCase();
+  const byName = projects.filter((project) => project.name.toLowerCase() === needle);
+  const matches = byName.length > 0 ? byName : projects.filter((project) => project.slug.toLowerCase() === needle);
+  if (matches.length === 0) {
     throw new CliError({ message: `Project not found: ${trimmed8}` });
   }
-  return match;
+  const narrowed = await narrowByWorkspace({ backend, matches, workspaceRef });
+  if (narrowed.length === 1) return narrowed[0];
+  const workspaces = await workspaceLabels({ backend });
+  const candidates = narrowed.map(
+    (project) => `  ${project.id}  (workspace: ${workspaces.get(project.workspaceId) ?? project.workspaceId})`
+  ).join("\n");
+  throw new CliError({
+    message: `Project reference matches ${narrowed.length} projects: ${trimmed8}
+${candidates}
+Re-run with --workspace-id <id|slug|name>, or pass the project id directly.`
+  });
+}
+async function workspaceLabels({
+  backend
+}) {
+  const workspaces = await backend.get("/api/workspaces");
+  return new Map(workspaces.map((workspace) => [workspace.id, workspace.name]));
+}
+async function narrowByWorkspace({
+  backend,
+  matches,
+  workspaceRef
+}) {
+  const hint = workspaceRef?.trim().toLowerCase();
+  if (!hint || matches.length <= 1) return matches;
+  const workspaces = await backend.get("/api/workspaces");
+  const targets = new Set(
+    workspaces.filter(
+      (workspace) => workspace.id.toLowerCase() === hint || workspace.slug.toLowerCase() === hint || workspace.name.toLowerCase() === hint
+    ).map((workspace) => workspace.id)
+  );
+  const narrowed = matches.filter((project) => targets.has(project.workspaceId));
+  return narrowed.length > 0 ? narrowed : matches;
 }
 async function tryResolveProjectByIdOrName({
   backend,
@@ -20866,7 +20917,8 @@ Subcommands:
   attach                 Start a mission session and return full working context
   connect                Start a lightweight session without full context assembly
   load-context           Read mission context without creating a session
-  search-missions         Find missions by keyword, status, or project
+  search                  Find grouped mission/objective/delivery matches (canonical)
+  search-missions         Compatibility alias for search
   discuss-objective      Mark a draft objective as submitted (does not start execution)
   add-objectives         Append ordered objectives to an existing mission
   update-objective       Set auto-advance and/or instruction text on an objective
@@ -20975,9 +21027,9 @@ load-context:
                                 rediscovering the mission's active objective. Required
                                 on a mission running objectives in parallel.
 
-search-missions:
+search:
   Purpose:
-    Find missions by keyword, status type, or project.
+    Find grouped mission, objective, and delivery matches by keyword, status type, or project.
   Optional:
     --query <text>              Free-text search
     --status <csv>              Comma-separated status TYPES (e.g. execute,review).
@@ -20985,18 +21037,30 @@ search-missions:
                                 complete, blocked, cancelled. Project-defined status
                                 names (board column labels) are not accepted here \u2014
                                 use \`statuses\` to read one project's names.
-    --project-id <id|slug|name> Restrict to one project (CLI resolves human references)
+    --project-id <id|slug|name> Restrict to one project. Names are matched
+                                case-insensitively across the workspaces you can reach;
+                                a name matching in two workspaces returns
+                                project_selection_required listing the candidates.
+    --workspace-id <id|slug|name>
+                                Narrow an ambiguous --project-id
     --resource-key <csv>        Restrict to logical resource key names
-    --date-field <createdAt|updatedAt>
-                                Date column for explicit range filtering
+    --date-field <createdAt|updatedAt|dueDatetime>
+                                Date column for explicit range filtering. Use dueDatetime
+                                for "scheduled"/"due" questions; missions with no due date
+                                are excluded from a dueDatetime range.
     --from <ISO-8601>           Inclusive date/time lower bound
     --to <ISO-8601>             Exclusive date/time upper bound
     --limit <n>                 Max results (default: 25)
-    --response-version <1|2>    1 (default) returns the legacy array; 2 returns
+    --response-version <1|2|3>  1 (default) returns the legacy array; 2 returns
                                 SearchMissionsResponseV2 with snippets, match
-                                evidence, appliedFilters, and truncation counts
+                                evidence, appliedFilters, and truncation counts;
+                                3 returns SearchResponseV3 with grouped objective
+                                and delivery matches
+    --entity-types <csv>        V3 only: mission,objective,delivery (default all)
+    --objective-states <csv>    V3 only: restrict matching objective states
+    --matches-per-result <n>    V3 only: child matches per mission (default 3, max 10)
   Returns:
-    JSON with matching missions (v1) or the versioned search envelope (v2).
+    JSON with matching missions (v1) or the versioned search envelope (v2/v3).
 
 statuses:
   Purpose:
@@ -21352,6 +21416,7 @@ var init_protocol_help = __esm({
       "record-touched",
       "record-work",
       "resume-follow-up",
+      "search",
       "search-missions",
       "update",
       "update-artifact",
@@ -24021,12 +24086,17 @@ async function runManagementCommand({
       const sub = parsed.positional[0];
       if (sub !== "list") {
         throw new CliError({
-          message: "Usage: ovld missions list [--status <csv>] [--project-id <id>] [--json]"
+          message: "Usage: ovld missions list [--status <csv>] [--project-id <id|slug|name>] [--workspace-id <id|slug|name>] [--json]"
         });
       }
       const params = new URLSearchParams();
       const query = flagValue(parsed.flags, "--query");
-      const projectId = flagValue(parsed.flags, "--project-id");
+      const projectRef = flagValue(parsed.flags, "--project-id");
+      const projectId = projectRef ? (await resolveProjectByIdOrName({
+        backend: runtime.backend,
+        projectRef,
+        workspaceRef: flagValue(parsed.flags, "--workspace-id")
+      })).id : void 0;
       const limit = flagValue(parsed.flags, "--limit");
       const statusTypes = (flagValue(parsed.flags, "--status") ?? "").split(",").map((value) => value.trim()).filter((value) => value !== "");
       if (query) params.set("q", query);
@@ -24068,7 +24138,8 @@ async function runManagementCommand({
       }
       const project = await resolveProjectByIdOrName({
         backend: runtime.backend,
-        projectRef
+        projectRef,
+        workspaceRef: flagValue(parsed.flags, "--workspace-id")
       });
       const statuses = await runtime.backend.get(
         `/api/projects/${encodeURIComponent(project.id)}/statuses`
@@ -24975,7 +25046,7 @@ Protocol (JSON output by default):
   ${primaryCommand} protocol heartbeat --mission-id <id> --session-key <key>
   ${primaryCommand} protocol ask --mission-id <id> --session-key <key> --question "..."
   ${primaryCommand} protocol deliver --mission-id <id> --session-key <key> --summary "..."
-  ${primaryCommand} protocol search-missions --query "<text>" --status execute,review
+  ${primaryCommand} protocol search --query "<text>" --status execute,review
   ${primaryCommand} protocol statuses --project-id <id|slug|name>
   ${primaryCommand} protocol load-context --mission-id <id>
   ${primaryCommand} protocol help