@vibesdotdev/session 0.0.0-stage → 1.0.0-rc.2

package/dist/mcp/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/mcp/types.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,YAAY,EACX,eAAe,EAAE,aAAa,EAAE,kBAAkB,EAAE,OAAO,EAC3D,eAAe,EAAE,gBAAgB,EAAE,aAAa,EAAE,cAAc,EAChE,MAAM,mBAAmB,CAAC"}

package/dist/mcp/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/mcp/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/mcp/types.ts"],"names":[],"mappings":""}

package/dist/mcp/utils/coordination.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Coordination helpers for multi-participant workflows.
+ */
+export type { CoordinationScenario, CoordinationPrompt, CoordinationCommand, CoordinationDocRef } from '../schemas/coordination.ts';
+import type { CoordinationDocRef } from '../schemas/coordination.ts';
+export declare const RECOMMENDED_TOOL_GROUPS: {
+    readonly planning: readonly ["session-todo", "session-scratchpad"];
+    readonly coordination: readonly ["session-collaborate", "session-todo"];
+    readonly tracking: readonly ["session-todo"];
+    readonly context: readonly ["session"];
+    readonly knowledge: readonly ["knowledge"];
+};
+export declare const COORDINATION_TIPS: readonly ["Share the full session boilerplate, current TODO tree, and scratchpad keys before collaborators begin.", "Coordinate by pairing `session-collaborate` (action: send --toParticipant) with `session-todo` (action: update --assignedParticipant) — there is no separate coordinate tool.", "Assign tasks with `session-todo` (action: update) so ownership stays explicit and reversible.", "Capture interim findings in `session-scratchpad` (action: write) before transferring responsibility to another participant.", "Before handoff, use `knowledge` (action: create) to preserve reusable discoveries (facts, examples, instructions) for future contributors."];
+export declare const COORDINATION_DOCS: CoordinationDocRef[];
+export declare function buildInvitePrompt(sessionId: string, title: string, invitingSlug: string): string;
+export declare function buildHandoffPrompt(sessionId: string, invitingSlug: string): string;
+//# sourceMappingURL=coordination.d.ts.map

package/dist/mcp/utils/coordination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coordination.d.ts","sourceRoot":"","sources":["../../../src/mcp/utils/coordination.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,YAAY,EACX,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAErE,eAAO,MAAM,uBAAuB;;;;;;CAM1B,CAAC;AAEX,eAAO,MAAM,iBAAiB,opBAMpB,CAAC;AAEX,eAAO,MAAM,iBAAiB,EAAE,kBAAkB,EAgBjD,CAAC;AAEF,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAShG;AAED,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAUlF"}

package/dist/mcp/utils/coordination.js

@@ -0,0 +1,56 @@
+/**
+ * Coordination helpers for multi-participant workflows.
+ */
+export const RECOMMENDED_TOOL_GROUPS = {
+    planning: ['session-todo', 'session-scratchpad'],
+    coordination: ['session-collaborate', 'session-todo'],
+    tracking: ['session-todo'],
+    context: ['session'],
+    knowledge: ['knowledge']
+};
+export const COORDINATION_TIPS = [
+    'Share the full session boilerplate, current TODO tree, and scratchpad keys before collaborators begin.',
+    'Coordinate by pairing `session-collaborate` (action: send --toParticipant) with `session-todo` (action: update --assignedParticipant) — there is no separate coordinate tool.',
+    'Assign tasks with `session-todo` (action: update) so ownership stays explicit and reversible.',
+    'Capture interim findings in `session-scratchpad` (action: write) before transferring responsibility to another participant.',
+    'Before handoff, use `knowledge` (action: create) to preserve reusable discoveries (facts, examples, instructions) for future contributors.'
+];
+export const COORDINATION_DOCS = [
+    {
+        title: 'Rules Summary',
+        path: 'docs/rules/summary.md',
+        summary: 'Generated checklist of active engineering rules.'
+    },
+    {
+        title: 'Development Cheatsheet',
+        path: 'docs/development/cheatsheet.md',
+        summary: 'Feature topology, schema-first workflow, and coordination guidance.'
+    },
+    {
+        title: 'Session Management Overview',
+        path: 'session/README.md',
+        summary: 'Session tooling reference including MCP, CLI, and collaboration workflows.'
+    }
+];
+export function buildInvitePrompt(sessionId, title, invitingSlug) {
+    return [
+        `You are joining workspace session "${title}" (${sessionId}) as a collaborating participant invited by ${invitingSlug}.`,
+        `1. Attach to THIS session: \`session\` (action: status, sessionId: "${sessionId}"). Do NOT run action: init — init forks a new session; passing the sessionId binds you to the shared one.`,
+        `2. Restate rules (cite ${invitingSlug}) and confirm the active session.`,
+        '3. Review TODOs via `session-todo` (action: list) and claim ownership with `session-todo` (action: update).',
+        '4. Announce your plan using `session-collaborate` (action: send) before executing.',
+        '5. Document progress in the scratchpad and send a status update when complete.'
+    ].join('\n');
+}
+export function buildHandoffPrompt(sessionId, invitingSlug) {
+    return [
+        `Handing off from ${invitingSlug} in session ${sessionId}.`,
+        '- Context accomplished so far: <summaries or links>',
+        '- TODOs reassigned: `session-todo` (action: update) with assignedParticipant <receiver-slug>',
+        '- Scratchpad entries to review: <keys or titles>',
+        '- Knowledge contributed: <items added via knowledge (action: create), or "none yet">',
+        '- Expected next steps: <bulleted list>',
+        'Send `session-collaborate` (action: send, messageType: request) when you pick this up and confirm timing.'
+    ].join('\n');
+}
+//# sourceMappingURL=coordination.js.map

