@pellux/goodvibes-agent 1.0.30 → 1.0.33

package/src/cli/agent-knowledge-command.ts

@@ -160,7 +160,7 @@ export async function handleAgentKnowledgeCommand(runtime: CliCommandRuntime): P
     const [id] = commandValues(rest);
     if (!id) return { output: 'Usage: goodvibes-agent knowledge get <source|node|issue id>', exitCode: 2 };
     const route = `/api/goodvibes-agent/knowledge/items/${encodeURIComponent(id)}`;
-    const result = await runKnowledgeCall(runtime, AGENT_KNOWLEDGE_METHODS.itemGet, async (connection) => (
+    const result = await runKnowledgeCall(runtime, { ...AGENT_KNOWLEDGE_METHODS.itemGet, route }, async (connection) => (
       await getAgentKnowledgeJson(connection, route)
     ));
     if (!result.ok) return { output: formatFailure(result, json), exitCode: 1 };
@@ -189,7 +189,7 @@ export async function handleAgentKnowledgeCommand(runtime: CliCommandRuntime): P
       const id = values[1];
       if (!id) return { output: 'Usage: goodvibes-agent knowledge connectors doctor <connectorId>', exitCode: 2 };
       const route = `/api/goodvibes-agent/knowledge/connectors/${encodeURIComponent(id)}/doctor`;
-      const result = await runKnowledgeCall(runtime, AGENT_KNOWLEDGE_METHODS.connectorDoctor, async (connection) => (
+      const result = await runKnowledgeCall(runtime, { ...AGENT_KNOWLEDGE_METHODS.connectorDoctor, route }, async (connection) => (
         await getAgentKnowledgeJson(connection, route)
       ));
       if (!result.ok) return { output: formatFailure(result, json), exitCode: 1 };
@@ -201,7 +201,7 @@ export async function handleAgentKnowledgeCommand(runtime: CliCommandRuntime): P
     const id = values[0];
     if (id) {
       const route = `/api/goodvibes-agent/knowledge/connectors/${encodeURIComponent(id)}`;
-      const result = await runKnowledgeCall(runtime, AGENT_KNOWLEDGE_METHODS.connectorGet, async (connection) => (
+      const result = await runKnowledgeCall(runtime, { ...AGENT_KNOWLEDGE_METHODS.connectorGet, route }, async (connection) => (
         await getAgentKnowledgeJson(connection, route)
       ));
       if (!result.ok) return { output: formatFailure(result, json), exitCode: 1 };
@@ -224,7 +224,7 @@ export async function handleAgentKnowledgeCommand(runtime: CliCommandRuntime): P
     const [id] = commandValues(rest);
     if (!id) return { output: 'Usage: goodvibes-agent knowledge connector <connectorId>', exitCode: 2 };
     const route = `/api/goodvibes-agent/knowledge/connectors/${encodeURIComponent(id)}`;
-    const result = await runKnowledgeCall(runtime, AGENT_KNOWLEDGE_METHODS.connectorGet, async (connection) => (
+    const result = await runKnowledgeCall(runtime, { ...AGENT_KNOWLEDGE_METHODS.connectorGet, route }, async (connection) => (
       await getAgentKnowledgeJson(connection, route)
     ));
     if (!result.ok) return { output: formatFailure(result, json), exitCode: 1 };
@@ -238,7 +238,7 @@ export async function handleAgentKnowledgeCommand(runtime: CliCommandRuntime): P
     const [id] = commandValues(rest);
     if (!id) return { output: 'Usage: goodvibes-agent knowledge connector-doctor <connectorId>', exitCode: 2 };
     const route = `/api/goodvibes-agent/knowledge/connectors/${encodeURIComponent(id)}/doctor`;
-    const result = await runKnowledgeCall(runtime, AGENT_KNOWLEDGE_METHODS.connectorDoctor, async (connection) => (
+    const result = await runKnowledgeCall(runtime, { ...AGENT_KNOWLEDGE_METHODS.connectorDoctor, route }, async (connection) => (
       await getAgentKnowledgeJson(connection, route)
     ));
     if (!result.ok) return { output: formatFailure(result, json), exitCode: 1 };

package/src/cli/agent-knowledge-format.ts

@@ -47,6 +47,7 @@ export function formatAgentKnowledgeFailureKind(kind: string): string {
   if (kind === 'connected_host_unavailable') return 'connected host unavailable';
   if (kind === 'connected_host_route_unavailable') return 'connected host route unavailable';
   if (kind === 'connected_host_error') return 'connected host error';
+  if (kind === 'scope_contamination') return 'scope contamination';
   if (kind === 'version_mismatch') return 'version mismatch';
   return kind.replace(/[_-]+/g, ' ');
 }
@@ -163,6 +164,7 @@ export function formatEntityList(data: unknown, kind: 'sources' | 'nodes' | 'iss
     ...values.slice(0, limit).map((value, index) => (
       kind === 'issues' ? format(value) : `  ${index + 1}. ${format(value)}`
     )),
+    `  route /api/goodvibes-agent/knowledge/${kind}`,
   ].join('\n');
 }
 
@@ -179,6 +181,7 @@ export function formatItem(data: unknown, id: string): string {
       `Agent Knowledge item ${id}`,
       `  ${sourceLine(source)}`,
       relatedKnowledgeCountsLine(relatedEdges, linkedSources, linkedNodes),
+      '  route /api/goodvibes-agent/knowledge/items/{id}',
     ].join('\n');
   }
   if (node) {
@@ -186,6 +189,7 @@ export function formatItem(data: unknown, id: string): string {
       `Agent Knowledge item ${id}`,
       `  ${nodeLine(node)}`,
       relatedKnowledgeCountsLine(relatedEdges, linkedSources, linkedNodes),
+      '  route /api/goodvibes-agent/knowledge/items/{id}',
     ].join('\n');
   }
   if (issue) {
@@ -193,6 +197,7 @@ export function formatItem(data: unknown, id: string): string {
       `Agent Knowledge item ${id}`,
       issueLine(issue),
       relatedKnowledgeCountsLine(relatedEdges, linkedSources, linkedNodes),
+      '  route /api/goodvibes-agent/knowledge/items/{id}',
     ].join('\n');
   }
   return [
@@ -231,6 +236,7 @@ export function formatConnectors(data: unknown): string {
   return [
     `Agent Knowledge connectors (${connectors.length})`,
     ...connectors.map(connectorLine),
+    '  route /api/goodvibes-agent/knowledge/connectors',
   ].join('\n');
 }
 
@@ -299,6 +305,7 @@ export function formatAsk(data: unknown, query: string): string {
   }
   if (facts.length > 0) lines.push('', `Facts ${facts.length}`);
   if (gaps.length > 0) lines.push('', `Gaps ${gaps.length}`);
+  lines.push('', 'route /api/goodvibes-agent/knowledge/ask');
   return lines.join('\n');
 }
 
@@ -316,6 +323,7 @@ export function formatSearch(data: unknown, query: string): string {
   return [
     `Agent Knowledge search ${query}`,
     ...results.slice(0, 10).map((result, index) => `  ${index + 1}. ${resultLine(result)}`),
+    '  route /api/goodvibes-agent/knowledge/search',
   ].join('\n');
 }
 
@@ -385,5 +393,8 @@ export function formatFailure(failure: AgentKnowledgeFailureLike, json: boolean)
     failure.kind === 'connected_host_route_unavailable'
       ? '  next update the connected GoodVibes host to the SDK version required by this Agent package.'
       : null,
+    failure.kind === 'scope_contamination'
+      ? '  next update the connected GoodVibes host so Agent Knowledge routes return only Agent-owned scope data.'
+      : null,
   ].filter((line): line is string => Boolean(line)).join('\n');
 }

package/src/cli/agent-knowledge-runtime.ts

@@ -1,8 +1,7 @@
-import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
 import { createBrowserAgentSdk } from '@pellux/goodvibes-sdk/browser/agent';
 import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
 import { SDK_VERSION, VERSION } from '../version.ts';
+import { readConnectedHostOperatorToken } from '../runtime/connected-host-auth.ts';
 import type { ConnectedHostCallMethod } from './agent-knowledge-methods.ts';
 
 export type JsonRecord = Record<string, unknown>;
@@ -22,7 +21,13 @@ export interface AgentKnowledgeConnectionRuntime {
 
 export interface AgentKnowledgeFailure {
   readonly ok: false;
-  readonly kind: 'connected_host_unavailable' | 'auth_required' | 'version_mismatch' | 'connected_host_route_unavailable' | 'connected_host_error';
+  readonly kind:
+    | 'connected_host_unavailable'
+    | 'auth_required'
+    | 'version_mismatch'
+    | 'connected_host_route_unavailable'
+    | 'connected_host_error'
+    | 'scope_contamination';
   readonly error: string;
   readonly baseUrl: string;
   readonly route: string;
@@ -56,15 +61,8 @@ export function resolveConnectedHostConnection(runtime: AgentKnowledgeConnection
   const host = String(runtime.configManager.get('controlPlane.host') ?? '127.0.0.1');
   const port = Number(runtime.configManager.get('controlPlane.port') ?? 3421);
   const baseUrl = `http://${host}:${Number.isFinite(port) ? port : 3421}`;
-  const tokenPath = join(runtime.homeDirectory, '.goodvibes', 'daemon', 'operator-tokens.json');
-  if (!existsSync(tokenPath)) return { baseUrl, token: null, tokenPath };
-  try {
-    const parsed = JSON.parse(readFileSync(tokenPath, 'utf-8')) as unknown;
-    const token = isRecord(parsed) && typeof parsed.token === 'string' ? parsed.token : null;
-    return { baseUrl, token, tokenPath };
-  } catch {
-    return { baseUrl, token: null, tokenPath };
-  }
+  const token = readConnectedHostOperatorToken(runtime.homeDirectory);
+  return { baseUrl, token: token.token, tokenPath: token.path };
 }
 
 export async function fetchConnectedHostStatus(connection: AgentKnowledgeConnection): Promise<{ readonly ok: boolean; readonly status: number; readonly body: unknown }> {
@@ -122,6 +120,87 @@ export function createAgentSdk(connection: AgentKnowledgeConnection) {
   });
 }
 
+const AGENT_KNOWLEDGE_SCOPE_KEYS = new Set(['spaceid', 'knowledgespaceid']);
+const AGENT_KNOWLEDGE_SCOPE_TEXT_PATTERNS: readonly { readonly label: string; readonly pattern: RegExp }[] = [
+  {
+    label: 'default knowledge scope id',
+    pattern: /["']?(?:knowledge[-_\s]*space[-_\s]*id|knowledgespaceid|space[-_\s]*id|spaceid)["']?\s*[:=]\s*["']?default["']?/i,
+  },
+  { label: 'host assistant payload marker', pattern: /home\s*assistant/i },
+  { label: 'host graph payload marker', pattern: /home\s*graph|homegraph/i },
+];
+
+function normalizedJsonKey(key: string): string {
+  return key.replace(/[-_\s]/g, '').toLowerCase();
+}
+
+function findAgentKnowledgeTextContamination(value: string): string | null {
+  for (const { label, pattern } of AGENT_KNOWLEDGE_SCOPE_TEXT_PATTERNS) {
+    if (pattern.test(value)) return label;
+  }
+  return null;
+}
+
+export function findAgentKnowledgeScopeContamination(value: unknown): string | null {
+  const seen = new WeakSet<object>();
+  const visit = (node: unknown): string | null => {
+    if (typeof node === 'string') return findAgentKnowledgeTextContamination(node);
+    if (!node || typeof node !== 'object') return null;
+    if (seen.has(node)) return null;
+    seen.add(node);
+    if (Array.isArray(node)) {
+      for (const item of node) {
+        const nested = visit(item);
+        if (nested) return nested;
+      }
+      return null;
+    }
+    for (const [key, nestedValue] of Object.entries(node as JsonRecord)) {
+      const keyFinding = findAgentKnowledgeTextContamination(key);
+      if (keyFinding && keyFinding !== 'default knowledge scope id') return keyFinding;
+      const normalizedKey = normalizedJsonKey(key);
+      if (
+        AGENT_KNOWLEDGE_SCOPE_KEYS.has(normalizedKey)
+        && typeof nestedValue === 'string'
+        && nestedValue.trim().toLowerCase() === 'default'
+      ) {
+        return `${key}=default`;
+      }
+      const nested = visit(nestedValue);
+      if (nested) return nested;
+    }
+    return null;
+  };
+  return visit(value);
+}
+
+export function agentKnowledgeScopeContaminationFailure(
+  connection: AgentKnowledgeConnection,
+  route: string,
+  finding: string,
+): AgentKnowledgeFailure {
+  return {
+    ok: false,
+    kind: 'scope_contamination',
+    error: [
+      `Agent Knowledge route returned non-Agent knowledge contamination (${finding}).`,
+      'GoodVibes Agent must use only isolated /api/goodvibes-agent/knowledge/* scope data.',
+    ].join(' '),
+    baseUrl: connection.baseUrl,
+    route,
+  };
+}
+
+export function validateAgentKnowledgeData<TData>(
+  data: TData,
+  connection: AgentKnowledgeConnection,
+  method: ConnectedHostCallMethod,
+): AgentKnowledgeResult<TData> {
+  const contamination = findAgentKnowledgeScopeContamination(data);
+  if (contamination) return agentKnowledgeScopeContaminationFailure(connection, method.route, contamination);
+  return { ok: true, kind: method.kind, route: method.route, data };
+}
+
 export async function postAgentKnowledgeJson<TData>(
   connection: AgentKnowledgeConnection,
   route: string,
@@ -239,7 +318,7 @@ export async function runKnowledgeCall<TData>(
   }
   try {
     const data = await call(connection);
-    return { ok: true, kind: method.kind, route: method.route, data };
+    return validateAgentKnowledgeData(data, connection, method);
   } catch (error) {
     return classifyKnowledgeError(error, connection, method.route);
   }

package/src/cli/bundle-command.ts

@@ -1,10 +1,11 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { dirname } from 'node:path';
 import { RuntimeEventBus } from '@/runtime/index.ts';
 import { createShellPathService } from '@/runtime/index.ts';
 import { listProviderRuntimeSnapshots } from '@pellux/goodvibes-sdk/platform/providers';
 import { createRuntimeServices } from '../runtime/services.ts';
 import { createRuntimeStore } from '../runtime/store/index.ts';
+import { readConnectedHostOperatorToken } from '../runtime/connected-host-auth.ts';
 import { getOnboardingCheckMarkerPath } from '../runtime/onboarding/index.ts';
 import { CONFIG_SCHEMA } from '../config/index.ts';
 import { SecretsManager } from '../config/secrets.ts';
@@ -76,14 +77,14 @@ function readAuthPosture(runtime: CliCommandRuntime) {
   });
   const userStorePath = shellPaths.resolveUserPath(GOODVIBES_AGENT_SURFACE_ROOT, 'auth-users.json');
   const bootstrapCredentialPath = shellPaths.resolveUserPath(GOODVIBES_AGENT_SURFACE_ROOT, 'auth-bootstrap.txt');
-  const operatorTokenPath = join(runtime.homeDirectory, '.goodvibes', 'daemon', 'operator-tokens.json');
+  const operatorToken = readConnectedHostOperatorToken(runtime.homeDirectory);
   return {
     userStorePath,
     userStorePresent: existsSync(userStorePath),
     bootstrapCredentialPath,
     bootstrapCredentialPresent: existsSync(bootstrapCredentialPath),
-    operatorTokenPath,
-    operatorTokenPresent: existsSync(operatorTokenPath),
+    operatorTokenPath: operatorToken.path,
+    operatorTokenPresent: operatorToken.present && Boolean(operatorToken.token),
   };
 }
 

package/src/cli/entrypoint.ts

@@ -186,6 +186,9 @@ export async function prepareShellCliRuntime(
       configManager,
       homeDirectory: bootstrapHomeDirectory,
     });
+    const effectiveOperatorTokenPath = externalRuntime.operatorToken.present
+      ? externalRuntime.operatorToken.path
+      : operatorTokenPath;
     const statusOptions = {
       configManager,
       workingDirectory: bootstrapWorkingDir,
@@ -196,8 +199,8 @@ export async function prepareShellCliRuntime(
         userStorePresent: existsSync(userStorePath),
         bootstrapCredentialPath,
         bootstrapCredentialPresent: existsSync(bootstrapCredentialPath),
-        operatorTokenPath,
-        operatorTokenPresent: existsSync(operatorTokenPath),
+        operatorTokenPath: effectiveOperatorTokenPath,
+        operatorTokenPresent: externalRuntime.operatorToken.present,
       },
       service,
       externalRuntime,

package/src/cli/external-runtime.ts

@@ -1,8 +1,7 @@
-import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
 import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
 import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
 import { SDK_VERSION } from '../version.ts';
+import { readConnectedHostOperatorToken } from '../runtime/connected-host-auth.ts';
 
 type JsonRecord = Record<string, unknown>;
 
@@ -47,18 +46,6 @@ function resolveBaseUrl(configManager: Pick<ConfigManager, 'get'>): string {
   return `http://${host}:${Number.isFinite(port) ? port : 3421}`;
 }
 
-function readOperatorToken(homeDirectory: string): { readonly token: string | null; readonly path: string } {
-  const path = join(homeDirectory, '.goodvibes', 'daemon', 'operator-tokens.json');
-  if (!existsSync(path)) return { token: null, path };
-  try {
-    const parsed = JSON.parse(readFileSync(path, 'utf-8')) as unknown;
-    const token = isRecord(parsed) && typeof parsed.token === 'string' ? parsed.token : null;
-    return { token, path };
-  } catch {
-    return { token: null, path };
-  }
-}
-
 async function fetchJson(
   url: string,
   token: string | null,
@@ -90,7 +77,7 @@ export async function inspectCliExternalRuntime(
   options: CliExternalRuntimeInspectionOptions,
 ): Promise<CliExternalRuntimeSnapshot> {
   const baseUrl = resolveBaseUrl(options.configManager);
-  const token = readOperatorToken(options.homeDirectory);
+  const token = readConnectedHostOperatorToken(options.homeDirectory);
   const timeoutMs = options.timeoutMs ?? 1500;
   const route = '/api/goodvibes-agent/knowledge/status' as const;
 

package/src/cli/management.ts

@@ -9,6 +9,7 @@ import { formatProviderModel, getModelIdFromProviderModel } from '../config/prov
 import { bootstrapRuntime } from '../runtime/bootstrap.ts';
 import { createRuntimeServices } from '../runtime/services.ts';
 import { createRuntimeStore } from '../runtime/store/index.ts';
+import { readConnectedHostOperatorToken } from '../runtime/connected-host-auth.ts';
 import type { RuntimeServices } from '../runtime/services.ts';
 import { SecretsManager } from '../config/secrets.ts';
 import { RuntimeEventBus, type TurnEvent } from '@/runtime/index.ts';
@@ -190,14 +191,14 @@ export function readAuthPaths(runtime: CliCommandRuntime) {
   });
   const userStorePath = shellPaths.resolveUserPath(GOODVIBES_AGENT_SURFACE_ROOT, 'auth-users.json');
   const bootstrapCredentialPath = shellPaths.resolveUserPath(GOODVIBES_AGENT_SURFACE_ROOT, 'auth-bootstrap.txt');
-  const operatorTokenPath = join(runtime.homeDirectory, '.goodvibes', 'daemon', 'operator-tokens.json');
+  const operatorToken = readConnectedHostOperatorToken(runtime.homeDirectory);
   return {
     userStorePath,
     userStorePresent: existsSync(userStorePath),
     bootstrapCredentialPath,
     bootstrapCredentialPresent: existsSync(bootstrapCredentialPath),
-    operatorTokenPath,
-    operatorTokenPresent: existsSync(operatorTokenPath),
+    operatorTokenPath: operatorToken.path,
+    operatorTokenPresent: operatorToken.present && Boolean(operatorToken.token),
   };
 }
 

package/src/input/commands/guidance-runtime.ts

@@ -21,7 +21,7 @@ export function registerGuidanceRuntimeCommands(registry: CommandRegistry): void
           'Welcome To GoodVibes Agent',
           '  /setup              - open Agent setup with current settings preloaded',
           '  /agent              - open the Agent operator workspace',
-          '  /knowledge          - inspect isolated Agent Knowledge status, ask, and search',
+          '  /knowledge          - inspect isolated Agent Knowledge status, ask/search, libraries, map, connectors, and ingest paths',
           '  /memory             - manage Agent-local memory',
           '  /personas           - manage Agent-local personas',
           '  /skills       - manage reusable Agent-local skills',

package/src/input/commands/knowledge.ts

@@ -209,9 +209,9 @@ function renderKnowledgeAskResult(result: KnowledgeAskResult): string {
 export const knowledgeCommand: SlashCommand = {
   name: 'knowledge',
   aliases: ['know', 'kb'],
-  description: 'Agent Knowledge: isolated Agent-owned sources, graph, review queue, and compact prompt packets.',
+  description: 'Agent Knowledge: isolated Agent-owned status, ask/search, source/node/issue lists, item lookup, map, connectors, ingest, and review queue.',
   usage: '<subcommand> [args]',
-  argsHint: 'status|ask|ingest-url --yes|ingest-file --yes|import-bookmarks --yes|list|search|get|queue|review-issue --yes',
+  argsHint: 'status|ask|search|list|get|map|connectors|connector|connector-doctor|ingest-url --yes|ingest-file --yes|import-urls --yes|import-bookmarks --yes|import-browser-history --yes|ingest-connector --yes|review-issue --yes|reindex --yes',
   handler: async (args: string[], context: CommandContext): Promise<void> => {
     if (args.length === 0 && context.openAgentWorkspace) {
       context.openAgentWorkspace('knowledge');

package/src/runtime/bootstrap.ts

@@ -51,8 +51,8 @@ const GOODVIBES_AGENT_OPERATOR_POLICY = [
   '- Use the `agent_operator_briefing` tool for read-only main-conversation summaries of connected work plan, approvals, automation, schedules, and scheduler capacity. This tool must not call mutation routes, connected-host lifecycle routes, default knowledge, non-Agent knowledge spaces, separate Agent job creation, or GoodVibes TUI delegation.',
   '- When the user explicitly asks Agent to approve, deny, or cancel a specific approval, run/pause/resume a specific automation job, cancel/retry a specific automation run, or run a specific schedule, use the `agent_operator_action` tool with confirm:true and the original user request. It can call only its allowlisted public operator routes and must not create, edit, delete, or discover automation definitions.',
   '- Use the `agent_work_plan` tool to keep the visible Agent-local work plan current while working in the main conversation. Create, inspect, and update local work items proactively when useful. Removing items or clearing completed items requires an explicit user request and confirm:true.',
-  '- Use the `agent_harness` tool to inspect and operate the harness surface itself: Agent workspace action catalog, slash command catalog, model tool catalog, connected-host posture, and Agent settings. Use it to change Agent settings, invoke workspace action mirrors, or invoke slash-command mirrors only when the user explicitly asks; preserve confirm:true and explicitUserRequest for mutations, keep secret-backed settings in the secret manager, and keep connected-host lifecycle/posture externally owned.',
-  '- Use the `agent_knowledge` tool for Agent Knowledge status, ask, and search from the main conversation. It must use only /api/goodvibes-agent/knowledge/* and must fail closed instead of falling back to default knowledge or non-Agent knowledge spaces.',
+  '- Use the `agent_harness` tool to inspect and operate the harness surface itself: Agent workspace action catalog, slash command catalog, model tool catalog, release evidence bundle, release readiness inventory, connected-host posture, and Agent settings. Use it to change Agent settings, invoke workspace action mirrors, or invoke slash-command mirrors only when the user explicitly asks; preserve confirm:true and explicitUserRequest for mutations, keep secret-backed settings in the secret manager, and keep connected-host lifecycle/posture externally owned.',
+  '- Use the `agent_knowledge` tool for Agent Knowledge status, ask, search, source/node/issue lists, item lookup, map summary, connector list/detail, and connector doctor from the main conversation. It must use only /api/goodvibes-agent/knowledge/* and must fail closed instead of falling back to default knowledge or non-Agent knowledge spaces.',
   '- When the user explicitly asks Agent to add, import, remember, or ingest a URL, URL-list file, local file, bookmarks file, browser history, or connector input into Agent Knowledge, use the `agent_knowledge_ingest` tool with confirm:true and the original user request. It must write only to /api/goodvibes-agent/knowledge/* ingest routes and never to default knowledge or non-Agent knowledge spaces.',
   '- Use the `agent_local_registry` tool when a scratchpad note, durable memory, reusable persona, skill, skill bundle, or routine would improve later work. Keep those records Agent-local, non-secret, source/provenance tagged, and reviewable. Notes are for temporary/source-triage context; promote them explicitly into memory, skills, personas, routines, or Agent Knowledge only when that is the correct durable home. Review memory with a confidence score when it should shape later turns. Starting a routine means applying its steps in this same serial conversation, not creating a background job.',
   '- When the user explicitly asks Agent to generate an image, video, or other media artifact, use the `agent_media_generate` tool with confirm:true and the original user request. Generated media is stored as artifacts; do not print base64, call default knowledge, use non-Agent knowledge spaces, send channels, create separate Agent jobs, or request GoodVibes TUI delegation for media generation.',

package/src/runtime/connected-host-auth.ts

@@ -20,6 +20,22 @@ export function connectedHostOperatorTokenPath(homeDirectory: string): string {
 }
 
 export function readConnectedHostOperatorToken(homeDirectory: string): ConnectedHostOperatorToken {
+  const connectedHostEnvToken = process.env.GOODVIBES_CONNECTED_HOST_TOKEN?.trim();
+  if (connectedHostEnvToken) {
+    return {
+      path: 'env:GOODVIBES_CONNECTED_HOST_TOKEN',
+      present: true,
+      token: connectedHostEnvToken,
+    };
+  }
+  const legacyEnvToken = process.env.GOODVIBES_DAEMON_TOKEN?.trim();
+  if (legacyEnvToken) {
+    return {
+      path: 'env:GOODVIBES_DAEMON_TOKEN',
+      present: true,
+      token: legacyEnvToken,
+    };
+  }
   const path = connectedHostOperatorTokenPath(homeDirectory);
   if (!existsSync(path)) return { path, present: false, token: null };
   try {

package/src/tools/agent-channel-send-tool.ts

@@ -42,11 +42,9 @@ export function createAgentChannelSendTool(
     definition: {
       name: 'agent_channel_send',
       description: [
-        'Send one explicitly confirmed message through a configured GoodVibes Agent delivery target from the main conversation.',
-        'Use only when the user explicitly asks Agent to send, message, alert, or notify a channel target.',
-        'Exactly one target must be supplied: channel, route, webhook, or link.',
-        'This tool does not create channel routes, authorize accounts, manage connected-host hosting, use default knowledge, use non-Agent knowledge segments, create separate Agent jobs, run delegated review, or invoke arbitrary routes.',
-        'Set confirm:true only for an explicit user request. Otherwise return the preview/confirmation error.',
+        'Send one confirmed message through a configured Agent target.',
+        'Use only for explicit send/message/alert requests.',
+        'Provide exactly one target.',
       ].join(' '),
       parameters: {
         type: 'object',
@@ -61,7 +59,7 @@ export function createAgentChannelSendTool(
           },
           channel: {
             type: 'string',
-            description: 'Optional channel target surface[:route[:label]], such as slack:ops:Ops or telephony:+15551234567. Use exactly one target field.',
+            description: 'Optional channel target. Use exactly one target field.',
           },
           route: {
             type: 'string',
@@ -77,7 +75,7 @@ export function createAgentChannelSendTool(
           },
           confirm: {
             type: 'boolean',
-            description: 'Required true only when the user explicitly asked for this exact channel delivery.',
+            description: 'Required true for confirmed delivery.',
           },
           explicitUserRequest: {
             type: 'string',

package/src/tools/agent-harness-channel-metadata.ts

@@ -0,0 +1,177 @@
+import type { CommandContext } from '../input/command-registry.ts';
+import type { AgentWorkspaceChannelStatus } from '../input/agent-workspace-channels.ts';
+import { buildAgentWorkspaceChannels } from '../input/agent-workspace-channels.ts';
+
+export interface AgentHarnessChannelArgs {
+  readonly channelId?: unknown;
+  readonly target?: unknown;
+  readonly query?: unknown;
+  readonly includeParameters?: unknown;
+  readonly limit?: unknown;
+}
+
+type ChannelLookupSource = 'channelId' | 'target' | 'query';
+
+type ChannelResolution =
+  | { readonly status: 'found'; readonly channel: Record<string, unknown> }
+  | { readonly status: 'ambiguous'; readonly input: string; readonly candidates: readonly Record<string, unknown>[] }
+  | { readonly status: 'missing_lookup'; readonly usage: string };
+
+function readString(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function readLimit(value: unknown, fallback: number): number {
+  const parsed = typeof value === 'string' && value.trim() ? Number(value) : value;
+  if (typeof parsed !== 'number' || !Number.isFinite(parsed)) return fallback;
+  return Math.max(1, Math.min(500, Math.trunc(parsed)));
+}
+
+function channelLookupFromArgs(args: AgentHarnessChannelArgs): { readonly source: ChannelLookupSource; readonly input: string } | null {
+  const channelId = readString(args.channelId);
+  if (channelId) return { source: 'channelId', input: channelId };
+  const target = readString(args.target);
+  if (target) return { source: 'target', input: target };
+  const query = readString(args.query);
+  return query ? { source: 'query', input: query } : null;
+}
+
+function channelSearchText(channel: AgentWorkspaceChannelStatus): string {
+  return [
+    channel.id,
+    channel.label,
+    channel.delivery,
+    channel.risk,
+    channel.riskLabel,
+    channel.setupState,
+    channel.nextStep,
+    ...channel.requiredKeys,
+    ...channel.missingRequiredKeys,
+    ...channel.defaultTargetKeys,
+    ...channel.configuredDefaultTargetKeys,
+  ].join('\n').toLowerCase();
+}
+
+function describeChannelCandidate(channel: AgentWorkspaceChannelStatus): Record<string, unknown> {
+  return {
+    channelId: channel.id,
+    label: channel.label,
+    setupState: channel.setupState,
+    ready: channel.ready,
+    delivery: channel.delivery,
+  };
+}
+
+function describeChannel(
+  channel: AgentWorkspaceChannelStatus,
+  options: { readonly includeParameters?: boolean; readonly lookup?: Record<string, unknown> } = {},
+): Record<string, unknown> {
+  return {
+    id: channel.id,
+    label: channel.label,
+    enabled: channel.enabled,
+    ready: channel.ready,
+    setupState: channel.setupState,
+    delivery: channel.delivery,
+    risk: channel.risk,
+    riskLabel: channel.riskLabel,
+    missingConfigCount: channel.missingConfigCount,
+    defaultTarget: channel.defaultTarget,
+    nextStep: channel.nextStep,
+    requiredConfigKeys: channel.requiredKeys,
+    missingConfigKeys: channel.missingRequiredKeys,
+    defaultTargetKeys: channel.defaultTargetKeys,
+    configuredDefaultTargetKeys: channel.configuredDefaultTargetKeys,
+    ...(options.lookup ? { lookup: options.lookup } : {}),
+    policy: {
+      effect: 'read-only',
+      values: 'Config key names and target key names are shown; secret values and stored target values are never returned.',
+      delivery: 'Use agent_channel_send only for one explicit, confirmed delivery target requested by the user.',
+      setup: 'Use connected-host setup/account/policy routes only as read-only diagnostics unless another confirmed first-class tool owns the mutation.',
+    },
+    modelAccess: {
+      sendTool: 'agent_channel_send',
+      notificationTool: 'agent_notify',
+      reminderTool: 'agent_reminder_schedule',
+      slashCommandDetail: `/channels show ${channel.id}`,
+      readOnlyConnectedRoutes: [
+        '/channels accounts',
+        '/channels policies',
+        '/channels status',
+        `/channels doctor ${channel.id}`,
+        `/channels setup ${channel.id}`,
+      ],
+      settingsFilter: `agent_harness mode:"settings" prefix:"surfaces.${channel.id}" includeHidden:true`,
+      connectedHostBoundary: 'agent_harness mode:"connected_host_capability" query:"delivery"',
+      ...(options.includeParameters ? {
+        deliveryTargetShape: 'surface[:route[:label]]',
+        exampleTarget: `${channel.id}:route:Label`,
+      } : {}),
+    },
+  };
+}
+
+export function channelReadinessCatalogStatus(context: CommandContext): Record<string, unknown> {
+  const channels = buildAgentWorkspaceChannels(context);
+  return {
+    modes: ['channels', 'channel'],
+    channels: channels.length,
+    enabled: channels.filter((channel) => channel.enabled).length,
+    ready: channels.filter((channel) => channel.ready).length,
+    attention: channels.filter((channel) => channel.enabled && channel.setupState !== 'ready').length,
+    readOnly: true,
+    deliveryTool: 'agent_channel_send',
+  };
+}
+
+export function listHarnessChannels(context: CommandContext, args: AgentHarnessChannelArgs): Record<string, unknown> {
+  const query = readString(args.query).toLowerCase();
+  const includeParameters = args.includeParameters === true;
+  const limit = readLimit(args.limit, 200);
+  const channels = buildAgentWorkspaceChannels(context);
+  const filtered = channels
+    .filter((channel) => !query || channelSearchText(channel).includes(query))
+    .slice(0, limit);
+  return {
+    channels: filtered.map((channel) => describeChannel(channel, { includeParameters })),
+    returned: filtered.length,
+    total: channels.length,
+    enabled: channels.filter((channel) => channel.enabled).length,
+    ready: channels.filter((channel) => channel.ready).length,
+    attention: channels.filter((channel) => channel.enabled && channel.setupState !== 'ready').length,
+    policy: 'Read-only channel readiness catalog. It returns key names, setup state, delivery posture, and model routes without printing secrets or sending messages.',
+  };
+}
+
+export function describeHarnessChannel(context: CommandContext, args: AgentHarnessChannelArgs): ChannelResolution {
+  const lookup = channelLookupFromArgs(args);
+  if (!lookup) {
+    return {
+      status: 'missing_lookup',
+      usage: 'channel requires channelId, target, or query. Use mode:"channels" to inspect available channel ids.',
+    };
+  }
+  const channels = buildAgentWorkspaceChannels(context);
+  const normalized = lookup.input.toLowerCase();
+  const exact = channels.find((channel) => channel.id === lookup.input);
+  if (exact) return { status: 'found', channel: describeChannel(exact, { includeParameters: true, lookup: { ...lookup, resolvedBy: 'id' } }) };
+  const insensitiveId = channels.find((channel) => channel.id.toLowerCase() === normalized);
+  if (insensitiveId) return { status: 'found', channel: describeChannel(insensitiveId, { includeParameters: true, lookup: { ...lookup, resolvedBy: 'case-insensitive-id' } }) };
+  const insensitiveLabel = channels.find((channel) => channel.label.toLowerCase() === normalized);
+  if (insensitiveLabel) return { status: 'found', channel: describeChannel(insensitiveLabel, { includeParameters: true, lookup: { ...lookup, resolvedBy: 'case-insensitive-label' } }) };
+  const searched = channels.filter((channel) => channelSearchText(channel).includes(normalized));
+  if (searched.length === 1) {
+    return { status: 'found', channel: describeChannel(searched[0]!, { includeParameters: true, lookup: { ...lookup, resolvedBy: 'search' } }) };
+  }
+  if (searched.length > 1) {
+    return {
+      status: 'ambiguous',
+      input: lookup.input,
+      candidates: searched.slice(0, 8).map(describeChannelCandidate),
+    };
+  }
+  return {
+    status: 'missing_lookup',
+    usage: `Unknown channel ${lookup.input}. Use mode:"channels" to inspect available channel ids.`,
+  };
+}