@qloo/qloo-harness 0.1.18 → 0.1.20

package/README.md

@@ -23,6 +23,9 @@ Per-turn call budgets and repeated-call detection stop accidental tool loops.
 Qloo workflow state is stored as a versioned, bounded session entry so the
 latest intent and provenance survive resume and branching. A resumed or forked
 `build` session is automatically downgraded to read-only `plan` authority.
+User-confirmed entity and tag matches are stored separately with their semantic
+role and target scope, then reused before later tool calls so the same
+ambiguity is not presented repeatedly.
 Its responsive opening mark interprets Qloo's rounded wordmark and connected
 taste graph in terminal-native line art, using the Qloo purple-to-blue palette
 in truecolor and 256-color terminals.
@@ -50,8 +53,40 @@ restored when the runtime exits.
 
 ## Install and Run
 
-The harness currently runs from source. Prepare it once from the repository
-root:
+Requirements:
+
+- Node.js 22.19.0 or newer.
+- pnpm 11 or newer for the recommended installation path.
+
+Install the public
+[`@qloo/qloo-harness`](https://www.npmjs.com/package/@qloo/qloo-harness)
+package globally with pnpm:
+
+```sh
+pnpm add --global @qloo/qloo-harness
+```
+
+Or use npm instead:
+
+```sh
+npm install --global @qloo/qloo-harness
+```
+
+You only need one of those install commands. If pnpm reports that its global
+bin directory is not on `PATH`, run `pnpm setup`, open a new terminal, and
+retry the pnpm install.
+
+Confirm the installation, then start the harness:
+
+```sh
+qloo --version
+qloo
+```
+
+### Run from Source
+
+Contributors can prepare the repository once instead of installing the public
+package:
 
 ```sh
 npm ci
@@ -70,29 +105,23 @@ To inspect the available commands without starting an interactive session:
 node apps/qloo-harness/dist/bin.js --help
 ```
 
-### Optional Local Global Install
+When working from source, replace `qloo` in the examples below with
+`node apps/qloo-harness/dist/bin.js`.
 
-The harness does not need to be published to npm's registry to provide a bare
-`qloo` command. Build the verified tarball, then install that local artifact:
+### Test a Local Release Artifact
+
+To test unpublished changes through the same global-install shape, build the
+verified tarball and install that local artifact:
 
 ```sh
 npm run pack:qloo-harness
 QLOO_HARNESS_VERSION="$(node -p "require('./apps/qloo-harness/package.json').version")"
-npm install --global \
-  "./build/qloo-harness/qloo-qloo-harness-$QLOO_HARNESS_VERSION.tgz"
-
-qloo --version
-qloo
+QLOO_ARTIFACT="$(pwd -P)/build/qloo-harness/qloo-qloo-harness-$QLOO_HARNESS_VERSION.tgz"
+(cd /tmp && pnpm add --global "$QLOO_ARTIFACT")
 ```
 
-This creates the npm-global `qloo` link on the current machine without using a
-public registry package. Someone who already has the verified `.tgz` can skip
-the pack step and install its absolute path directly.
-
-Without that optional installation, replace `qloo` in the examples below with
-`node apps/qloo-harness/dist/bin.js` from the repository root. Interactive
-startup requires TTY stdin and stdout so it cannot accidentally consume piped
-automation input.
+Interactive startup requires TTY stdin and stdout so it cannot accidentally
+consume piped automation input.
 `qloo api <command>` and direct legacy verbs execute the existing CLI through
 its import-safe runner; no subprocess is used.
 
@@ -205,8 +234,8 @@ qloo update --force               # reinstall or explicitly downgrade
 qloo update --timeout 300         # bound each install phase to five minutes
 ```
 
-Self-update applies only to a future global npm or pnpm installation. A source
-checkout should be updated through Git and rebuilt with `npm run build`.
+Self-update applies only to a global npm or pnpm installation. A source checkout
+should be updated through Git and rebuilt with `npm run build`.
 
 Self-update first installs and smoke-checks the candidate in an isolated
 location, then activates it with whichever supported package manager owns the
@@ -232,8 +261,8 @@ The guarded release artifact is built with `npm run pack:qloo-harness`. Its
 release output compiles the unpublished Qloo client, tool schema, and legacy
 CLI into the harness while leaving pinned Pi as an ordinary registry
 dependency. The release gate installs and reinstalls the artifact with both npm
-and pnpm, including a pnpm-owned `qloo update --force` smoke. A future registry
-package will be published only from that verified artifact with
+and pnpm, including a pnpm-owned `qloo update --force` smoke. Registry releases
+are published only from that verified artifact with
 `npm run publish:qloo-harness`; direct source `npm pack` and `npm publish` are
 rejected by `prepack`.
 
@@ -263,6 +292,10 @@ The default `native` provider runs entirely inside the harness and uses Qloo
 for compatibility. Tag concepts use Qloo's semantic search, retain its returned
 rank, and are locally scoped to the requested entity domain when the response
 includes parent metadata. Identifiers and one exact normalized name proceed.
+For entity names with additional context, the native provider compares the
+supplied terms with candidate names, descriptions, types, and locations. A
+unique candidate matching every term can proceed with a warning and visible
+alternatives; otherwise only the context-compatible choices are shown.
 Unscored semantic candidates become guided choices instead of having
 popularity or result order relabeled as confidence. Entity and tag outcomes are
 cached in a bounded 15-minute session-local cache. No taste-resolver process,
@@ -302,6 +335,14 @@ input. Cache hits and all semantic choices remain visible in provenance.
 Resolver selection is never enabled by the mere presence of a URL and a
 failure never silently falls back to native tag search.
 
+The interactive harness adds confirmed-choice memory above that lookup cache.
+A choice is keyed by normalized input, entity-versus-tag role, and target scope;
+it is never reused across an incompatible tag target or entity type. Choices
+survive session resume and branching, while `/matches` can inspect or forget
+them. Several unresolved inputs from one workflow appear in one review dialog
+and are applied in one retry. Explicit location and naming terms also narrow
+entity candidates before the harness asks.
+
 `qloo_capabilities` returns the exact shared input/result schemas, active
 resolution strategy, and source documentation for selected operations without
 a network request. It identifies the harness, canonical Node MCP, and canonical
@@ -317,13 +358,16 @@ and normalized outputs at the project's existing code boundary.
 
 Inside chat, `/start` offers guided goals and `/status` reports the active
 profile, actual transport, model, workspace, context use, and turn budget.
+`/usage` shows the current model's context-window use as a raw token count and
+percentage, while `/exit` closes the harness cleanly.
 `/why`, `/sources`, `/request`, and `/trace` show the latest normalized query
 intent, provenance, safe underlying GET request preview, and privacy-safe
 execution metadata respectively. `/next` offers operation-aware continuations.
 `/doctor [network]` runs explicit diagnostics,
 `/raw [page|next|prev]` shows paginated redacted detail from the latest live
 normalized result, and `/retry` replays its recorded input once without model
-reconstruction. A DNS, connection, TLS, timeout, authentication, or resolver
+reconstruction. `/matches` inspects or forgets user-confirmed entity and tag
+choices. A DNS, connection, TLS, timeout, authentication, or resolver
 connection failure automatically runs one bounded diagnostic per turn and
 presents the most useful recovery step without dumping the full report. Qloo
 tool calls render the interpreted input, concise result,

package/dist/cli.js

@@ -5,7 +5,7 @@ const require = __qlooCreateRequire(import.meta.url);
 import { launchInteractiveHarness } from "./app.js";
 import { isQlooHarnessProfile, QLOO_DEFAULT_PROFILE, QLOO_HARNESS_PROFILES } from "./profiles.js";
 import { MissingModelAuthenticationError } from "./runtime/pi-adapter.js";
-var HARNESS_VERSION = "0.1.18";
+var HARNESS_VERSION = "0.1.20";
 var HARNESS_HELP = `Qloo terminal harness
 
 Usage:

package/dist/exec.js

@@ -195,12 +195,12 @@ var QLOO_LIMIT_SCHEMA = Type.Optional(Type.Integer({
 var QLOO_ENTITY_INPUTS_SCHEMA = Type.Array(Type.String({ minLength: 1 }), {
   minItems: 1,
   maxItems: 10,
-  description: "Entity names or Qloo entity UUIDs. Keep one combined taste profile in one call."
+  description: "Named entities or Qloo entity UUIDs; use tag fields for abstract concepts."
 });
 var QLOO_TAG_INPUTS_SCHEMA = Type.Array(Type.String({ minLength: 1 }), {
   minItems: 1,
   maxItems: 10,
-  description: "Natural-language tag concepts or stable Qloo tag URNs."
+  description: "Genres, moods, styles, traits, or other concepts, or Qloo tag URNs; not named entities."
 });
 var QLOO_DEMOGRAPHIC_SCHEMA = Type.String({
   minLength: 1,
@@ -360,6 +360,7 @@ var QLOO_WORKFLOW_METADATA = {
     promptSnippet: "Recommend entities from a combined Qloo taste profile",
     promptGuidelines: [
       "Pass every related taste and audience signal together in one qloo_recommend call.",
+      "Put named things in signals; put genres, moods, styles, traits, and concepts such as quiet luxury in signal_tags; reuse returned Qloo UUIDs and tag URNs.",
       "Use signal_location for audience location and filter_location to constrain result geography.",
       "Include demographic and location in the same call when both describe the audience."
     ],
@@ -370,7 +371,10 @@ var QLOO_WORKFLOW_METADATA = {
     label: "Qloo rank",
     description: "Rank one supplied option set against one shared entity, location, demographic, and tag profile. Scores from separate calls are not comparable.",
     promptSnippet: "Rank a caller-supplied shortlist with Qloo",
-    promptGuidelines: ["Pass every option in one qloo_rank call so scores remain comparable."],
+    promptGuidelines: [
+      "Pass every option in one qloo_rank call so scores remain comparable.",
+      "Put named things in entity fields and concepts in tag fields; reuse returned Qloo UUIDs and tag URNs."
+    ],
     documentation: ["https://docs.qloo.com/reference/insights-api-deep-dive"]
   },
   describe: {

package/dist/index.d.ts

@@ -161,6 +161,7 @@ declare const QLOO_WORKFLOW_INPUT_SCHEMAS: {
         limit: Type.TOptional<Type.TInteger>;
     }>;
 };
+type QlooWorkflowResolutionInputKind = "entity" | "tag";
 type QlooRecommendInput = Static<typeof QLOO_WORKFLOW_INPUT_SCHEMAS.recommend>;
 type QlooRankInput = Static<typeof QLOO_WORKFLOW_INPUT_SCHEMAS.rank>;
 type QlooDescribeInput = Static<typeof QLOO_WORKFLOW_INPUT_SCHEMAS.describe>;
@@ -673,7 +674,7 @@ interface LaunchInteractiveHarnessOptions {
 }
 declare function launchInteractiveHarness(options?: LaunchInteractiveHarnessOptions): Promise<void>;
 
-declare const HARNESS_VERSION = "0.1.18";
+declare const HARNESS_VERSION = "0.1.20";
 declare const HARNESS_HELP = "Qloo terminal harness\n\nUsage:\n  qloo              Start guided Qloo chat\n  qloo chat         Start guided Qloo chat explicitly\n  qloo explore      Ask grounded Qloo questions (read-only workspace)\n  qloo integrate    Inspect and design a Qloo integration\n  qloo plan         Open interactive read-only planning\n  qloo plan \"<goal>\" --json\n                    Create a typed, evidence-backed plan\n  qloo build        Open approval-gated build mode\n  qloo build --plan <plan-id>\n                    Build from a validated integration plan\n  qloo chat --mode <explore|integrate|plan|build>\n  qloo --help       Show this help\n  qloo --version    Show the harness version\n\nThe deterministic API CLI and additional harness commands are attached by the\ntop-level qloo command router.";
 interface HarnessCliDependencies {
     launch: (profile: QlooHarnessProfile) => Promise<void>;
@@ -933,6 +934,26 @@ interface QlooTextComponent {
 interface QlooResolutionChoice {
     readonly input: string;
     readonly selectedId: string;
+    readonly selectedName?: string;
+    readonly selectedType?: string;
+    readonly field?: string;
+    readonly inputKind?: QlooWorkflowResolutionInputKind;
+    readonly scope?: string;
+    readonly purpose?: "signal" | "include_filter" | "exclude_filter";
+}
+interface QlooResolutionCandidateIssue {
+    readonly input: string;
+    readonly candidates: readonly Record<string, unknown>[];
+    readonly field?: string;
+    readonly inputKind?: QlooWorkflowResolutionInputKind;
+    readonly scope?: string;
+    readonly purpose?: "signal" | "include_filter" | "exclude_filter";
+}
+interface QlooResolutionInputContext {
+    readonly field: string;
+    readonly inputKind: QlooWorkflowResolutionInputKind;
+    readonly scope?: string;
+    readonly purpose?: "signal" | "include_filter" | "exclude_filter";
 }
 declare function formatQlooResolutionCandidateLabels(candidates: readonly Readonly<Record<string, unknown>>[]): string[];
 declare function renderQlooCallLines(toolName: string, input: Readonly<Record<string, unknown>>, width: number): string[];
@@ -944,10 +965,8 @@ declare function createQlooCallComponent(toolName: string, input: Readonly<Recor
 declare function createQlooResultComponent(details: unknown, expanded: boolean, theme: QlooPresentationTheme): QlooTextComponent;
 declare function paginateQlooResult(detailsValue: Readonly<Record<string, unknown>>, requestedPage: number, pageSize?: number): Record<string, unknown>;
 declare function parseQlooRawPage(argument: string, currentPage: number): number | undefined;
-declare function resolutionCandidates(detailsValue: unknown): readonly {
-    readonly input: string;
-    readonly candidates: readonly Record<string, unknown>[];
-}[];
+declare function resolutionInputContexts(toolName: string, input: Readonly<Record<string, unknown>>): readonly QlooResolutionInputContext[];
+declare function resolutionCandidates(detailsValue: unknown, toolName?: string, toolInput?: Readonly<Record<string, unknown>>): readonly QlooResolutionCandidateIssue[];
 declare function applyResolutionChoices(toolName: string, input: Readonly<Record<string, unknown>>, choices: readonly QlooResolutionChoice[]): Record<string, unknown> | undefined;
 
 /**
@@ -1082,6 +1101,51 @@ interface CreateProjectContextToolOptions {
 }
 declare function createProjectContextTool(options: CreateProjectContextToolOptions): ToolDefinition;
 
+declare const QLOO_RESOLUTION_CHOICE_ENTRY_TYPE: "qloo.resolution-choice";
+declare const QLOO_RESOLUTION_CHOICE_SCHEMA_VERSION: "1.0";
+interface QlooConfirmedResolutionBinding {
+    readonly tool_name: string;
+    readonly input: string;
+    readonly input_kind: QlooWorkflowResolutionInputKind;
+    readonly field: string;
+    readonly scope?: string;
+    readonly purpose?: "signal" | "include_filter" | "exclude_filter";
+    readonly selected: {
+        readonly id: string;
+        readonly name: string;
+        readonly type?: string;
+    };
+    readonly source: "user";
+}
+type QlooResolutionChoiceEvent = {
+    readonly schema_version: typeof QLOO_RESOLUTION_CHOICE_SCHEMA_VERSION;
+    readonly action: "remember";
+    readonly choices: readonly QlooConfirmedResolutionBinding[];
+} | {
+    readonly schema_version: typeof QLOO_RESOLUTION_CHOICE_SCHEMA_VERSION;
+    readonly action: "forget";
+    readonly binding: Pick<QlooConfirmedResolutionBinding, "input" | "input_kind" | "scope">;
+} | {
+    readonly schema_version: typeof QLOO_RESOLUTION_CHOICE_SCHEMA_VERSION;
+    readonly action: "clear";
+};
+interface QlooResolutionMemoryApplication {
+    readonly input: Record<string, unknown>;
+    readonly reused: readonly QlooConfirmedResolutionBinding[];
+}
+declare class QlooResolutionMemory {
+    #private;
+    clear(): void;
+    list(): readonly QlooConfirmedResolutionBinding[];
+    remember(toolName: string, choices: readonly QlooResolutionChoice[]): readonly QlooConfirmedResolutionBinding[];
+    forget(binding: Pick<QlooConfirmedResolutionBinding, "input" | "input_kind" | "scope">): boolean;
+    restore(entries: readonly unknown[]): void;
+    apply(toolName: string, input: Readonly<Record<string, unknown>>): QlooResolutionMemoryApplication | undefined;
+}
+declare function rememberResolutionChoicesEvent(choices: readonly QlooConfirmedResolutionBinding[]): QlooResolutionChoiceEvent;
+declare function forgetResolutionChoiceEvent(binding: Pick<QlooConfirmedResolutionBinding, "input" | "input_kind" | "scope">): QlooResolutionChoiceEvent;
+declare function clearResolutionChoicesEvent(): QlooResolutionChoiceEvent;
+
 declare const PINNED_PI_VERSION = "0.84.2";
 declare const BLOCKED_PI_INTERACTIVE_COMMANDS: ReadonlySet<string>;
 declare const PI_SHARE_BLOCK_MESSAGE = "External session sharing is disabled in the Qloo harness.";
@@ -1317,5 +1381,5 @@ interface CanonicalMcpServerLifecycle {
 declare function startCanonicalMcpServer(options?: CanonicalMcpServerOptions): CanonicalMcpServerLifecycle;
 declare function runQlooMcp(argv: readonly string[], options?: CanonicalMcpServerOptions): number;
 
-export { BLOCKED_PI_INTERACTIVE_COMMANDS, HARNESS_HELP, HARNESS_VERSION, MissingModelAuthenticationError, PINNED_PI_VERSION, PI_AGENT_DIR_ENVIRONMENT_VARIABLE, PI_OFFLINE_ENVIRONMENT_VARIABLE, PI_SHARE_BLOCK_MESSAGE, PI_SKIP_VERSION_CHECK_ENVIRONMENT_VARIABLE, PI_TELEMETRY_ENVIRONMENT_VARIABLE, PI_TRUST_BLOCK_MESSAGE, PI_VERSION, PiCommandPolicyCompatibilityError, PiHarnessRuntime, QLOO_BUILD_HELP, QLOO_DEFAULT_PROFILE, QLOO_EXECUTION_LOG_SCHEMA_VERSION, QLOO_EXEC_EVENT_SCHEMA_VERSION, QLOO_EXEC_HELP, QLOO_EXEC_MAX_INPUT_BYTES, QLOO_GUIDED_GOALS, QLOO_HARNESS_PACKAGE_NAME, QLOO_HARNESS_PROFILES, QLOO_HELP, QLOO_INTEGRATION_PLAN_DRAFT_SCHEMA, QLOO_INTEGRATION_PLAN_ID_PATTERN, QLOO_INTEGRATION_PLAN_MAX_BYTES, QLOO_INTEGRATION_PLAN_MAX_EVIDENCE_BYTES, QLOO_INTEGRATION_PLAN_MAX_GOAL_BYTES, QLOO_INTEGRATION_PLAN_SCHEMA, QLOO_INTEGRATION_PLAN_SCHEMA_VERSION, QLOO_MCP_CONTRACT_RESOURCE_URI, QLOO_MCP_HELP, QLOO_MODEL_RETRY_POLICY, QLOO_NO_GUIDED_START_ENVIRONMENT_VARIABLE, QLOO_PLAN_HELP, QLOO_PROFILE_DEFINITIONS, QLOO_PROJECT_CONTEXT_SCHEMA_VERSION, QLOO_RESOLUTION_PROVIDER_ENVIRONMENT_VARIABLE, QLOO_SESSION_STATE_ENTRY_TYPE, QLOO_SESSION_STATE_SCHEMA_VERSION, QLOO_SETUP_HELP, QLOO_SETUP_SCHEMA_VERSION, QLOO_TASTE_RESOLVER_MIN_MARGIN_ENVIRONMENT_VARIABLE, QLOO_TASTE_RESOLVER_MIN_SCORE_ENVIRONMENT_VARIABLE, QLOO_TASTE_RESOLVER_TAG_ENDPOINT_ENVIRONMENT_VARIABLE, QLOO_TRUSTED_TASTE_RESOLVER_URL_ENVIRONMENT_VARIABLE, QLOO_UPDATE_HELP, QLOO_UPDATE_SPEC_ENVIRONMENT_VARIABLE, QLOO_WORKSPACE_TOOL_NAMES, QlooIntegrationPlanError, QlooResolutionProviderError, QlooWorkflowExecutionError, TASTE_RESOLVER_API_KEY_ENVIRONMENT_VARIABLE, TASTE_RESOLVER_URL_ENVIRONMENT_VARIABLE, applyPiInteractiveCommandPolicy, applyQlooModelRetryPolicy, applyResolutionChoices, buildExploreResourceOptions, buildExploreToolNames, buildHarnessResourceOptions, buildProfileToolNames, createBuildHandoffPrompt, createCliQlooWorkflowExecutor, createDelegatingQlooWorkflowExecutor, createDirectQlooWorkflowExecutor, createDirectQlooWorkflowExecutorFromEnvironment, createExplorePolicyExtension, createFileExecutionObserver, createHarnessPolicyExtension, createIntegrationPlanArtifact, createIntegrationPlanPrompt, createIntegrationPlanSubmissionTool, createMcpQlooWorkflowExecutor, createNativeQlooResolutionProvider, createPiHarnessRuntime, createProjectContextTool, createPublicQlooResolutionProvider, createQlooCallComponent, createQlooResolutionProviderFromEnvironment, createQlooResultComponent, createQlooTools, createQlooToolsFromEnvironment, createTasteResolverAssistedResolutionProvider, createTerminalSetupIO, ensureQlooStateDirectories, findGuidedGoal, formatDoctorReport, formatQlooResolutionCandidateLabels, formatQlooSetupReport, getQlooProfileDefinition, getQlooToolRuntimeInfo, guidedGoalLabel, inferGlobalInstallPrefix, inspectPiAuthFile, inspectProjectContext, inspectQlooResolutionProviderConfiguration, isBlockedPiInteractiveCommand, isQlooHarnessProfile, launchInteractiveHarness, loadHarnessResources, loadIntegrationPlanArtifact, paginateQlooResult, parseQlooRawPage, probeTasteResolverHealth, qlooNextActions, renderQlooCallLines, renderQlooResultLines, requireAuthenticatedModel, resolutionCandidates, resolveQlooPaths, runDoctor, runHarnessCli, runQloo, runQlooBuild, runQlooExec, runQlooMcp, runQlooPlan, runQlooSetup, runQlooUpdate, saveIntegrationPlanArtifact, setupQloo, startCanonicalMcpServer, validateExploreTools, withPiAgentDirectory, withPiPrivacyDefaults };
-export type { CanonicalMcpServerLifecycle, CanonicalMcpServerOptions, CreateDelegatingQlooExecutorOptions, CreateDirectQlooWorkflowExecutorFromEnvironmentOptions, CreateFileExecutionObserverOptions, CreateIntegrationPlanArtifactOptions, CreateIntegrationPlanSubmissionOptions, CreatePiHarnessRuntimeOptions, CreateProjectContextToolOptions, CreateQlooResolutionProviderFromEnvironmentOptions, CreateQlooToolsFromEnvironmentOptions, CreateQlooToolsOptions, DoctorCheck, DoctorReport, EnsureQlooStateOptions, HarnessPrerequisite, HarnessPrerequisiteContext, HarnessResources, HarnessRuntime, HarnessRuntimeFactory, InspectProjectContextOptions, InspectQlooResolutionProviderConfigurationOptions, IntegrationPlanSubmission, LaunchInteractiveHarnessOptions, LoadHarnessResourcesOptions, LoadIntegrationPlanArtifactOptions, NativeQlooResolutionProviderOptions, PiAuthFileInspection, ProjectContextResult, QlooEntityResolutionRequest, QlooExecCompletedEvent, QlooExecEvent, QlooExecFailedEvent, QlooExecStartedEvent, QlooExecutionLogRecord, QlooGuidedGoal, QlooGuidedGoalId, QlooGuidedStarter, QlooHarnessProfile, QlooIntegrationPlan, QlooIntegrationPlanDraft, QlooIntegrationPlanErrorCode, QlooInteractiveCommandActions, QlooNextAction, QlooPaths, QlooPresentationTheme, QlooProfileDefinition, QlooProjectContext, QlooResolutionBatch, QlooResolutionChoice, QlooResolutionClient, QlooResolutionContext, QlooResolutionProvider, QlooResolutionProviderConfigurationInspection, QlooResolutionProviderErrorCode, QlooRouterDependencies, QlooSetupChoice, QlooSetupIO, QlooSetupModelRuntime, QlooSetupOptions, QlooSetupReport, QlooTagResolutionPurpose, QlooTagResolutionRequest, QlooTextComponent, QlooToolClient, QlooToolRuntimeInfo, QlooTransportDescriptor, QlooTransportKind, QlooWorkflowExecution, QlooWorkflowExecutionContext, QlooWorkflowExecutionObserver, QlooWorkflowExecutor, QlooWorkflowFailure, QlooWorkflowResultEnvelope, ResolveQlooPathsOptions, RunDoctorOptions, RunQlooBuildOptions, RunQlooExecOptions, RunQlooPlanOptions, RunQlooSetupOptions, RunQlooUpdateOptions, TasteResolverHealthKind, TasteResolverHealthProbeOptions, TasteResolverHealthProbeResult, TasteResolverResolutionProviderOptions, TasteResolverTagEndpoint };
+export { BLOCKED_PI_INTERACTIVE_COMMANDS, HARNESS_HELP, HARNESS_VERSION, MissingModelAuthenticationError, PINNED_PI_VERSION, PI_AGENT_DIR_ENVIRONMENT_VARIABLE, PI_OFFLINE_ENVIRONMENT_VARIABLE, PI_SHARE_BLOCK_MESSAGE, PI_SKIP_VERSION_CHECK_ENVIRONMENT_VARIABLE, PI_TELEMETRY_ENVIRONMENT_VARIABLE, PI_TRUST_BLOCK_MESSAGE, PI_VERSION, PiCommandPolicyCompatibilityError, PiHarnessRuntime, QLOO_BUILD_HELP, QLOO_DEFAULT_PROFILE, QLOO_EXECUTION_LOG_SCHEMA_VERSION, QLOO_EXEC_EVENT_SCHEMA_VERSION, QLOO_EXEC_HELP, QLOO_EXEC_MAX_INPUT_BYTES, QLOO_GUIDED_GOALS, QLOO_HARNESS_PACKAGE_NAME, QLOO_HARNESS_PROFILES, QLOO_HELP, QLOO_INTEGRATION_PLAN_DRAFT_SCHEMA, QLOO_INTEGRATION_PLAN_ID_PATTERN, QLOO_INTEGRATION_PLAN_MAX_BYTES, QLOO_INTEGRATION_PLAN_MAX_EVIDENCE_BYTES, QLOO_INTEGRATION_PLAN_MAX_GOAL_BYTES, QLOO_INTEGRATION_PLAN_SCHEMA, QLOO_INTEGRATION_PLAN_SCHEMA_VERSION, QLOO_MCP_CONTRACT_RESOURCE_URI, QLOO_MCP_HELP, QLOO_MODEL_RETRY_POLICY, QLOO_NO_GUIDED_START_ENVIRONMENT_VARIABLE, QLOO_PLAN_HELP, QLOO_PROFILE_DEFINITIONS, QLOO_PROJECT_CONTEXT_SCHEMA_VERSION, QLOO_RESOLUTION_CHOICE_ENTRY_TYPE, QLOO_RESOLUTION_CHOICE_SCHEMA_VERSION, QLOO_RESOLUTION_PROVIDER_ENVIRONMENT_VARIABLE, QLOO_SESSION_STATE_ENTRY_TYPE, QLOO_SESSION_STATE_SCHEMA_VERSION, QLOO_SETUP_HELP, QLOO_SETUP_SCHEMA_VERSION, QLOO_TASTE_RESOLVER_MIN_MARGIN_ENVIRONMENT_VARIABLE, QLOO_TASTE_RESOLVER_MIN_SCORE_ENVIRONMENT_VARIABLE, QLOO_TASTE_RESOLVER_TAG_ENDPOINT_ENVIRONMENT_VARIABLE, QLOO_TRUSTED_TASTE_RESOLVER_URL_ENVIRONMENT_VARIABLE, QLOO_UPDATE_HELP, QLOO_UPDATE_SPEC_ENVIRONMENT_VARIABLE, QLOO_WORKSPACE_TOOL_NAMES, QlooIntegrationPlanError, QlooResolutionMemory, QlooResolutionProviderError, QlooWorkflowExecutionError, TASTE_RESOLVER_API_KEY_ENVIRONMENT_VARIABLE, TASTE_RESOLVER_URL_ENVIRONMENT_VARIABLE, applyPiInteractiveCommandPolicy, applyQlooModelRetryPolicy, applyResolutionChoices, buildExploreResourceOptions, buildExploreToolNames, buildHarnessResourceOptions, buildProfileToolNames, clearResolutionChoicesEvent, createBuildHandoffPrompt, createCliQlooWorkflowExecutor, createDelegatingQlooWorkflowExecutor, createDirectQlooWorkflowExecutor, createDirectQlooWorkflowExecutorFromEnvironment, createExplorePolicyExtension, createFileExecutionObserver, createHarnessPolicyExtension, createIntegrationPlanArtifact, createIntegrationPlanPrompt, createIntegrationPlanSubmissionTool, createMcpQlooWorkflowExecutor, createNativeQlooResolutionProvider, createPiHarnessRuntime, createProjectContextTool, createPublicQlooResolutionProvider, createQlooCallComponent, createQlooResolutionProviderFromEnvironment, createQlooResultComponent, createQlooTools, createQlooToolsFromEnvironment, createTasteResolverAssistedResolutionProvider, createTerminalSetupIO, ensureQlooStateDirectories, findGuidedGoal, forgetResolutionChoiceEvent, formatDoctorReport, formatQlooResolutionCandidateLabels, formatQlooSetupReport, getQlooProfileDefinition, getQlooToolRuntimeInfo, guidedGoalLabel, inferGlobalInstallPrefix, inspectPiAuthFile, inspectProjectContext, inspectQlooResolutionProviderConfiguration, isBlockedPiInteractiveCommand, isQlooHarnessProfile, launchInteractiveHarness, loadHarnessResources, loadIntegrationPlanArtifact, paginateQlooResult, parseQlooRawPage, probeTasteResolverHealth, qlooNextActions, rememberResolutionChoicesEvent, renderQlooCallLines, renderQlooResultLines, requireAuthenticatedModel, resolutionCandidates, resolutionInputContexts, resolveQlooPaths, runDoctor, runHarnessCli, runQloo, runQlooBuild, runQlooExec, runQlooMcp, runQlooPlan, runQlooSetup, runQlooUpdate, saveIntegrationPlanArtifact, setupQloo, startCanonicalMcpServer, validateExploreTools, withPiAgentDirectory, withPiPrivacyDefaults };
+export type { CanonicalMcpServerLifecycle, CanonicalMcpServerOptions, CreateDelegatingQlooExecutorOptions, CreateDirectQlooWorkflowExecutorFromEnvironmentOptions, CreateFileExecutionObserverOptions, CreateIntegrationPlanArtifactOptions, CreateIntegrationPlanSubmissionOptions, CreatePiHarnessRuntimeOptions, CreateProjectContextToolOptions, CreateQlooResolutionProviderFromEnvironmentOptions, CreateQlooToolsFromEnvironmentOptions, CreateQlooToolsOptions, DoctorCheck, DoctorReport, EnsureQlooStateOptions, HarnessPrerequisite, HarnessPrerequisiteContext, HarnessResources, HarnessRuntime, HarnessRuntimeFactory, InspectProjectContextOptions, InspectQlooResolutionProviderConfigurationOptions, IntegrationPlanSubmission, LaunchInteractiveHarnessOptions, LoadHarnessResourcesOptions, LoadIntegrationPlanArtifactOptions, NativeQlooResolutionProviderOptions, PiAuthFileInspection, ProjectContextResult, QlooConfirmedResolutionBinding, QlooEntityResolutionRequest, QlooExecCompletedEvent, QlooExecEvent, QlooExecFailedEvent, QlooExecStartedEvent, QlooExecutionLogRecord, QlooGuidedGoal, QlooGuidedGoalId, QlooGuidedStarter, QlooHarnessProfile, QlooIntegrationPlan, QlooIntegrationPlanDraft, QlooIntegrationPlanErrorCode, QlooInteractiveCommandActions, QlooNextAction, QlooPaths, QlooPresentationTheme, QlooProfileDefinition, QlooProjectContext, QlooResolutionBatch, QlooResolutionCandidateIssue, QlooResolutionChoice, QlooResolutionChoiceEvent, QlooResolutionClient, QlooResolutionContext, QlooResolutionInputContext, QlooResolutionMemoryApplication, QlooResolutionProvider, QlooResolutionProviderConfigurationInspection, QlooResolutionProviderErrorCode, QlooRouterDependencies, QlooSetupChoice, QlooSetupIO, QlooSetupModelRuntime, QlooSetupOptions, QlooSetupReport, QlooTagResolutionPurpose, QlooTagResolutionRequest, QlooTextComponent, QlooToolClient, QlooToolRuntimeInfo, QlooTransportDescriptor, QlooTransportKind, QlooWorkflowExecution, QlooWorkflowExecutionContext, QlooWorkflowExecutionObserver, QlooWorkflowExecutor, QlooWorkflowFailure, QlooWorkflowResultEnvelope, ResolveQlooPathsOptions, RunDoctorOptions, RunQlooBuildOptions, RunQlooExecOptions, RunQlooPlanOptions, RunQlooSetupOptions, RunQlooUpdateOptions, TasteResolverHealthKind, TasteResolverHealthProbeOptions, TasteResolverHealthProbeResult, TasteResolverResolutionProviderOptions, TasteResolverTagEndpoint };

package/dist/index.js

@@ -10,7 +10,7 @@ import { createIntegrationPlanPrompt, QLOO_PLAN_HELP, runQlooPlan } from "./plan
 import { getQlooProfileDefinition, isQlooHarnessProfile, QLOO_DEFAULT_PROFILE, QLOO_HARNESS_PROFILES, QLOO_PROFILE_DEFINITIONS } from "./profiles.js";
 import { formatDoctorReport, inspectPiAuthFile, runDoctor } from "./doctor.js";
 import { createQlooTools, createDirectQlooWorkflowExecutor, createDirectQlooWorkflowExecutorFromEnvironment, createQlooToolsFromEnvironment, getQlooToolRuntimeInfo } from "./qloo-tools.js";
-import { applyResolutionChoices, createQlooCallComponent, createQlooResultComponent, formatQlooResolutionCandidateLabels, paginateQlooResult, parseQlooRawPage, renderQlooCallLines, renderQlooResultLines, resolutionCandidates } from "./qloo-presentation.js";
+import { applyResolutionChoices, createQlooCallComponent, createQlooResultComponent, formatQlooResolutionCandidateLabels, paginateQlooResult, parseQlooRawPage, renderQlooCallLines, renderQlooResultLines, resolutionCandidates, resolutionInputContexts } from "./qloo-presentation.js";
 import { createNativeQlooResolutionProvider, createPublicQlooResolutionProvider, createQlooResolutionProviderFromEnvironment, createTasteResolverAssistedResolutionProvider, inspectQlooResolutionProviderConfiguration, probeTasteResolverHealth, QLOO_RESOLUTION_PROVIDER_ENVIRONMENT_VARIABLE, QLOO_TASTE_RESOLVER_MIN_MARGIN_ENVIRONMENT_VARIABLE, QLOO_TASTE_RESOLVER_MIN_SCORE_ENVIRONMENT_VARIABLE, QLOO_TASTE_RESOLVER_TAG_ENDPOINT_ENVIRONMENT_VARIABLE, QLOO_TRUSTED_TASTE_RESOLVER_URL_ENVIRONMENT_VARIABLE, QlooResolutionProviderError, TASTE_RESOLVER_API_KEY_ENVIRONMENT_VARIABLE, TASTE_RESOLVER_URL_ENVIRONMENT_VARIABLE } from "./resolution-provider.js";
 import { PI_VERSION, QLOO_HELP, runQloo } from "./router.js";
 import { QLOO_EXEC_EVENT_SCHEMA_VERSION, QLOO_EXEC_HELP, QLOO_EXEC_MAX_INPUT_BYTES, runQlooExec } from "./exec.js";
@@ -18,6 +18,7 @@ import { ensureQlooStateDirectories, resolveQlooPaths } from "./paths.js";
 import { createProjectContextTool, inspectProjectContext, QLOO_PROJECT_CONTEXT_SCHEMA_VERSION } from "./project-context.js";
 import { buildExploreResourceOptions, buildHarnessResourceOptions, applyQlooModelRetryPolicy, createPiHarnessRuntime, MissingModelAuthenticationError, PI_AGENT_DIR_ENVIRONMENT_VARIABLE, PI_OFFLINE_ENVIRONMENT_VARIABLE, PI_SKIP_VERSION_CHECK_ENVIRONMENT_VARIABLE, PI_TELEMETRY_ENVIRONMENT_VARIABLE, QLOO_MODEL_RETRY_POLICY, PiHarnessRuntime, requireAuthenticatedModel, withPiAgentDirectory, withPiPrivacyDefaults } from "./runtime/pi-adapter.js";
 import { buildExploreToolNames, buildProfileToolNames, createHarnessPolicyExtension, createExplorePolicyExtension, QLOO_SESSION_STATE_ENTRY_TYPE, QLOO_SESSION_STATE_SCHEMA_VERSION, QLOO_WORKSPACE_TOOL_NAMES, validateExploreTools } from "./runtime/explore-policy.js";
+import { QLOO_RESOLUTION_CHOICE_ENTRY_TYPE, QLOO_RESOLUTION_CHOICE_SCHEMA_VERSION, QlooResolutionMemory, clearResolutionChoicesEvent, forgetResolutionChoiceEvent, rememberResolutionChoicesEvent } from "./runtime/resolution-memory.js";
 import { applyPiInteractiveCommandPolicy, BLOCKED_PI_INTERACTIVE_COMMANDS, isBlockedPiInteractiveCommand, PI_SHARE_BLOCK_MESSAGE, PI_TRUST_BLOCK_MESSAGE, PiCommandPolicyCompatibilityError, PINNED_PI_VERSION } from "./runtime/pi-command-policy.js";
 import { loadHarnessResources } from "./runtime/resources.js";
 import { findGuidedGoal, guidedGoalLabel, QLOO_GUIDED_GOALS, qlooNextActions } from "./guided-journey.js";
@@ -65,6 +66,8 @@ export {
   QLOO_PLAN_HELP,
   QLOO_PROFILE_DEFINITIONS,
   QLOO_PROJECT_CONTEXT_SCHEMA_VERSION,
+  QLOO_RESOLUTION_CHOICE_ENTRY_TYPE,
+  QLOO_RESOLUTION_CHOICE_SCHEMA_VERSION,
   QLOO_RESOLUTION_PROVIDER_ENVIRONMENT_VARIABLE,
   QLOO_SESSION_STATE_ENTRY_TYPE,
   QLOO_SESSION_STATE_SCHEMA_VERSION,
@@ -78,6 +81,7 @@ export {
   QLOO_UPDATE_SPEC_ENVIRONMENT_VARIABLE,
   QLOO_WORKSPACE_TOOL_NAMES,
   QlooIntegrationPlanError,
+  QlooResolutionMemory,
   QlooResolutionProviderError,
   QlooWorkflowExecutionError,
   TASTE_RESOLVER_API_KEY_ENVIRONMENT_VARIABLE,
@@ -89,6 +93,7 @@ export {
   buildExploreToolNames,
   buildHarnessResourceOptions,
   buildProfileToolNames,
+  clearResolutionChoicesEvent,
   createBuildHandoffPrompt,
   createCliQlooWorkflowExecutor,
   createDelegatingQlooWorkflowExecutor,
@@ -114,6 +119,7 @@ export {
   createTerminalSetupIO,
   ensureQlooStateDirectories,
   findGuidedGoal,
+  forgetResolutionChoiceEvent,
   formatDoctorReport,
   formatQlooResolutionCandidateLabels,
   formatQlooSetupReport,
@@ -133,10 +139,12 @@ export {
   parseQlooRawPage,
   probeTasteResolverHealth,
   qlooNextActions,
+  rememberResolutionChoicesEvent,
   renderQlooCallLines,
   renderQlooResultLines,
   requireAuthenticatedModel,
   resolutionCandidates,
+  resolutionInputContexts,
   resolveQlooPaths,
   runDoctor,
   runHarnessCli,

package/dist/integration-plan.js

@@ -211,12 +211,12 @@ var QLOO_LIMIT_SCHEMA = Type.Optional(Type.Integer({
 var QLOO_ENTITY_INPUTS_SCHEMA = Type.Array(Type.String({ minLength: 1 }), {
   minItems: 1,
   maxItems: 10,
-  description: "Entity names or Qloo entity UUIDs. Keep one combined taste profile in one call."
+  description: "Named entities or Qloo entity UUIDs; use tag fields for abstract concepts."
 });
 var QLOO_TAG_INPUTS_SCHEMA = Type.Array(Type.String({ minLength: 1 }), {
   minItems: 1,
   maxItems: 10,
-  description: "Natural-language tag concepts or stable Qloo tag URNs."
+  description: "Genres, moods, styles, traits, or other concepts, or Qloo tag URNs; not named entities."
 });
 var QLOO_DEMOGRAPHIC_SCHEMA = Type.String({
   minLength: 1,
@@ -376,6 +376,7 @@ var QLOO_WORKFLOW_METADATA = {
     promptSnippet: "Recommend entities from a combined Qloo taste profile",
     promptGuidelines: [
       "Pass every related taste and audience signal together in one qloo_recommend call.",
+      "Put named things in signals; put genres, moods, styles, traits, and concepts such as quiet luxury in signal_tags; reuse returned Qloo UUIDs and tag URNs.",
       "Use signal_location for audience location and filter_location to constrain result geography.",
       "Include demographic and location in the same call when both describe the audience."
     ],
@@ -386,7 +387,10 @@ var QLOO_WORKFLOW_METADATA = {
     label: "Qloo rank",
     description: "Rank one supplied option set against one shared entity, location, demographic, and tag profile. Scores from separate calls are not comparable.",
     promptSnippet: "Rank a caller-supplied shortlist with Qloo",
-    promptGuidelines: ["Pass every option in one qloo_rank call so scores remain comparable."],
+    promptGuidelines: [
+      "Pass every option in one qloo_rank call so scores remain comparable.",
+      "Put named things in entity fields and concepts in tag fields; reuse returned Qloo UUIDs and tag URNs."
+    ],
     documentation: ["https://docs.qloo.com/reference/insights-api-deep-dive"]
   },
   describe: {

package/dist/mcp.js

@@ -209,12 +209,12 @@ var QLOO_LIMIT_SCHEMA = Type.Optional(Type.Integer({
 var QLOO_ENTITY_INPUTS_SCHEMA = Type.Array(Type.String({ minLength: 1 }), {
   minItems: 1,
   maxItems: 10,
-  description: "Entity names or Qloo entity UUIDs. Keep one combined taste profile in one call."
+  description: "Named entities or Qloo entity UUIDs; use tag fields for abstract concepts."
 });
 var QLOO_TAG_INPUTS_SCHEMA = Type.Array(Type.String({ minLength: 1 }), {
   minItems: 1,
   maxItems: 10,
-  description: "Natural-language tag concepts or stable Qloo tag URNs."
+  description: "Genres, moods, styles, traits, or other concepts, or Qloo tag URNs; not named entities."
 });
 var QLOO_DEMOGRAPHIC_SCHEMA = Type.String({
   minLength: 1,
@@ -374,6 +374,7 @@ var QLOO_WORKFLOW_METADATA = {
     promptSnippet: "Recommend entities from a combined Qloo taste profile",
     promptGuidelines: [
       "Pass every related taste and audience signal together in one qloo_recommend call.",
+      "Put named things in signals; put genres, moods, styles, traits, and concepts such as quiet luxury in signal_tags; reuse returned Qloo UUIDs and tag URNs.",
       "Use signal_location for audience location and filter_location to constrain result geography.",
       "Include demographic and location in the same call when both describe the audience."
     ],
@@ -384,7 +385,10 @@ var QLOO_WORKFLOW_METADATA = {
     label: "Qloo rank",
     description: "Rank one supplied option set against one shared entity, location, demographic, and tag profile. Scores from separate calls are not comparable.",
     promptSnippet: "Rank a caller-supplied shortlist with Qloo",
-    promptGuidelines: ["Pass every option in one qloo_rank call so scores remain comparable."],
+    promptGuidelines: [
+      "Pass every option in one qloo_rank call so scores remain comparable.",
+      "Put named things in entity fields and concepts in tag fields; reuse returned Qloo UUIDs and tag URNs."
+    ],
     documentation: ["https://docs.qloo.com/reference/insights-api-deep-dive"]
   },
   describe: {