package/dist/mcp/utils/coordination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coordination.js","sourceRoot":"","sources":["../../../src/mcp/utils/coordination.ts"],"names":[],"mappings":"AAAA;;GAEG;AAWH,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACtC,QAAQ,EAAE,CAAC,cAAc,EAAE,oBAAoB,CAAC;IAChD,YAAY,EAAE,CAAC,qBAAqB,EAAE,cAAc,CAAC;IACrD,QAAQ,EAAE,CAAC,cAAc,CAAC;IAC1B,OAAO,EAAE,CAAC,SAAS,CAAC;IACpB,SAAS,EAAE,CAAC,WAAW,CAAC;CACf,CAAC;AAEX,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAChC,wGAAwG;IACxG,+KAA+K;IAC/K,+FAA+F;IAC/F,6HAA6H;IAC7H,4IAA4I;CACnI,CAAC;AAEX,MAAM,CAAC,MAAM,iBAAiB,GAAyB;IACtD;QACC,KAAK,EAAE,eAAe;QACtB,IAAI,EAAE,uBAAuB;QAC7B,OAAO,EAAE,kDAAkD;KAC3D;IACD;QACC,KAAK,EAAE,wBAAwB;QAC/B,IAAI,EAAE,gCAAgC;QACtC,OAAO,EAAE,qEAAqE;KAC9E;IACD;QACC,KAAK,EAAE,6BAA6B;QACpC,IAAI,EAAE,mBAAmB;QACzB,OAAO,EAAE,4EAA4E;KACrF;CACD,CAAC;AAEF,MAAM,UAAU,iBAAiB,CAAC,SAAiB,EAAE,KAAa,EAAE,YAAoB;IACvF,OAAO;QACN,sCAAsC,KAAK,MAAM,SAAS,+CAA+C,YAAY,GAAG;QACxH,uEAAuE,SAAS,4GAA4G;QAC5L,0BAA0B,YAAY,mCAAmC;QACzE,6GAA6G;QAC7G,oFAAoF;QACpF,gFAAgF;KAChF,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACd,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,SAAiB,EAAE,YAAoB;IACzE,OAAO;QACN,oBAAoB,YAAY,eAAe,SAAS,GAAG;QAC3D,qDAAqD;QACrD,8FAA8F;QAC9F,kDAAkD;QAClD,sFAAsF;QACtF,wCAAwC;QACxC,2GAA2G;KAC3G,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACd,CAAC"}

