@remnic/core 9.32.0 → 9.34.0

package/src/extraction.ts

@@ -41,9 +41,9 @@ import { normalizeReasoningTrace } from "./reasoning-trace-types.js";
 import { looksLikeMechanicalTelemetryTranscript } from "./telemetry-transcript.js";
 import {
   attachExtractionProvenance,
-  applyExtractionSourceGrounding,
   type ExtractionGroundingRoleSources,
 } from "./extraction-source-grounding.js";
+import { applyGroundingWithConnector, headerConnector, renderExtractionConversation, resolveSourceConnector, type ExtractionGroundingContext } from "./source-agent-qualifier.js";
 import { isMemoryCategory } from "./write-envelope.js";
 import { classifyExtractionThrownError, classifyFallbackParseFailure } from "./extraction-error-classification.js";
 export { classifyExtractionThrownError, classifyFallbackParseFailure } from "./extraction-error-classification.js";
@@ -666,10 +666,7 @@ export class ExtractionEngine {
   private async applyProactiveQuestionPass(
     conversation: string,
     base: ExtractionResult,
-    groundingSource: string,
-    assertionSource: string,
-    messageTimestamp?: Date,
-    roleAssertionSources?: ExtractionGroundingRoleSources,
+    ctx: ExtractionGroundingContext,
     signal?: AbortSignal,
   ): Promise<ExtractionResult> {
     if (!resolvePipelineProcessingCapabilities(this.config).proactiveExtraction) return base;
@@ -684,16 +681,11 @@ export class ExtractionEngine {
         base,
         proactive,
         maxAdditional,
+        ctx.sourceConnector,
         signal,
       );
-      const sanitizedAdditions = this.sanitizeExtractionResult(proactiveAdditions, messageTimestamp);
-      const groundedAdditions = this.applySourceGrounding(
-        sanitizedAdditions,
-        groundingSource,
-        assertionSource,
-        roleAssertionSources,
-        messageTimestamp,
-      );
+      const sanitizedAdditions = this.sanitizeExtractionResult(proactiveAdditions, ctx.messageTimestamp);
+      const groundedAdditions = applyGroundingWithConnector(this.config, sanitizedAdditions, ctx);
       if (!this.hasExtractionOutputs(groundedAdditions)) return base;
       return this.mergeProactiveExtractionPass(base, groundedAdditions, maxAdditional);
     } catch (err) {
@@ -841,6 +833,7 @@ export class ExtractionEngine {
     base: ExtractionResult,
     proactiveQuestions: ExtractionQuestion[],
     maxAdditional: number,
+    sourceConnector: string | undefined,
     signal?: AbortSignal,
   ): Promise<ExtractionResult> {
     const factsPreview = base.facts
@@ -870,6 +863,9 @@ export class ExtractionEngine {
       // (chatgpt-codex thread on extraction.ts:1607). Returns "" when the
       // bi-temporal gate is off, keeping the prompt unchanged by default.
       this.eventTimePromptInstruction(),
+      headerConnector(sourceConnector) !== undefined && resolveMemoryLifecycleCapabilities(this.config).extractionScopeClassification
+        ? `Tool, command, or CLI-flag instructions tied to the ${sourceConnector} agent are "project" scope; when you recover one, begin the fact with a leading "In ${sourceConnector}, " clause naming that agent (e.g. "In ${sourceConnector}, use the search tool with a repository path.").`
+        : "",
       "",
       "Base extracted facts (do not repeat):",
       factsPreview || "(none)",
@@ -1097,27 +1093,6 @@ export class ExtractionEngine {
     return null;
   }
 
-  private applySourceGrounding(
-    result: ExtractionResult,
-    sourceText: string,
-    assertionSourceText: string = sourceText,
-    roleAssertionSources?: ExtractionGroundingRoleSources,
-    messageTimestamp?: Date,
-  ): ExtractionResult {
-    const capabilities = resolvePipelineProcessingCapabilities(this.config);
-    return applyExtractionSourceGrounding(
-      result,
-      sourceText,
-      assertionSourceText,
-      roleAssertionSources,
-      messageTimestamp,
-      {
-        sourceGrounding: capabilities.sourceGrounding,
-        anchorTemporalExpressions: capabilities.delinearize,
-      },
-    );
-  }
-
   private finalizeExtractionResult(
     result: ExtractionResult,
     turns: ReadonlyArray<{
@@ -1127,8 +1102,10 @@ export class ExtractionEngine {
       timestamp: string;
       turnFingerprint?: string;
     }>,
+    sourceConnector?: string,
   ): ExtractionResult {
-    return attachExtractionProvenance(result, turns, this.config.provenance);
+    const provenanced = attachExtractionProvenance(result, turns, this.config.provenance);
+    return sourceConnector === undefined ? provenanced : { ...provenanced, sourceConnector };
   }
 
   async extract(
@@ -1153,13 +1130,17 @@ export class ExtractionEngine {
           : turn.content,
       }))
       .filter((turn) => turn.content.trim().length > 0);
-    const conversation = boundedTurns
-      .map((t) => {
-        const roleLabel =
-          t.extractionContextOnly === true ? `context ${t.role}` : t.role;
-        return `[${roleLabel}] ${t.content}`;
-      })
-      .join("\n\n");
+    // One derivation, over the turns the model actually sees (boundedTurns) —
+    // the same set the qualifier, grounding source, and telemetry filter
+    // operate on. result.sourceConnector carries it to persistence so the
+    // orchestrator does not recompute over a different turn set (#2183).
+    const resolvedConnector = resolveSourceConnector(boundedTurns);
+    // The header and qualifier strip/restore are gated on the scope-classification
+    // capability; persistence records resolvedConnector regardless (trusted metadata).
+    const sourceConnector = lifecycleCaps.extractionScopeClassification
+      ? resolvedConnector
+      : undefined;
+    const { conversation, renderedConversation } = renderExtractionConversation(boundedTurns, headerConnector(sourceConnector));
 
     const groundingSource = boundedTurns
       .map((turn) => turn.content)
@@ -1178,13 +1159,13 @@ export class ExtractionEngine {
         .map((turn) => turn.content)
         .join("\n\n"),
     };
-    if (conversation.trim().length === 0) {
+    if (renderedConversation.trim().length === 0) {
       log.debug("extraction skipped — conversation only contained non-memory work-layer context");
       return { facts: [], profileUpdates: [], entities: [], questions: [] };
     }
     if (
       lifecycleCaps.extractionTelemetryPrefilter &&
-      looksLikeMechanicalTelemetryTranscript(conversation)
+      looksLikeMechanicalTelemetryTranscript(renderedConversation)
     ) {
       log.debug("extraction skipped — mechanical action/state telemetry without durable-memory cues");
       return {
@@ -1198,6 +1179,14 @@ export class ExtractionEngine {
     // Use the last turn's timestamp for temporal anchoring (more accurate than wall-clock)
     const lastTurnTs = boundedTurns.length > 0 ? new Date(boundedTurns[boundedTurns.length - 1].timestamp) : undefined;
     const messageTimestamp = lastTurnTs && !isNaN(lastTurnTs.getTime()) ? lastTurnTs : undefined;
+    const groundingContext: ExtractionGroundingContext = {
+      groundingSource,
+      assertionSource,
+      roleAssertionSources,
+      messageTimestamp,
+      sourceConnector,
+      scopeClassificationEnabled: lifecycleCaps.extractionScopeClassification,
+    };
 
     const traceId = crypto.randomUUID();
     // Only emit llm_start for the direct path when a client or local LLM is configured.
@@ -1234,23 +1223,9 @@ export class ExtractionEngine {
           this.emit({ kind: "llm_end", traceId, model: this.config.localLlmModel, operation: "extraction", durationMs });
           log.debug(`extraction: used local LLM — ${localResult.facts.length} facts, ${localResult.entities.length} entities`);
           const sanitized = this.sanitizeExtractionResult(localResult, messageTimestamp);
-          const grounded = this.applySourceGrounding(
-            sanitized,
-            groundingSource,
-            assertionSource,
-            roleAssertionSources,
-            messageTimestamp,
-          );
-          const finalResult = await this.applyProactiveQuestionPass(
-            conversation,
-            grounded,
-            groundingSource,
-            assertionSource,
-            messageTimestamp,
-            roleAssertionSources,
-            signal,
-          );
-          return this.finalizeExtractionResult(finalResult, boundedTurns);
+          const grounded = applyGroundingWithConnector(this.config, sanitized, groundingContext);
+          const finalResult = await this.applyProactiveQuestionPass(conversation, grounded, groundingContext, signal);
+          return this.finalizeExtractionResult(finalResult, boundedTurns, resolvedConnector);
         }
         // Local failed, fall back if allowed
         if (!this.config.localLlmFallback) {
@@ -1297,23 +1272,9 @@ export class ExtractionEngine {
           this.emit({ kind: "llm_end", traceId, model: this.config.model, operation: "extraction", durationMs });
           log.debug(`extraction: used direct client (${this.config.model}) — ${directResult.facts.length} facts, ${directResult.entities.length} entities`);
           const sanitized = this.sanitizeExtractionResult(directResult, messageTimestamp);
-          const grounded = this.applySourceGrounding(
-            sanitized,
-            groundingSource,
-            assertionSource,
-            roleAssertionSources,
-            messageTimestamp,
-          );
-          const finalResult = await this.applyProactiveQuestionPass(
-            conversation,
-            grounded,
-            groundingSource,
-            assertionSource,
-            messageTimestamp,
-            roleAssertionSources,
-            signal,
-          );
-          return this.finalizeExtractionResult(finalResult, boundedTurns);
+          const grounded = applyGroundingWithConnector(this.config, sanitized, groundingContext);
+          const finalResult = await this.applyProactiveQuestionPass(conversation, grounded, groundingContext, signal);
+          return this.finalizeExtractionResult(finalResult, boundedTurns, resolvedConnector);
         }
         // Emit error event so Opik sees the direct client failure before fallback.
         // Wrapped in try/catch so a subscriber error doesn't break the fallback path.
@@ -1399,23 +1360,9 @@ export class ExtractionEngine {
         );
         const normalized = this.normalizeExtractionResultPayload(result);
         const sanitized = this.sanitizeExtractionResult(normalized, messageTimestamp);
-        const grounded = this.applySourceGrounding(
-          sanitized,
-          groundingSource,
-          assertionSource,
-          roleAssertionSources,
-          messageTimestamp,
-        );
-        const finalResult = await this.applyProactiveQuestionPass(
-          conversation,
-          grounded,
-          groundingSource,
-          assertionSource,
-          messageTimestamp,
-          roleAssertionSources,
-          signal,
-        );
-        return this.finalizeExtractionResult(finalResult, boundedTurns);
+        const grounded = applyGroundingWithConnector(this.config, sanitized, groundingContext);
+        const finalResult = await this.applyProactiveQuestionPass(conversation, grounded, groundingContext, signal);
+        return this.finalizeExtractionResult(finalResult, boundedTurns, resolvedConnector);
       }
 
       this.emit({
@@ -1519,7 +1466,7 @@ Rules:
 - Add structuredAttributes only for concrete values.
 - Include at most five durable relationships.${this.config.provenance?.enabled ? `
 - Each fact must include a quote copied verbatim from one contiguous conversation span.` : ""}${lifecycleCaps.extractionScopeClassification ? `
-- Set each fact scope to "global" for cross-project knowledge or "project" for codebase-specific knowledge.` : ""}
+- Set each fact scope to "global" for cross-project knowledge or "project" for codebase-specific knowledge. Tool, command, or CLI-flag instructions tied to one agent are "project" (the same tool name can mean different things across agents); when keeping one, begin the fact with a leading "In <agent>," clause naming that agent.` : ""}
 ${this.eventTimePromptInstruction()}
 Return only valid JSON matching this shape. Placeholder text describes field shape only and is never source evidence:
 ${EXTRACTION_RESPONSE_SHAPE}
@@ -1748,8 +1695,8 @@ Rules:
 
 Scope classification:
 For each fact, set "scope" to one of:
-- "global" — knowledge that applies across projects: core framework/library bugs, API behavior patterns, user preferences (editor, language, style), tool configurations, general coding patterns, infrastructure knowledge, technology facts not tied to one codebase
-- "project" — knowledge specific to one codebase: file paths, environment configs, deployment details, project-specific workarounds, team/stakeholder info tied to one project, repo-specific conventions
+- "global" — knowledge that applies across projects: core framework/library bugs, API behavior patterns, user preferences (editor, language, style), general coding patterns, infrastructure knowledge, technology facts not tied to one codebase
+- "project" — knowledge specific to one codebase: file paths, environment configs, deployment details, project-specific workarounds, team/stakeholder info tied to one project, repo-specific conventions. Tool, command, or CLI-flag instructions TIED TO ONE AGENT are also "project", because the same tool name means different things in different agent integrations (a "search" tool may search repository code in one agent and the web in another); when keeping such an agent-tied instruction, the fact text MUST name the originating agent as a leading "In <agent>," clause (e.g. "In Pi, use the search tool with a repository path."). A tool/command fact that holds in every agent and every repo is NOT agent-tied — leave it "global" and do not add a qualifier (e.g. "\`git status --short\` emits compact output"). Examples: "In Pi, the search tool takes a repository path" -> "project"; "\`git status --short\` emits compact output" -> "global".
 When in doubt, prefer "project" — it is safer to keep knowledge scoped narrowly.` : ""}
 Entity creation rules (STRICT):
 - Only create entities for DURABLE things: real people, companies, products, tools, ongoing projects

package/src/index.ts

@@ -1439,7 +1439,6 @@ export {
   type ForkLineage,
 } from "./transfer/capsule-fork.js";
 
-
 // ---------------------------------------------------------------------------
 // Coding-graph engine contract (#1551 PR1) — types owned by core,
 // implemented by @remnic/coding-graph (à-la-carte optional).
@@ -1460,3 +1459,4 @@ export type {
   ParseResult,
   SymbolIR,
 } from "./coding/coding-graph-types.js";
+export type { ResolvedScopeProfilePlan } from "./namespaces/scope-profiles.js";

package/src/orchestration/extraction-persist.ts

@@ -82,6 +82,7 @@ import {
   stripCitationForTemplate,
 } from "../source-attribution.js";
 import { classifyMemoryKind } from "../himem.js";
+import { shouldPromoteGlobalFactToShared, withholdToolScopedFromSharedNamespace } from "../tool-scoped-memory.js";
 import {
   buildBehaviorSignalsForMemory,
   dedupeBehaviorSignalsByMemoryAndHash,
@@ -394,6 +395,7 @@ export class ExtractionPersistCoordinator {
     // (pre-judge + write-loop) so no new scattered config.*Enabled read is
     // introduced (ratchet scatteredConfigFlagReads; see #1523).
     const namespacesEnabled = resolveNamespaceCapabilities(this.deps.config).namespaces;
+    const sourceConnector = sourceContext?.sourceConnector; // #2183 tool-scope guard input
     const promoteMemoryToProfileTargets = async (options: {
       sourceStorage: StorageManager;
       category: string;
@@ -607,11 +609,14 @@ export class ExtractionPersistCoordinator {
       observedAt?: string;
       eventTimeSource?: "extracted" | "assumed";
       source: string;
+      sourceConnector?: string;
+      procedureSteps?: ReadonlyArray<{ toolCall?: { kind?: string } }>;
       /** Claim-level provenance spans (issue #1575 PR 2). */
       sources?: ProvenanceSource[];
       provenance?: "verified" | "unverified" | "none";
     }): Promise<void> => {
       await promoteMemoryToProfileTargets(options);
+      if (lifecycleCaps.extractionScopeClassification && withholdToolScopedFromSharedNamespace(options)) return;
       if (
         !shouldPromoteToShared(
           this.deps.config,
@@ -629,7 +634,6 @@ export class ExtractionPersistCoordinator {
           this.deps.config.sharedNamespace,
         );
         // Dedup gate: canonicalize content before hashing.
-        //
         // Issue #369 (PR #401): When inline attribution is enabled,
         // `applyInlineCitation` appends a timestamp-bearing marker (e.g.
         // `[Source: ..., ts=2026-04-11T...]`).  Because the timestamp changes
@@ -639,7 +643,6 @@ export class ExtractionPersistCoordinator {
         // `fact.content`, which can already carry an inline citation (e.g. a
         // relayed or reprocessed fact).  Strip any pre-existing citation so the
         // dedup key matches the hash stored from the original un-cited write.
-        //
         // PR #402 round-6 (Fix #2 / chatgpt-codex P1 PRRT_kwDORJXyws56U74n):
         // Compute the enriched content before the hash-dedup check so the
         // lookup uses the same content that writeMemory will actually store.
@@ -652,7 +655,6 @@ export class ExtractionPersistCoordinator {
         // key order and casing are canonical — identical to the enrichment
         // applied by storage.writeMemory — preventing spurious hash misses
         // when attribute maps arrive with different insertion orders or casing.
-        //
         // Fix #4 (Low PRRT_kwDORJXyws56VHth): sanitize the base content before
         // building dedupContent.  writeMemory runs sanitizeMemoryContent on the
         // enriched body before hashing; if sanitization redacts the content to
@@ -660,7 +662,6 @@ export class ExtractionPersistCoordinator {
         // the raw form.  Computing dedupContent from sanitized.text here ensures
         // the hash lookup and the normalizedIncoming comparison both use the
         // same content that writeMemory will actually store.
-        //
         // Combined fix: strip any pre-existing citation FIRST to obtain
         // rawContent (the canonical body), then sanitize rawContent (not
         // options.content) when building dedupContent, so that citation
@@ -1350,20 +1351,18 @@ export class ExtractionPersistCoordinator {
           // + PBJEe/PBKAj).
           let factRedactionRules = preJudgeRedactionRules;
           let factNs = preRoutedNamespaceByFact[fi];
-          // #1713 (codex PRRT_kwDORJXyws6PBj5X): scope classification can route
-          // a scope=global fact to the shared namespace independent of routing
-          // rules. If so, the pre-judge filter must consult the shared
-          // namespace's rules too, or a never-store pattern under shared is
-          // missed at pre-judge and only caught at the write gate — letting the
-          // content reach the extraction judge/training path. Mirror the write
-          // loop's scope-routing conditions exactly.
+          // #1713: predict the same target namespace the write loop will route
+          // this global fact to (shared, via shouldPromoteGlobalFactToShared) so
+          // the pre-judge redaction filter consults that namespace's rules.
           if (
             !factNs &&
             lifecycleCaps.extractionScopeClassification &&
             namespacesEnabled &&
             f.scope === "global" &&
             profileAllowsSharedWrites &&
-            this.deps.storageDirNamespace(storage.dir) !== this.deps.config.sharedNamespace
+            this.deps.storageDirNamespace(storage.dir) !== this.deps.config.sharedNamespace &&
+            shouldPromoteGlobalFactToShared({ scope: f.scope, content: f.content,
+              sourceConnector, procedureSteps: f.procedureSteps })
           ) {
             factNs = this.deps.config.sharedNamespace;
           }
@@ -1611,14 +1610,9 @@ export class ExtractionPersistCoordinator {
         }
       }
 
-      // Scope-based namespace routing: when scope classification is enabled
-      // and the LLM tagged this fact as "global", route it to the shared
-      // namespace so cross-project knowledge is visible everywhere. Only
-      // applies when namespaces are enabled and the fact was not already
-      // routed to a specific namespace by a routing rule (routing rules
-      // that set an explicit namespace take precedence; category-only rules
-      // do not block scope routing). Rule 30: gated by
-      // extractionScopeClassificationEnabled.
+      // Scope-based namespace routing: a `global` fact (scope classification
+      // on, no explicit routing-rule namespace) is promoted to the shared
+      // namespace unless the tool-scope guard withholds it (#2183).
       if (
         lifecycleCaps.extractionScopeClassification &&
         namespacesEnabled &&
@@ -1627,18 +1621,21 @@ export class ExtractionPersistCoordinator {
       ) {
         const currentNs = this.deps.storageDirNamespace(targetStorage.dir);
         if (currentNs !== this.deps.config.sharedNamespace && profileAllowsSharedWrites) {
-          try {
-            targetStorage = await this.deps.getStorageRouter().storageFor(
-              this.deps.config.sharedNamespace,
-            );
-            targetNamespaceName = this.deps.config.sharedNamespace;
-            log.debug(
-              `scope-routing: fact "${fact.content.slice(0, 60)}…" routed to shared namespace (scope=global)`,
-            );
-          } catch (scopeRouteErr) {
-            log.warn(
-              `scope-routing: failed to resolve shared namespace storage; writing to session namespace (fail-open): ${scopeRouteErr}`,
-            );
+          if (shouldPromoteGlobalFactToShared({ scope: fact.scope, content: fact.content,
+            sourceConnector, procedureSteps: fact.procedureSteps })) {
+            try {
+              targetStorage = await this.deps.getStorageRouter().storageFor(
+                this.deps.config.sharedNamespace,
+              );
+              targetNamespaceName = this.deps.config.sharedNamespace;
+              log.debug(
+                `scope-routing: fact "${fact.content.slice(0, 60)}…" routed to shared namespace (scope=global)`,
+              );
+            } catch (scopeRouteErr) {
+              log.warn(
+                `scope-routing: failed to resolve shared namespace storage; writing to session namespace (fail-open): ${scopeRouteErr}`,
+              );
+            }
           }
         } else if (currentNs !== this.deps.config.sharedNamespace) {
           log.debug(
@@ -2404,6 +2401,7 @@ export class ExtractionPersistCoordinator {
               : {}),
             source: extractionWriteSource,
             ...(extractionSourceConnector ? { sourceConnector: extractionSourceConnector } : {}),
+            ...(fact.procedureSteps && fact.procedureSteps.length ? { procedureSteps: fact.procedureSteps } : {}),
             ...(fact.sources && fact.sources.length > 0 ? { sources: fact.sources } : {}),
             ...(fact.provenance ? { provenance: fact.provenance } : {}),
           });
@@ -2704,6 +2702,7 @@ export class ExtractionPersistCoordinator {
             : {}),
           source: extractionWriteSource,
           ...(extractionSourceConnector ? { sourceConnector: extractionSourceConnector } : {}),
+          ...(fact.procedureSteps && fact.procedureSteps.length ? { procedureSteps: fact.procedureSteps } : {}),
           ...(fact.sources && fact.sources.length > 0 ? { sources: fact.sources } : {}),
           ...(fact.provenance ? { provenance: fact.provenance } : {}),
         });

package/src/orchestration/extraction-run.ts

@@ -1067,7 +1067,7 @@ export class ExtractionRunCoordinator {
       result,
       storage,
       threadIdForExtraction,
-      { sessionKey, principal, validAt: sourceValidAt, sourceConnector: deriveSourceConnector(targetTurns as BufferTurn[]) },
+      { sessionKey, principal, validAt: sourceValidAt, sourceConnector: result.sourceConnector },
       // Pass the KNOWN base namespace (NHIdx) so the catalog write touch records the
       // real namespace rather than a guess decoded from the storage dir.
       selfNamespace,

package/src/orchestration/recall-result-formatter.ts

@@ -31,6 +31,7 @@ import type { VerifiedSemanticRuleResult } from "../semantic-rule-verifier.js";
 import type { WorkProductLedgerSearchResult } from "../work-product-ledger.js";
 import { trustResultFor, type TrustStageResultItem } from "../trust-score-stage.js";
 import { CONNECTOR_ID_PATTERN, CONNECTOR_LABEL_MAX_LENGTH } from "../connectors/label.js";
+import { isValidConnectorId } from "../connectors/index.js";
 import type {
   ContinuityIncidentRecord,
   IdentityInjectionMode,
@@ -49,7 +50,7 @@ import type {
  * exact signal this PR adds). One resolver at the single render site.
  */
 function renderConnectorLabel(connector: string | undefined): string | null {
-  if (!connector || !CONNECTOR_ID_PATTERN.test(connector)) return null;
+  if (!isValidConnectorId(connector)) return null;
   return connector.length <= CONNECTOR_LABEL_MAX_LENGTH
     ? connector
     : `${connector.slice(0, CONNECTOR_LABEL_MAX_LENGTH - 1)}…`;

package/src/schemas.ts

@@ -91,7 +91,7 @@ export const ExtractedFactSchema = z.object({
     .optional()
     .nullable()
     .describe(
-      'Scope classification: "global" for cross-project knowledge (framework bugs, library behavior, API patterns, user preferences, tool configs, general coding patterns); "project" for project-specific knowledge (file paths, env configs, deployment details, project workarounds). Defaults to "project" when a coding context is active.',
+      'Scope classification: "global" for cross-project knowledge (framework bugs, library behavior, API patterns, user preferences, general coding patterns); "project" for project-specific knowledge (file paths, env configs, deployment details, project workarounds) and for tool, command, or CLI-flag instructions tied to one agent, since the same tool name can mean different things across agents. When keeping such an agent-tied instruction, begin the fact with a leading "In <agent>," clause naming that agent. Defaults to "project" when a coding context is active.',
     ),
   quote: z
     .string()

package/src/source-agent-qualifier.ts

@@ -0,0 +1,156 @@
+/**
+ * Source-agent qualifier helpers for extraction (#2183).
+ *
+ * Pure leaf module: imports only types and sibling leaf/orchestration helpers,
+ * never `extraction.ts`, so it introduces no cycle (extraction-run.ts only
+ * type-imports extraction.ts).
+ */
+import { resolvePipelineProcessingCapabilities } from "./capabilities.js";
+import { applyExtractionSourceGrounding } from "./extraction-source-grounding.js";
+import type { ExtractionGroundingRoleSources } from "./extraction-source-grounding.js";
+import { isValidConnectorId } from "./connectors/index.js";
+import { CONNECTOR_LABEL_MAX_LENGTH, knownConnectorIds } from "./connectors/label.js";
+import { deriveSourceConnector } from "./orchestration/extraction-run.js";
+import type { BufferTurn, ExtractionResult, PluginConfig } from "./types.js";
+
+
+export function resolveSourceConnector(turns: readonly BufferTurn[]): string | undefined {
+  const contributing = turns.filter((turn) => turn.extractionContextOnly !== true);
+  const derived = deriveSourceConnector(contributing);
+  if (derived === undefined || !isValidConnectorId(derived)) return undefined;
+  return /[\u0000-\u001F\u007F]/.test(derived) ? undefined : derived;
+}
+
+// Same bound as the recall renderer (CONNECTOR_LABEL_MAX_LENGTH) but a DIFFERENT
+// policy: recall TRUNCATES past the bound (a truncated display label cannot
+// mislead), while the prompt SUPPRESSES (a truncated id could collide with a
+// different connector). Do not "fix" this inconsistency — it is deliberate.
+export function headerConnector(connector: string | undefined): string | undefined {
+  return connector !== undefined && connector.length <= CONNECTOR_LABEL_MAX_LENGTH ? connector : undefined;
+}
+
+export function renderExtractionConversation(
+  boundedTurns: readonly BufferTurn[],
+  sourceConnector: string | undefined,
+): { conversation: string; renderedConversation: string } {
+  const renderedConversation = boundedTurns
+    .map((t) => `[${t.extractionContextOnly === true ? `context ${t.role}` : t.role}] ${t.content}`)
+    .join("\n\n");
+  const conversation = sourceConnector === undefined
+    ? renderedConversation
+    : `Source agent: ${sourceConnector}\n\nTool and command instructions in this conversation apply to the ${sourceConnector} agent unless they are clearly universal.\n\n${renderedConversation}`;
+  return { conversation, renderedConversation };
+}
+
+export interface ExtractionGroundingContext {
+  groundingSource: string;
+  assertionSource: string;
+  roleAssertionSources?: ExtractionGroundingRoleSources;
+  messageTimestamp: Date | undefined;
+  sourceConnector?: string;
+  scopeClassificationEnabled?: boolean;
+}
+
+export function applyGroundingWithConnector(
+  config: PluginConfig,
+  result: ExtractionResult,
+  ctx: ExtractionGroundingContext,
+): ExtractionResult {
+  const caps = resolvePipelineProcessingCapabilities(config);
+  const options = { sourceGrounding: caps.sourceGrounding, anchorTemporalExpressions: caps.delinearize };
+  const known = buildKnownConnectors(ctx.sourceConnector);
+  // Scope-forcing is decoupled from strip/restore (runs without a trusted
+  // connector) but gated on the capability: flag off = byte-identical pre-#2183.
+  const scoped = ctx.scopeClassificationEnabled === false
+    ? result
+    : forceProjectScopeOnAnyQualifier(result, known);
+  if (ctx.sourceConnector === undefined) {
+    return applyExtractionSourceGrounding(scoped, ctx.groundingSource, ctx.assertionSource, ctx.roleAssertionSources, ctx.messageTimestamp, options);
+  }
+  const prepared = prepareTrustedConnectorQualifier(scoped, ctx.sourceConnector, known);
+  const grounded = applyExtractionSourceGrounding(prepared.result, ctx.groundingSource, ctx.assertionSource, ctx.roleAssertionSources, ctx.messageTimestamp, options);
+  return restoreTrustedConnectorQualifier(grounded);
+}
+
+function buildKnownConnectors(trusted: string | undefined): Set<string> {
+  const known = new Set<string>();
+  for (const id of knownConnectorIds()) known.add(id.toLowerCase());
+  if (trusted !== undefined) known.add(trusted.toLowerCase());
+  return known;
+}
+
+/**
+ * Parse a leading agent qualifier from fact text. ONE parser, ONE boundary
+ * rule, ONE case policy (case-insensitive), ONE definition of "agent" (the name
+ * must be a known connector ID). Returns the matched agent and the remaining
+ * text, or undefined. Both scope-forcing and strip/restore consume this single
+ * result so they can never disagree (#2183 round-11).
+ */
+function parseLeadingQualifier(content: string, known: ReadonlySet<string>): { agent: string; rest: string } | undefined {
+  const lower = content.toLowerCase();
+  for (const lead of ["in ", "for "]) {
+    if (!lower.startsWith(lead)) continue;
+    const m = lower.slice(lead.length).match(/^([a-z0-9][a-z0-9._-]*)\s*,/u);
+    if (m && known.has(m[1])) {
+      const consumed = lead.length + m[0].length;
+      return { agent: m[1], rest: content.slice(consumed).replace(/^[\s,.;:]+/u, "") };
+    }
+  }
+  const pm = lower.match(/^([a-z0-9][a-z0-9._-]*)'s(?![\p{L}\p{N}])/u);
+  if (pm && known.has(pm[1])) {
+    return { agent: pm[1], rest: content.slice(pm[0].length).replace(/^[\s,.;:]+/u, "") };
+  }
+  return undefined;
+}
+
+/**
+ * Force "project" scope on any fact whose content starts with a recognised
+ * agent qualifier (a known connector name). A qualifier is evidence the fact is
+ * agent-tied; which connector it names does not matter.
+ */
+function forceProjectScopeOnAnyQualifier(result: ExtractionResult, known: ReadonlySet<string>): ExtractionResult {
+  let any = false;
+  const facts = result.facts.map((fact) => {
+    if (fact.scope === "project") return fact;
+    if (parseLeadingQualifier(fact.content, known) === undefined) return fact;
+    any = true;
+    return { ...fact, scope: "project" as const };
+  });
+  return any ? { ...result, facts } : result;
+}
+
+const RESTORE_KEY = "_qo";
+
+/**
+ * Strip the TRUSTED connector's qualifier for the grounding pass. Uses the same
+ * parseLeadingQualifier as scope-forcing, but only strips when the matched agent
+ * IS the trusted connector. Each stripped fact carries its original content
+ * positionally for collision-free restore.
+ */
+function prepareTrustedConnectorQualifier(
+  result: ExtractionResult,
+  trustedConnector: string,
+  known: ReadonlySet<string>,
+): { result: ExtractionResult } {
+  const trusted = trustedConnector.toLowerCase();
+  const facts = result.facts.map((fact) => {
+    const parsed = parseLeadingQualifier(fact.content, known);
+    if (parsed === undefined || parsed.agent !== trusted) return fact;
+    return { ...fact, content: parsed.rest, [RESTORE_KEY]: fact.content };
+  }) as ExtractionResult["facts"];
+  return { result: { ...result, facts } };
+}
+
+function restoreTrustedConnectorQualifier(grounded: ExtractionResult): ExtractionResult {
+  let touched = false;
+  const facts = grounded.facts.map((fact) => {
+    const record = fact as unknown as Record<string, unknown>;
+    const original = record[RESTORE_KEY];
+    if (typeof original !== "string") return fact;
+    touched = true;
+    const rest = { ...record };
+    delete rest[RESTORE_KEY];
+    return { ...rest, content: original } as ExtractionResult["facts"][number];
+  });
+  return touched ? { ...grounded, facts } : grounded;
+}