@openscout/protocol 0.2.29 → 0.2.31

package/dist/agent-identity.d.ts

@@ -39,6 +39,10 @@ export declare function constructAgentIdentity(input: AgentIdentityInput, option
     raw?: string;
 }): AgentIdentity | null;
 export declare function extractAgentIdentities(text: string): AgentIdentity[];
+export declare function extractAgentMentions(text: string): {
+    parsed: AgentIdentity[];
+    unparsed: string[];
+};
 export declare function agentIdentityMatches(identity: AgentIdentity, candidate: AgentIdentityCandidate): boolean;
 export declare function resolveAgentIdentity<T extends AgentIdentityCandidate>(identity: AgentIdentity, candidates: T[]): T | null;
 export declare function constructAgentAlias(input: {

package/dist/agent-identity.js

@@ -57,7 +57,8 @@ function parseSegmentedIdentity(raw) {
     const next = {
         definitionId: definitionPart,
     };
-    let sawPositionalWorkspace = false;
+    // Collect positional (non-keyed) segments
+    const positional = [];
     for (const part of parts) {
         if (part.includes(":")) {
             const [rawKey, rawValue = ""] = part.split(":", 2);
@@ -80,15 +81,29 @@ function parseSegmentedIdentity(raw) {
             }
             continue;
         }
-        if (sawPositionalWorkspace) {
+        positional.push(part);
+    }
+    // 1 positional → workspaceQualifier  (@agent.branch)
+    // 2 positionals → nodeQualifier.workspaceQualifier  (@agent.node.branch — matches instance ID format)
+    // 3+ positionals → invalid
+    if (positional.length === 1) {
+        const value = normalizeAgentIdentitySegment(positional[0]);
+        if (!value)
             return null;
-        }
-        const value = normalizeAgentIdentitySegment(part);
-        if (!value) {
-            return null;
-        }
         next.workspaceQualifier = value;
-        sawPositionalWorkspace = true;
+    }
+    else if (positional.length === 2) {
+        const nodeValue = normalizeAgentIdentitySegment(positional[0]);
+        const workspaceValue = normalizeAgentIdentitySegment(positional[1]);
+        if (!nodeValue || !workspaceValue)
+            return null;
+        if (!next.nodeQualifier)
+            next.nodeQualifier = nodeValue;
+        if (!next.workspaceQualifier)
+            next.workspaceQualifier = workspaceValue;
+    }
+    else if (positional.length > 2) {
+        return null;
     }
     return constructAgentIdentity(next, { raw });
 }
@@ -139,16 +154,26 @@ export function constructAgentIdentity(input, options = {}) {
     };
 }
 export function extractAgentIdentities(text) {
+    return extractAgentMentions(text).parsed;
+}
+export function extractAgentMentions(text) {
     const matches = Array.from(text.matchAll(/(^|\s)@([a-z0-9][a-z0-9._/:-]*)/gi));
     const identities = new Map();
+    const unparsed = [];
     for (const match of matches) {
-        const candidate = parseAgentIdentity(match[2] ?? "");
+        const raw = match[2] ?? "";
+        const candidate = parseAgentIdentity(raw);
         if (!candidate) {
+            if (raw)
+                unparsed.push(`@${raw}`);
             continue;
         }
         identities.set(candidate.label, candidate);
     }
-    return Array.from(identities.values());
+    return {
+        parsed: Array.from(identities.values()),
+        unparsed: Array.from(new Set(unparsed)),
+    };
 }
 function candidateAliases(candidate) {
     const canonical = canonicalizeIdentity({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openscout/protocol",
-  "version": "0.2.29",
+  "version": "0.2.31",
   "description": "Typed protocol for the OpenScout local control plane",
   "type": "module",
   "exports": {

package/src/agent-identity.test.ts

@@ -57,11 +57,19 @@ describe("agent identity grammar", () => {
     });
   });
 
+  test("parses 3-segment positional as definitionId.nodeQualifier.workspaceQualifier", () => {
+    const result = parseAgentIdentity("@arc.main.dev");
+    expect(result).not.toBeNull();
+    expect(result!.definitionId).toBe("arc");
+    expect(result!.nodeQualifier).toBe("main");
+    expect(result!.workspaceQualifier).toBe("dev");
+  });
+
   test("rejects invalid and legacy-shaped identities", () => {
     expect(parseAgentIdentity("")).toBeNull();
-    expect(parseAgentIdentity("@arc.main.dev")).toBeNull();
     expect(parseAgentIdentity("@arc.profile:")).toBeNull();
     expect(parseAgentIdentity("@arc@mini#main")).toBeNull();
+    expect(parseAgentIdentity("@arc.a.b.c")).toBeNull(); // 3+ positionals rejected
   });
 
   test("constructs canonical agent identities", () => {

package/src/agent-identity.ts

@@ -104,7 +104,8 @@ function parseSegmentedIdentity(raw: string): AgentIdentity | null {
     definitionId: definitionPart,
   };
 
-  let sawPositionalWorkspace = false;
+  // Collect positional (non-keyed) segments
+  const positional: string[] = [];
   for (const part of parts) {
     if (part.includes(":")) {
       const [rawKey, rawValue = ""] = part.split(":", 2);
@@ -126,17 +127,24 @@ function parseSegmentedIdentity(raw: string): AgentIdentity | null {
       continue;
     }
 
-    if (sawPositionalWorkspace) {
-      return null;
-    }
-
-    const value = normalizeAgentIdentitySegment(part);
-    if (!value) {
-      return null;
-    }
+    positional.push(part);
+  }
 
+  // 1 positional → workspaceQualifier  (@agent.branch)
+  // 2 positionals → nodeQualifier.workspaceQualifier  (@agent.node.branch — matches instance ID format)
+  // 3+ positionals → invalid
+  if (positional.length === 1) {
+    const value = normalizeAgentIdentitySegment(positional[0]);
+    if (!value) return null;
     next.workspaceQualifier = value;
-    sawPositionalWorkspace = true;
+  } else if (positional.length === 2) {
+    const nodeValue = normalizeAgentIdentitySegment(positional[0]);
+    const workspaceValue = normalizeAgentIdentitySegment(positional[1]);
+    if (!nodeValue || !workspaceValue) return null;
+    if (!next.nodeQualifier) next.nodeQualifier = nodeValue;
+    if (!next.workspaceQualifier) next.workspaceQualifier = workspaceValue;
+  } else if (positional.length > 2) {
+    return null;
   }
 
   return constructAgentIdentity(next, { raw });
@@ -204,21 +212,31 @@ export function constructAgentIdentity(
 }
 
 export function extractAgentIdentities(text: string): AgentIdentity[] {
+  return extractAgentMentions(text).parsed;
+}
+
+export function extractAgentMentions(text: string): { parsed: AgentIdentity[]; unparsed: string[] } {
   const matches = Array.from(
     text.matchAll(/(^|\s)@([a-z0-9][a-z0-9._/:-]*)/gi),
   );
   const identities = new Map<string, AgentIdentity>();
+  const unparsed: string[] = [];
 
   for (const match of matches) {
-    const candidate = parseAgentIdentity(match[2] ?? "");
+    const raw = match[2] ?? "";
+    const candidate = parseAgentIdentity(raw);
     if (!candidate) {
+      if (raw) unparsed.push(`@${raw}`);
       continue;
     }
 
     identities.set(candidate.label, candidate);
   }
 
-  return Array.from(identities.values());
+  return {
+    parsed: Array.from(identities.values()),
+    unparsed: Array.from(new Set(unparsed)),
+  };
 }
 
 function candidateAliases(candidate: AgentIdentityCandidate): string[] {