package/dist/mcp/utils/knowledge.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Knowledge context utilities for session-init (injury L-06).
+ *
+ * Pre-fix this module had a divergent, dead resolution path: its ONLY
+ * discovery lane was an HTTP GET against `/api/knowledge/bases` — a route
+ * shape that does not exist anywhere — its config lane was a stub service
+ * that always returned null, and a non-UUID project id (e.g. the atlas
+ * basename 'repository-collection') gated the whole thing into a FALSE 'offline' state.
+ *
+ * Now the knowledge-base discovery resolves through the SAME implementation
+ * the `knowledge` tool serves (ONE path — @vibesdotdev/knowledge's canonical
+ * semantic client, identity-scoped exactly like
+ * items/bases reads). State names are honest:
+ *  - 'explicit'  — caller-provided knowledgeBaseIds
+ *  - 'discovery' — bases found through the knowledge store
+ *  - 'none'      — discovery ran and found nothing
+ *  - 'disabled'  — caller set useKnowledgeApi: false
+ *  - 'project-binding' — project-owned role bindings from platform-web
+ * There is no 'offline': the local store does not need a network, and a
+ * missing project binding is represented by its own readiness snapshot.
+ *
+ * Binding policy (project-bound sessions):
+ *  - 'optional' (default) — bindings win only when ALL three roles are bound
+ *    ('ready'). While the binding is degraded/missing (including reads the
+ *    runtime cannot perform: local-only networking, provider absent, read
+ *    failed), resolution FALLS BACK to the prior explicit → project-ref →
+ *    discovery chain so adopting the binding table never empties a session's
+ *    knowledge context. The honest binding snapshot is persisted either way,
+ *    with a `reason` that distinguishes truly-unbound ('no-roles-bound') from
+ *    an unperformable read ('local-only-networking', 'binding-read-failed',
+ *    'binding-provider-unavailable').
+ *  - 'required' — init fails unless the binding is 'ready'. Local-only
+ *    networking cannot verify bindings, so required + local-only fails too.
+ * The binding read is a REMOTE lane and is skipped under local-only
+ * networking, exactly like project resolution; local discovery never is.
+ */
+import { CapabilityError, type ValueFreeFailure, type VibesRuntime } from '@vibesdotdev/kernel';
+import type { SessionManager } from '../../manager/index.ts';
+import type { Session } from '../../schemas/index.ts';
+import type { SessionInitInput } from '../schemas/tools.ts';
+import type { McpToolContext } from '../types.ts';
+export declare const PROJECT_KNOWLEDGE_BINDING_ROLES: readonly ["dependencies", "rules", "codebase"];
+export type ProjectKnowledgeBindingRole = (typeof PROJECT_KNOWLEDGE_BINDING_ROLES)[number];
+export type KnowledgeBindingPolicy = 'required' | 'optional';
+export type KnowledgeBindingState = 'ready' | 'degraded' | 'missing';
+export type KnowledgeContextSource = 'explicit' | 'project-ref' | 'project-binding' | 'discovery' | 'none' | 'disabled';
+export interface KnowledgeBindingSnapshot {
+    projectId?: string;
+    state: KnowledgeBindingState;
+    policy: KnowledgeBindingPolicy;
+    roles: Partial<Record<ProjectKnowledgeBindingRole, string>>;
+    missingRoles: ProjectKnowledgeBindingRole[];
+    source: 'project-binding' | 'unbound' | 'disabled';
+    reason?: string;
+    /** Why a performable read failed (`binding-read-failed`, `binding-provider-failed`): value-free facts only. */
+    failure?: ValueFreeFailure;
+}
+type KnowledgeContextResolution = {
+    projectId?: string;
+    knowledgeBaseIds: string[];
+    missingKnowledgeBases: string[];
+    source: KnowledgeContextSource;
+    knowledgeBinding: KnowledgeBindingSnapshot;
+    workspacePath?: string;
+    /** Local knowledge-base discovery failed: carried value-free, never reported as 'none' silently. */
+    discoveryFailure?: ValueFreeFailure;
+};
+type SessionMetadata = Session['metadata'];
+/**
+ * A `required` binding policy refused: the project binding is not `ready`.
+ * Typed `PERMISSION_DENIED knowledge-binding-required`; `details` carries the
+ * value-free snapshot facts (project id, state, missing roles).
+ */
+export declare function knowledgeBindingRequired(snapshot: KnowledgeBindingSnapshot): CapabilityError;
+interface ApplyKnowledgeContextOptions {
+    workspacePath?: string;
+    projectIdOverride?: string;
+    knowledgeBaseIdsOverride?: string[];
+    /** The runtime the caller was handed. */
+    runtime: VibesRuntime;
+}
+export declare function applyKnowledgeContext(context: McpToolContext, sessionManager: SessionManager, sessionId: string, args: SessionInitInput, options: ApplyKnowledgeContextOptions): Promise<KnowledgeContextResolution & {
+    metadata: SessionMetadata;
+    knowledgeApiEnabled: boolean;
+    workspacePath?: string;
+    /** Project resolution over the API failed; init continued with the raw identifier. */
+    projectResolutionFailure?: ValueFreeFailure;
+}>;
+export {};
+//# sourceMappingURL=knowledge.d.ts.map

package/dist/mcp/utils/knowledge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge.d.ts","sourceRoot":"","sources":["../../../src/mcp/utils/knowledge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAGH,OAAO,EACN,eAAe,EAGf,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,KAAK,EAAE,OAAO,EAAiB,MAAM,wBAAwB,CAAC;AACrE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,KAAK,EAAiB,cAAc,EAAE,MAAM,aAAa,CAAC;AASjE,eAAO,MAAM,+BAA+B,gDAAiD,CAAC;AAE9F,MAAM,MAAM,2BAA2B,GAAG,CAAC,OAAO,+BAA+B,CAAC,CAAC,MAAM,CAAC,CAAC;AAC3F,MAAM,MAAM,sBAAsB,GAAG,UAAU,GAAG,UAAU,CAAC;AAC7D,MAAM,MAAM,qBAAqB,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,CAAC;AACrE,MAAM,MAAM,sBAAsB,GACjC,UAAU,GAAG,aAAa,GAAG,iBAAiB,GAAG,WAAW,GAAG,MAAM,GAAG,UAAU,CAAC;AAEpF,MAAM,WAAW,wBAAwB;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,qBAAqB,CAAC;IAC7B,MAAM,EAAE,sBAAsB,CAAC;IAC/B,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,2BAA2B,EAAE,MAAM,CAAC,CAAC,CAAC;IAC5D,YAAY,EAAE,2BAA2B,EAAE,CAAC;IAC5C,MAAM,EAAE,iBAAiB,GAAG,SAAS,GAAG,UAAU,CAAC;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+GAA+G;IAC/G,OAAO,CAAC,EAAE,gBAAgB,CAAC;CAC3B;AAQD,KAAK,0BAA0B,GAAG;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,qBAAqB,EAAE,MAAM,EAAE,CAAC;IAChC,MAAM,EAAE,sBAAsB,CAAC;IAC/B,gBAAgB,EAAE,wBAAwB,CAAC;IAC3C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,oGAAoG;IACpG,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CACpC,CAAC;AAEF,KAAK,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;AAwS3C;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,wBAAwB,GAAG,eAAe,CAe5F;AA4CD,UAAU,4BAA4B;IACrC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,wBAAwB,CAAC,EAAE,MAAM,EAAE,CAAC;IACpC,yCAAyC;IACzC,OAAO,EAAE,YAAY,CAAC;CACtB;AAuCD,wBAAsB,qBAAqB,CAC1C,OAAO,EAAE,cAAc,EACvB,cAAc,EAAE,cAAc,EAC9B,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,4BAA4B,GACnC,OAAO,CACT,0BAA0B,GAAG;IAC5B,QAAQ,EAAE,eAAe,CAAC;IAC1B,mBAAmB,EAAE,OAAO,CAAC;IAC7B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,sFAAsF;IACtF,wBAAwB,CAAC,EAAE,gBAAgB,CAAC;CAC5C,CACD,CAsIA"}

package/dist/mcp/utils/knowledge.js

@@ -0,0 +1,455 @@
+/**
+ * Knowledge context utilities for session-init (injury L-06).
+ *
+ * Pre-fix this module had a divergent, dead resolution path: its ONLY
+ * discovery lane was an HTTP GET against `/api/knowledge/bases` — a route
+ * shape that does not exist anywhere — its config lane was a stub service
+ * that always returned null, and a non-UUID project id (e.g. the atlas
+ * basename 'repository-collection') gated the whole thing into a FALSE 'offline' state.
+ *
+ * Now the knowledge-base discovery resolves through the SAME implementation
+ * the `knowledge` tool serves (ONE path — @vibesdotdev/knowledge's canonical
+ * semantic client, identity-scoped exactly like
+ * items/bases reads). State names are honest:
+ *  - 'explicit'  — caller-provided knowledgeBaseIds
+ *  - 'discovery' — bases found through the knowledge store
+ *  - 'none'      — discovery ran and found nothing
+ *  - 'disabled'  — caller set useKnowledgeApi: false
+ *  - 'project-binding' — project-owned role bindings from platform-web
+ * There is no 'offline': the local store does not need a network, and a
+ * missing project binding is represented by its own readiness snapshot.
+ *
+ * Binding policy (project-bound sessions):
+ *  - 'optional' (default) — bindings win only when ALL three roles are bound
+ *    ('ready'). While the binding is degraded/missing (including reads the
+ *    runtime cannot perform: local-only networking, provider absent, read
+ *    failed), resolution FALLS BACK to the prior explicit → project-ref →
+ *    discovery chain so adopting the binding table never empties a session's
+ *    knowledge context. The honest binding snapshot is persisted either way,
+ *    with a `reason` that distinguishes truly-unbound ('no-roles-bound') from
+ *    an unperformable read ('local-only-networking', 'binding-read-failed',
+ *    'binding-provider-unavailable').
+ *  - 'required' — init fails unless the binding is 'ready'. Local-only
+ *    networking cannot verify bindings, so required + local-only fails too.
+ * The binding read is a REMOTE lane and is skipped under local-only
+ * networking, exactly like project resolution; local discovery never is.
+ */
+import * as z from 'zod/v4';
+import { CapabilityError, CaughtFailureSchema, valueFreeFailure } from '@vibesdotdev/kernel';
+const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const CORE_KNOWLEDGE_BASE_NAMES = [
+    'Dependencies & Tech Stack',
+    'Project Rules & Standards',
+    'Codebase Knowledge'
+];
+export const PROJECT_KNOWLEDGE_BINDING_ROLES = ['dependencies', 'rules', 'codebase'];
+async function loadSessionMetadata(session, sessionId) {
+    const existing = await session.getSession(sessionId);
+    return existing?.metadata ?? {};
+}
+/**
+ * Resolve API client from context using canonical `api` property.
+ */
+async function getApiClient(context) {
+    if (context.api) {
+        return context.api;
+    }
+    if (context.createClient) {
+        return await context.createClient();
+    }
+    return null;
+}
+const ProjectKnowledgeBindingRoleSchema = z.enum(PROJECT_KNOWLEDGE_BINDING_ROLES);
+function makeUnboundKnowledgeBinding(policy, knowledgeEnabled) {
+    return {
+        state: 'missing',
+        policy,
+        roles: {},
+        missingRoles: [],
+        source: knowledgeEnabled ? 'unbound' : 'disabled',
+        reason: knowledgeEnabled ? 'no-project-binding' : 'knowledge-disabled'
+    };
+}
+/**
+ * The `projects` runtime client. Absence is asked as the declared fact (no
+ * registered client); a registered client that fails to resolve is a carried
+ * failure, never reported as absence.
+ */
+async function resolveProjectKnowledgeBindingProvider(runtime) {
+    const query = runtime
+        .query('runtime/client')
+        .withId('projects');
+    if (!(await query.existsAsync()))
+        return { outcome: 'absent' };
+    try {
+        return { outcome: 'present', provider: await query.resolve() };
+    }
+    catch (error) {
+        return { outcome: 'failed', failure: valueFreeFailure(CaughtFailureSchema.parse(error)) };
+    }
+}
+/** A mode string, read independently: a malformed value is absent, never a throw. */
+const ModeSchema = z.string().optional().catch(undefined);
+const LocalOnlyFlagSchema = z.union([z.boolean(), z.literal('true')]).optional().catch(undefined);
+const NetworkSettingsSchema = z
+    .object({ mode: ModeSchema, localOnly: LocalOnlyFlagSchema })
+    .optional()
+    .catch(undefined);
+const AiSettingsSchema = z.object({ connectionMode: ModeSchema }).optional().catch(undefined);
+const NetworkConfigSchema = z
+    .object({
+    ai: AiSettingsSchema,
+    dev: z.object({ network: NetworkSettingsSchema }).optional().catch(undefined),
+    network: NetworkSettingsSchema
+})
+    .catch({});
+const NetworkEnvironmentSchema = z
+    .object({
+    ai: AiSettingsSchema,
+    connectionMode: ModeSchema,
+    network: NetworkSettingsSchema,
+    networkMode: ModeSchema,
+    localOnly: LocalOnlyFlagSchema
+})
+    .catch({});
+function isLocalOnlyNetworking(context) {
+    const config = NetworkConfigSchema.parse(context.config ?? {});
+    const environment = NetworkEnvironmentSchema.parse(context.environment ?? {});
+    const aiConnectionMode = config.ai?.connectionMode || environment.connectionMode || environment.ai?.connectionMode;
+    if (aiConnectionMode?.toLowerCase() === 'local-only') {
+        return true;
+    }
+    const networkMode = config.dev?.network?.mode ||
+        config.network?.mode ||
+        environment.network?.mode ||
+        environment.networkMode;
+    if (networkMode?.toLowerCase().includes('local-only')) {
+        return true;
+    }
+    return [config.network?.localOnly, environment.network?.localOnly, environment.localOnly].some((value) => value === true || value === 'true');
+}
+/** A knowledge base as discovery reads it; one malformed row is skipped, never the batch. */
+const KnowledgeBaseRowSchema = z.object({ id: z.string().min(1), name: z.string() });
+/**
+ * Discover knowledge bases through the SAME implementation the `knowledge`
+ * tool serves: the local record store, identity-scoped like every other
+ * bases/items read through Knowledge's semantic client. No
+ * network, no project gate — bases are identity-scoped, not project-gated.
+ *
+ * `@vibesdotdev/knowledge` is a declared dependency loaded on first use, which
+ * keeps its storage machinery out of bundles that never init sessions. A load
+ * or read failure is a carried `failed` outcome (value-free), never 'none'.
+ */
+async function discoverKnowledgeBasesLocally(runtime, names) {
+    try {
+        return { outcome: 'found', bases: await readKnowledgeBasesByName(runtime, names) };
+    }
+    catch (error) {
+        return { outcome: 'failed', failure: valueFreeFailure(CaughtFailureSchema.parse(error)) };
+    }
+}
+async function readKnowledgeBasesByName(runtime, names) {
+    const { getVibesKnowledgeClient } = await import('@vibesdotdev/knowledge/client');
+    const client = await getVibesKnowledgeClient(runtime);
+    const bases = await (await client.bases).list();
+    const matching = new Map();
+    for (const row of bases) {
+        const base = KnowledgeBaseRowSchema.safeParse(row);
+        if (base.success && names.includes(base.data.name) && !matching.has(base.data.name)) {
+            matching.set(base.data.name, base.data.id);
+        }
+    }
+    if (matching.size > 0)
+        return new Map(names.filter(name => matching.has(name)).map(name => [name, matching.get(name)]));
+    // Listing is identity-scoped by Knowledge. Never call getDefault(): it can mint.
+    const oldestFirst = [...bases].sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+    const fallback = oldestFirst.find(base => base.isDefault)
+        ?? oldestFirst.find(base => base.slug === 'default');
+    return fallback ? new Map([[fallback.name, fallback.id]]) : new Map();
+}
+async function resolveProjectKnowledgeBinding(runtime, projectId, policy, knowledgeEnabled, localOnly) {
+    const empty = {
+        projectId,
+        knowledgeBaseIds: [],
+        missingKnowledgeBases: [...PROJECT_KNOWLEDGE_BINDING_ROLES],
+        source: 'project-binding'
+    };
+    if (!knowledgeEnabled) {
+        return {
+            ...empty,
+            source: 'disabled',
+            knowledgeBinding: {
+                projectId,
+                state: 'missing',
+                policy,
+                roles: {},
+                missingRoles: [...PROJECT_KNOWLEDGE_BINDING_ROLES],
+                source: 'disabled',
+                reason: 'knowledge-disabled'
+            }
+        };
+    }
+    if (!UUID_REGEX.test(projectId)) {
+        return {
+            ...empty,
+            knowledgeBinding: {
+                projectId,
+                state: 'missing',
+                policy,
+                roles: {},
+                missingRoles: [...PROJECT_KNOWLEDGE_BINDING_ROLES],
+                source: 'project-binding',
+                reason: 'project-id-is-not-a-uuid'
+            }
+        };
+    }
+    // The binding read is a remote lane (platform-web over the projects
+    // client). Local-only networking skips it — never a fake read.
+    if (localOnly) {
+        return {
+            ...empty,
+            knowledgeBinding: {
+                projectId,
+                state: 'missing',
+                policy,
+                roles: {},
+                missingRoles: [...PROJECT_KNOWLEDGE_BINDING_ROLES],
+                source: 'project-binding',
+                reason: 'local-only-networking'
+            }
+        };
+    }
+    const lookup = await resolveProjectKnowledgeBindingProvider(runtime);
+    if (lookup.outcome !== 'present') {
+        const binding = {
+            projectId,
+            state: 'missing',
+            policy,
+            roles: {},
+            missingRoles: [...PROJECT_KNOWLEDGE_BINDING_ROLES],
+            source: 'project-binding',
+            reason: lookup.outcome === 'absent' ? 'binding-provider-unavailable' : 'binding-provider-failed'
+        };
+        if (lookup.outcome === 'failed')
+            binding.failure = lookup.failure;
+        return { ...empty, knowledgeBinding: binding };
+    }
+    let records;
+    try {
+        records = BindingListSchema.parse(await lookup.provider.listKnowledgeBindings(projectId)).results;
+    }
+    catch (error) {
+        return {
+            ...empty,
+            knowledgeBinding: {
+                projectId,
+                state: 'missing',
+                policy,
+                roles: {},
+                missingRoles: [...PROJECT_KNOWLEDGE_BINDING_ROLES],
+                source: 'project-binding',
+                reason: 'binding-read-failed',
+                failure: valueFreeFailure(CaughtFailureSchema.parse(error))
+            }
+        };
+    }
+    const roles = {};
+    for (const row of records) {
+        const record = BindingRecordSchema.safeParse(row);
+        if (record.success && roles[record.data.role] === undefined) {
+            roles[record.data.role] = record.data.knowledgeBaseId;
+        }
+    }
+    const missingRoles = PROJECT_KNOWLEDGE_BINDING_ROLES.filter((role) => roles[role] === undefined);
+    const state = missingRoles.length === 0 ? 'ready' : Object.keys(roles).length > 0 ? 'degraded' : 'missing';
+    return {
+        ...empty,
+        knowledgeBaseIds: PROJECT_KNOWLEDGE_BINDING_ROLES.flatMap((role) => roles[role] ? [roles[role]] : []),
+        missingKnowledgeBases: [...missingRoles],
+        knowledgeBinding: {
+            projectId,
+            state,
+            policy,
+            roles,
+            missingRoles,
+            source: 'project-binding',
+            // Distinguish "the read worked and found nothing/partial" from the
+            // unperformable-read reasons above — outages must not read as unbound.
+            reason: state === 'degraded'
+                ? 'binding-roles-missing'
+                : state === 'missing'
+                    ? 'no-roles-bound'
+                    : undefined
+        }
+    };
+}
+/** The binding list answer: a `results` array; each row is parsed on its own below. */
+const BindingListSchema = z.object({ results: z.array(z.unknown()) });
+const BindingRecordSchema = z.object({
+    role: ProjectKnowledgeBindingRoleSchema,
+    knowledgeBaseId: z.string().regex(UUID_REGEX)
+});
+/**
+ * A `required` binding policy refused: the project binding is not `ready`.
+ * Typed `PERMISSION_DENIED knowledge-binding-required`; `details` carries the
+ * value-free snapshot facts (project id, state, missing roles).
+ */
+export function knowledgeBindingRequired(snapshot) {
+    return new CapabilityError(`KNOWLEDGE_BINDING_REQUIRED: project ${snapshot.projectId ?? 'unknown'} is ${snapshot.state}; ` +
+        `missing roles: ${snapshot.missingRoles.join(', ') || 'none'}`, 'PERMISSION_DENIED', {
+        reason: 'knowledge-binding-required',
+        details: {
+            projectId: snapshot.projectId,
+            state: snapshot.state,
+            missingRoles: [...snapshot.missingRoles],
+            bindingReason: snapshot.reason
+        }
+    });
+}
+async function resolveKnowledgeBaseIds(runtime, projectId, selectedIds, knowledgeEnabled, selectedSource = 'explicit', knowledgeBindingPolicy = 'optional') {
+    if (!knowledgeEnabled) {
+        return {
+            projectId,
+            knowledgeBaseIds: [],
+            missingKnowledgeBases: [...CORE_KNOWLEDGE_BASE_NAMES],
+            source: 'disabled',
+            knowledgeBinding: makeUnboundKnowledgeBinding(knowledgeBindingPolicy, false)
+        };
+    }
+    if (selectedIds && selectedIds.length > 0) {
+        return {
+            projectId,
+            knowledgeBaseIds: selectedIds,
+            missingKnowledgeBases: [],
+            source: selectedSource,
+            knowledgeBinding: makeUnboundKnowledgeBinding(knowledgeBindingPolicy, true)
+        };
+    }
+    const discovered = await discoverKnowledgeBasesLocally(runtime, CORE_KNOWLEDGE_BASE_NAMES);
+    const bases = discovered.outcome === 'found' ? discovered.bases : new Map();
+    const ids = Array.from(bases.values());
+    const resolution = {
+        projectId,
+        knowledgeBaseIds: ids,
+        missingKnowledgeBases: CORE_KNOWLEDGE_BASE_NAMES.filter((name) => !bases.has(name)),
+        source: ids.length > 0 ? 'discovery' : 'none',
+        knowledgeBinding: makeUnboundKnowledgeBinding(knowledgeBindingPolicy, true)
+    };
+    if (discovered.outcome === 'failed')
+        resolution.discoveryFailure = discovered.failure;
+    return resolution;
+}
+/** The project answer session reads; anything else resolves no project. */
+const ProjectResponseSchema = z.object({
+    id: z.string().min(1),
+    slug: z.string().optional().catch(undefined)
+});
+/**
+ * Resolve a project identifier (UUID or slug) to its UUID via the API.
+ * Project resolution is a remote nicety: a failure never becomes a knowledge
+ * state, and init continues with the raw identifier, carrying why.
+ */
+async function resolveProjectViaApi(client, projectIdentifier) {
+    if (!projectIdentifier?.trim() || !client) {
+        return { outcome: 'unresolved' };
+    }
+    const identifier = projectIdentifier.trim();
+    try {
+        // API endpoint /api/projects/[id] accepts both UUID and slug
+        const answer = await client.request(`/api/projects/${encodeURIComponent(identifier)}`, { method: 'GET' });
+        const project = ProjectResponseSchema.safeParse(answer);
+        return project.success
+            ? { outcome: 'resolved', id: project.data.id, slug: project.data.slug }
+            : { outcome: 'unresolved' };
+    }
+    catch (error) {
+        return { outcome: 'failed', failure: valueFreeFailure(CaughtFailureSchema.parse(error)) };
+    }
+}
+export async function applyKnowledgeContext(context, sessionManager, sessionId, args, options) {
+    const apiClient = await getApiClient(context);
+    const runtime = options.runtime;
+    let projectRef = null;
+    if (runtime?.hasContext?.('workspace/project-ref')) {
+        const projectRefContext = await runtime.context('workspace/project-ref');
+        projectRef = projectRefContext.resolve();
+    }
+    const boundProjectId = projectRef?.projectId ? projectRef.projectId : undefined;
+    const requestedProjectId = options.projectIdOverride ?? args.projectId;
+    if (boundProjectId &&
+        requestedProjectId &&
+        boundProjectId.toLowerCase() !== requestedProjectId.toLowerCase()) {
+        throw new CapabilityError(`PROJECT_REF_CONFLICT: checkout is bound to ${boundProjectId}, not ${requestedProjectId}`, 'CONFLICT', { reason: 'project-ref-conflict', details: { boundProjectId, requestedProjectId } });
+    }
+    // Checkout ProjectRef is authority when bound; explicit may only confirm it
+    // or supply identity when the checkout is unbound.
+    const projectIdentifier = boundProjectId ?? requestedProjectId;
+    // Resolve project via API (handles both UUID and slug). Local-only
+    // networking skips ONLY this remote lane — never local knowledge discovery.
+    const localOnly = isLocalOnlyNetworking(context);
+    const projectResolution = !localOnly
+        ? await resolveProjectViaApi(apiClient, projectIdentifier)
+        : { outcome: 'unresolved' };
+    const resolvedProject = projectResolution.outcome === 'resolved' ? projectResolution : undefined;
+    const projectId = resolvedProject?.id ?? projectIdentifier;
+    const projectIdIsUuid = projectId ? UUID_REGEX.test(projectId) : false;
+    // Knowledge discovery is LOCAL-FIRST and identity-scoped; it needs neither
+    // a network nor a platform-project UUID. The only off switch is the caller.
+    const knowledgeEnabled = args.useKnowledgeApi ?? true;
+    const knowledgeBindingPolicy = args.knowledgeBindingPolicy ?? 'optional';
+    const projectBound = Boolean(projectIdentifier && projectId);
+    const selectedKnowledgeBaseIds = args.knowledgeBaseIds ?? options.knowledgeBaseIdsOverride ?? projectRef?.knowledgeBaseIds;
+    const selectedKnowledgeSource = args.knowledgeBaseIds && args.knowledgeBaseIds.length > 0 ? 'explicit' : 'project-ref';
+    let knowledgeResolution;
+    if (projectBound) {
+        const bindingResolution = await resolveProjectKnowledgeBinding(runtime, projectId, knowledgeBindingPolicy, knowledgeEnabled, localOnly);
+        if (knowledgeBindingPolicy === 'required' &&
+            bindingResolution.knowledgeBinding.state !== 'ready') {
+            throw knowledgeBindingRequired(bindingResolution.knowledgeBinding);
+        }
+        if (bindingResolution.knowledgeBinding.state === 'ready' || !knowledgeEnabled) {
+            knowledgeResolution = bindingResolution;
+        }
+        else {
+            // Optional policy, binding not ready: restore the prior explicit →
+            // project-ref → discovery chain so adopting bindings never empties a
+            // previously-working knowledge context. The honest binding snapshot
+            // (degraded/missing + reason) is persisted regardless of which lane
+            // supplied the ids.
+            const fallback = await resolveKnowledgeBaseIds(runtime, projectId, selectedKnowledgeBaseIds, knowledgeEnabled, selectedKnowledgeSource, knowledgeBindingPolicy);
+            knowledgeResolution =
+                fallback.knowledgeBaseIds.length === 0 && bindingResolution.knowledgeBaseIds.length > 0
+                    ? // The fallback chain found nothing but SOME roles are bound —
+                        // partially-bound knowledge is still real knowledge context.
+                        bindingResolution
+                    : { ...fallback, knowledgeBinding: bindingResolution.knowledgeBinding };
+        }
+    }
+    else {
+        knowledgeResolution = await resolveKnowledgeBaseIds(runtime, projectId, selectedKnowledgeBaseIds, knowledgeEnabled, selectedKnowledgeSource, knowledgeBindingPolicy);
+    }
+    const metadata = await loadSessionMetadata(sessionManager, sessionId);
+    const updatedMetadata = {
+        ...metadata,
+        projectId: knowledgeResolution.projectId,
+        projectSlug: resolvedProject?.slug ?? (projectIdIsUuid || !projectId ? undefined : projectId),
+        knowledgeBaseIds: knowledgeResolution.knowledgeBaseIds,
+        knowledgeBinding: knowledgeResolution.knowledgeBinding,
+        workspaceKey: projectRef?.workspaceKey,
+        projectBindingId: projectRef?.bindingId,
+        workspacePath: options.workspacePath
+    };
+    const updatePayload = {
+        projectId: knowledgeResolution.projectId,
+        metadata: updatedMetadata
+    };
+    await sessionManager.updateSession(sessionId, updatePayload);
+    return {
+        ...knowledgeResolution,
+        metadata: updatedMetadata,
+        knowledgeApiEnabled: knowledgeEnabled,
+        workspacePath: options.workspacePath,
+        projectResolutionFailure: projectResolution.outcome === 'failed' ? projectResolution.failure : undefined
+    };
+}
+//# sourceMappingURL=knowledge.js.map