@debian777/kairos-mcp 3.0.1-beta.14

package/dist/embed-docs/mem/00000000-0000-0000-0000-000000002001.md

@@ -0,0 +1,324 @@
+# Create New KAIROS Protocol Chain
+
+Guide an AI agent through creating a new executable protocol chain in KAIROS.
+This protocol is offered when kairos_search finds no match. **Use a challenge
+on every step that can be verified** — it makes protocols runnable, auditable,
+and self-healing. When in doubt, add a challenge.
+
+A challenge is defined as a **JSON object in a fenced ` ```json ` block** at the
+end of each step: use an object with a `challenge` key whose value has the same
+shape as the `challenge` returned by kairos_begin and kairos_next; round-trips
+cleanly with kairos_dump and kairos_mint.
+
+## How to write a Natural Language Triggers section
+
+Every protocol **must** include a `## Natural Language Triggers` section as the
+**first H2** after the H1 title and introductory paragraph. This section tells
+agents when to activate the protocol from human speech.
+
+**Required structure (exact order):**
+
+1. **Trigger phrases** — 3–6 quoted phrases a user would say to invoke this protocol.
+2. **Trigger pattern** — verb + noun formula: `**verb** + (noun1 / noun2 / noun3)`.
+3. **Must Never** — 1–3 cases where this protocol must NOT be triggered.
+4. **Must Always** — 1–3 mandatory behaviours when the protocol IS triggered.
+5. **Good trigger examples** — 2–3 phrases that correctly activate, with `→ run this protocol`.
+6. **Bad trigger examples** — 2–3 phrases that should NOT activate, with `→ use X instead`.
+
+**Must Never:**
+- Use vague descriptions: ❌ "Run when the user wants to do something with UI"
+- Overlap with another protocol's triggers without disambiguation
+- Omit the section — every protocol needs one
+
+**Must Always:**
+- Use imperative language in Must Never / Must Always (no "should", "consider", "might")
+- Include at least one Good and one Bad example
+- Match trigger verbs to the protocol's actual purpose
+
+**Good example** (for a deployment protocol):
+
+```markdown
+## Natural Language Triggers
+
+**Run this protocol when the user says ANY of:**
+
+- "deploy to staging" / "push to production"
+- "release this version" / "ship it"
+
+**Trigger verbs** + (staging / production / environment / release):
+- **deploy** / **push** / **release** / **ship** / **promote**
+
+**Must Never:**
+- Trigger on "deploy" when the user means a local dev server
+- Run without confirming the target environment
+
+**Must Always:**
+- Confirm target environment before Step 1
+- Check that CI pipeline passed before deploying
+
+**Good trigger examples:**
+- "Deploy the API to staging" → run this protocol
+- "Ship v2.3.0 to production" → run this protocol
+
+**Bad trigger examples:**
+- "Start the dev server" → not a deployment, do not trigger
+- "Show me the last deployment" → use search, not this protocol
+```
+
+**Bad example** (vague, no verbs, no Good/Bad):
+
+```markdown
+## When to Use
+This protocol can be used for deployments and releases.
+```
+
+## Why use a challenge on every step
+
+- **Runnable:** Agents and users can execute the protocol step-by-step and
+  prove completion.
+- **Deterministic:** Each step has a clear success criterion (command exit
+  code, comment length, user confirmation, or MCP result).
+- **Recoverable:** If a step fails, kairos_next returns a fresh challenge
+  and the agent can retry or fix the step via kairos_update.
+
+Prefer a challenge on every step; omit only for purely informational steps
+where no verification is possible.
+
+Example: ```json
+{
+  "challenge": {
+    "type": "comment",
+    "comment": { "min_length": 10 },
+    "required": true
+  }
+}
+```
+
+## Challenge types and JSON examples
+
+Place a fenced ` ```json ` block at the end of the step with an object with a
+`challenge` key. Use the type that fits the step; mix types in one protocol.
+
+**shell** — Step requires running a command (build, test, deploy script).
+
+Example: ```json
+{
+  "challenge": {
+    "type": "shell",
+    "shell": {
+      "cmd": "npm test",
+      "timeout_seconds": 60
+    },
+    "required": true
+  }
+}
+```
+
+**comment** — Step requires a short verification (review, summary, checklist).
+
+Example: ```json
+{
+  "challenge": {
+    "type": "comment",
+    "comment": { "min_length": 50 },
+    "required": true
+  }
+}
+```
+
+**user_input** — Step requires human confirmation (approvals, go/no-go).
+
+Example: ```json
+{
+  "challenge": {
+    "type": "user_input",
+    "user_input": { "prompt": "Approve deployment?" },
+    "required": true
+  }
+}
+```
+
+**mcp** — Step requires calling an MCP tool (e.g. kairos_mint, kairos_update).
+
+Example: ```json
+{
+  "challenge": {
+    "type": "mcp",
+    "mcp": { "tool_name": "kairos_mint" },
+    "required": true
+  }
+}
+```
+
+## Example protocol (for inspiration)
+
+Use H1 for the protocol title, H2 for each step, then step body, then a
+` ```json ` block with the challenge for that step.
+
+**Step 1 — shell:** Run the test suite and linter.
+
+Example: ```json
+{
+  "challenge": {
+    "type": "shell",
+    "shell": {
+      "cmd": "npm test && npm run lint",
+      "timeout_seconds": 60
+    },
+    "required": true
+  }
+}
+```
+
+**Step 2 — comment:** Summarize what changed and why (min 50 chars).
+
+Example: ```json
+{
+  "challenge": {
+    "type": "comment",
+    "comment": { "min_length": 50 },
+    "required": true
+  }
+}
+```
+
+**Step 3 — user_input:** Get user approval for merge.
+
+Example: ```json
+{
+  "challenge": {
+    "type": "user_input",
+    "user_input": { "prompt": "Approve these changes for merge?" },
+    "required": true
+  }
+}
+```
+
+**Step 4 — mcp:** Call the merge tool.
+
+Example: ```json
+{
+  "challenge": {
+    "type": "mcp",
+    "mcp": { "tool_name": "merge_tool" },
+    "required": true
+  }
+}
+```
+
+---
+
+Example step format: H2, body, then a trailing ` ```json ` block with `challenge`.
+
+Format: ```json
+{
+  "challenge": {
+    "type": "comment",
+    "comment": { "min_length": 10 },
+    "required": true
+  }
+}
+```
+
+## Step 1: Confirm Intent
+
+Before creating a new protocol, confirm the user actually wants this.
+They may have misspelled a search query, or the protocol may exist under
+a different name.
+
+Ask the user: "No existing protocol matched your query. Would you like
+to create a new one, or refine your search?"
+
+```json
+{
+  "challenge": {
+    "type": "user_input",
+    "user_input": { "prompt": "Confirm you want to create a new protocol chain" },
+    "required": true
+  }
+}
+```
+
+## Step 2: Gather Requirements
+
+Collect the key details for the new protocol:
+
+- **Title**: A clear, descriptive name for the protocol chain (H1 heading)
+- **Steps**: What steps should the protocol have? (each becomes an H2 heading)
+- **Challenges**: For each step, add a ` ```json ` block with a `challenge` key (one of):
+  - **shell** — `{"challenge":{"type":"shell","shell":{"cmd":"...","timeout_seconds":30},"required":true}}`
+  - **comment** — `{"challenge":{"type":"comment","comment":{"min_length":50},"required":true}}`
+  - **user_input** — `{"challenge":{"type":"user_input","user_input":{"prompt":"..."},"required":true}}`
+  - **mcp** — `{"challenge":{"type":"mcp","mcp":{"tool_name":"kairos_mint"},"required":true}}`
+
+Summarize the gathered requirements as a structured list.
+
+```json
+{
+  "challenge": {
+    "type": "comment",
+    "comment": { "min_length": 50 },
+    "required": true
+  }
+}
+```
+
+## Step 3: Draft Markdown
+
+Using the requirements from step 2, draft the full markdown document
+that will be passed to `kairos_mint`. Use H1 for title, H2 per step,
+step body, then a ` ```json ` block with the challenge for that step.
+**Add a challenge (```json block) to every step** that can be verified (see
+examples above). Post the full drafted markdown in your verification comment.
+
+**Must Always include in the draft:**
+- **Natural Language Triggers** section as the first H2 — follow the structure
+  and Good/Bad examples defined in "How to write a Natural Language Triggers
+  section" above.
+- **Completion Rule** section as the last H2.
+
+```json
+{
+  "challenge": {
+    "type": "comment",
+    "comment": { "min_length": 100 },
+    "required": true
+  }
+}
+```
+
+## Step 4: User Review
+
+Present the drafted protocol markdown to the user for review.
+Ask them to approve, request changes, or cancel.
+
+If they request changes, update the draft before proceeding.
+
+```json
+{
+  "challenge": {
+    "type": "user_input",
+    "user_input": { "prompt": "Approve the protocol draft for minting" },
+    "required": true
+  }
+}
+```
+
+## Step 5: Mint Protocol
+
+Call `kairos_mint` with the approved markdown document. Use
+`force_update: false` (default) unless the user explicitly asks to
+overwrite an existing protocol.
+
+Confirm the mint was successful and report the chain head URI back
+to the user.
+
+```json
+{
+  "challenge": {
+    "type": "mcp",
+    "mcp": { "tool_name": "kairos_mint" },
+    "required": true
+  }
+}
+```

package/dist/embed-docs/mem/00000000-0000-0000-0000-000000002002.md

@@ -0,0 +1,48 @@
+# Get help refining your search
+
+**You are an AI agent.** You ran `kairos_search` and got no solid match (or only weak/ambiguous ones). This protocol helps you turn the user's vague request into a better query so the next `kairos_search` can find the right protocol.
+
+## Step 1: Extract what the user actually wants
+
+From the user's original message, identify:
+- **Goal:** What outcome do they want? (e.g. "run tests", "write docs", "create a Jira ticket")
+- **Context:** Any project, tool, domain, or proper noun they mentioned?
+- **Gaps:** What is missing or ambiguous? (e.g. "which repo?", "which doc type?", "which project key?")
+
+If the request was a slash-command or shorthand (e.g. "/ai-docs", "do the thing"), expand it: what would a concrete version of that command look like?
+
+Write your analysis as your solution (goal + context + gaps, minimum 30 characters).
+
+```json
+{
+  "challenge": {
+    "type": "comment",
+    "comment": { "min_length": 30 },
+    "required": true
+  }
+}
+```
+
+## Step 2: Build and run a refined kairos_search query
+
+Using your Step 1 analysis, construct a single search query:
+- Use 3–8 specific words (nouns and verbs, no filler). Examples: "write ai instructions zero-drift template", "jira create story BIB", "npm test lint deploy".
+- Include domain or tool names if known (e.g. "jira", "gitlab", "coding standards").
+- Do not reuse the user's exact vague phrase — that already failed.
+
+Write your refined query as your solution, then call `kairos_search` with it.
+
+- **Strong match (score >= 0.7):** Pick that choice and call `kairos_begin` with its URI.
+- **Weak matches only (all scores < 0.7):** Ask the user to clarify, or pick the create choice to build a new protocol.
+
+Do not loop this refining protocol more than once — if two searches fail, the protocol likely does not exist yet.
+
+```json
+{
+  "challenge": {
+    "type": "mcp",
+    "mcp": { "tool_name": "kairos_search" },
+    "required": true
+  }
+}
+```

package/dist/http/bearer-validate.d.ts

@@ -0,0 +1,14 @@
+export interface AuthPayload {
+    sub: string;
+    groups: string[];
+    /** Realm from token issuer (e.g. kairos-dev) for space isolation. */
+    realm: string;
+    /** Optional group UUIDs from token; when present used for space ID so renames are stable. */
+    group_ids?: string[];
+}
+/**
+ * Validate Bearer JWT: iss in trusted list, aud in allowed list, exp not expired, signature valid.
+ * Returns { sub, groups } or null if invalid.
+ */
+export declare function validateBearerToken(token: string, trustedIssuers: string[], allowedAudiences: string[]): Promise<AuthPayload | null>;
+//# sourceMappingURL=bearer-validate.d.ts.map

package/dist/http/bearer-validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bearer-validate.d.ts","sourceRoot":"","sources":["../../src/http/bearer-validate.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAC;IACd,6FAA6F;IAC7F,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAoDD;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,MAAM,EACb,cAAc,EAAE,MAAM,EAAE,EACxB,gBAAgB,EAAE,MAAM,EAAE,GACzB,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAsD7B"}

package/dist/http/bearer-validate.js

@@ -0,0 +1,111 @@
+/**
+ * Bearer JWT validation for OIDC (Keycloak). Verifies iss, aud, exp and signature via JWKS.
+ * When KEYCLOAK_INTERNAL_URL is set, JWKS is fetched from that host so the app in Docker can reach Keycloak.
+ */
+import { createRemoteJWKSet, jwtVerify } from 'jose';
+import { decodeJwt } from 'jose/jwt/decode';
+import { KEYCLOAK_URL, KEYCLOAK_INTERNAL_URL } from '../config.js';
+import { structuredLogger } from '../utils/structured-logger.js';
+const JWKS_CACHE = new Map();
+/** Resolve JWKS fetch URL: use KEYCLOAK_INTERNAL_URL when token issuer is user-facing (localhost) so Docker app can reach Keycloak. */
+function getJwksFetchUrl(issuer) {
+    const base = issuer.replace(/\/$/, '');
+    if (KEYCLOAK_INTERNAL_URL && KEYCLOAK_URL && base.startsWith(KEYCLOAK_URL.replace(/\/$/, ''))) {
+        const internalBase = KEYCLOAK_INTERNAL_URL.replace(/\/$/, '');
+        return `${internalBase}${new URL(base).pathname}/protocol/openid-connect/certs`;
+    }
+    return `${base}/protocol/openid-connect/certs`;
+}
+function getJwksForIssuer(issuer) {
+    const cached = JWKS_CACHE.get(issuer);
+    if (cached)
+        return cached;
+    const url = getJwksFetchUrl(issuer);
+    const jwks = createRemoteJWKSet(new URL(url));
+    JWKS_CACHE.set(issuer, jwks);
+    return jwks;
+}
+/** Decode JWT payload without verification (issuer check only). */
+function decodePayload(jwt) {
+    return decodeJwt(jwt);
+}
+function extractGroups(payload) {
+    const g = payload['groups'];
+    if (Array.isArray(g))
+        return g.filter((x) => typeof x === 'string');
+    const realm = payload['realm_access'];
+    if (realm && Array.isArray(realm.roles))
+        return realm.roles.filter((x) => typeof x === 'string');
+    return [];
+}
+/** Extract realm from issuer URL (e.g. http://keycloak:8080/realms/kairos-dev -> kairos-dev). */
+function realmFromIssuer(iss) {
+    const match = /\/realms\/([^/]+)/.exec(iss);
+    const segment = match?.[1] ?? iss.split('/').filter(Boolean).pop();
+    return typeof segment === 'string' ? segment : 'default';
+}
+function extractGroupIds(payload) {
+    const g = payload['group_ids'];
+    if (Array.isArray(g)) {
+        const ids = g.filter((x) => typeof x === 'string' && x.length > 0);
+        return ids.length > 0 ? ids : undefined;
+    }
+    return undefined;
+}
+/**
+ * Validate Bearer JWT: iss in trusted list, aud in allowed list, exp not expired, signature valid.
+ * Returns { sub, groups } or null if invalid.
+ */
+export async function validateBearerToken(token, trustedIssuers, allowedAudiences) {
+    if (!token || trustedIssuers.length === 0 || allowedAudiences.length === 0)
+        return null;
+    let payload;
+    try {
+        const unverified = decodePayload(token);
+        if (process.env['AUTH_TRACE'] === 'true' || process.env['LOG_LEVEL'] === 'trace') {
+            structuredLogger.info(`[auth] TRACE Bearer unverified payload raw=${JSON.stringify(unverified)}`);
+        }
+        const iss = typeof unverified['iss'] === 'string' ? unverified['iss'] : undefined;
+        if (!iss || !trustedIssuers.includes(iss)) {
+            structuredLogger.info(`[auth] Bearer rejected: issuer not trusted token_iss=${iss ?? 'missing'} trusted=${JSON.stringify(trustedIssuers)}`);
+            return null;
+        }
+        const jwks = getJwksForIssuer(iss);
+        const getKey = (protectedHeader) => jwks(protectedHeader);
+        const { payload: p } = await jwtVerify(token, getKey, { issuer: iss });
+        payload = p;
+        if (process.env['AUTH_TRACE'] === 'true' || process.env['LOG_LEVEL'] === 'trace') {
+            structuredLogger.info(`[auth] TRACE Bearer payload raw=${JSON.stringify(payload)}`);
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        structuredLogger.info(`[auth] Bearer rejected: JWT verify failed err=${msg}`);
+        return null;
+    }
+    const aud = payload['aud'];
+    const audList = Array.isArray(aud) ? aud : typeof aud === 'string' ? [aud] : [];
+    const issForAud = typeof payload['iss'] === 'string' ? payload['iss'] : '';
+    // Keycloak: accept aud "account", or empty aud when issuer is a Keycloak realm (some tokens omit aud).
+    const keycloakAccountAud = audList.includes('account') && issForAud.includes('/realms/');
+    const keycloakEmptyAud = audList.length === 0 && issForAud.includes('/realms/');
+    const hasAudience = allowedAudiences.some((a) => audList.includes(a)) ||
+        keycloakAccountAud ||
+        keycloakEmptyAud;
+    if (!hasAudience) {
+        structuredLogger.info(`[auth] Bearer rejected: audience not allowed token_aud=${JSON.stringify(audList)} allowed=${JSON.stringify(allowedAudiences)}`);
+        return null;
+    }
+    const sub = typeof payload['sub'] === 'string' ? payload['sub'] : '';
+    if (!sub)
+        return null;
+    const iss = typeof payload['iss'] === 'string' ? payload['iss'] : '';
+    const realm = realmFromIssuer(iss);
+    const groups = extractGroups(payload);
+    const group_ids = extractGroupIds(payload);
+    const result = { sub, groups, realm };
+    if (group_ids && group_ids.length > 0)
+        result.group_ids = group_ids;
+    return result;
+}
+//# sourceMappingURL=bearer-validate.js.map

package/dist/http/bearer-validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bearer-validate.js","sourceRoot":"","sources":["../../src/http/bearer-validate.ts"],"names":[],"mappings":"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"}

package/dist/http/http-api-attest.d.ts

@@ -0,0 +1,7 @@
+import express from 'express';
+import type { QdrantService } from '../services/qdrant/service.js';
+/**
+ * Set up API route for kairos_attest (V2: no final_solution required)
+ */
+export declare function setupAttestRoute(app: express.Express, qdrantService: QdrantService): void;
+//# sourceMappingURL=http-api-attest.d.ts.map

package/dist/http/http-api-attest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-api-attest.d.ts","sourceRoot":"","sources":["../../src/http/http-api-attest.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAE9B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAInE;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,CAAC,OAAO,EAAE,aAAa,EAAE,aAAa,QAmIlF"}

package/dist/http/http-api-attest.js

@@ -0,0 +1,103 @@
+import { structuredLogger } from '../utils/structured-logger.js';
+import { IDGenerator } from '../services/id-generator.js';
+import { modelStats } from '../services/stats/model-stats.js';
+/**
+ * Set up API route for kairos_attest (V2: no final_solution required)
+ */
+export function setupAttestRoute(app, qdrantService) {
+    app.post('/api/kairos_attest', async (req, res) => {
+        const startTime = Date.now();
+        try {
+            const { uri, outcome, quality_bonus = 0, message, llm_model_id } = req.body;
+            if (!uri || typeof uri !== 'string') {
+                res.status(400).json({
+                    error: 'INVALID_INPUT',
+                    message: 'uri is required and must be a string'
+                });
+                return;
+            }
+            if (!outcome || !['success', 'failure'].includes(outcome)) {
+                res.status(400).json({
+                    error: 'INVALID_INPUT',
+                    message: 'outcome is required and must be "success" or "failure"'
+                });
+                return;
+            }
+            if (!message || typeof message !== 'string') {
+                res.status(400).json({
+                    error: 'INVALID_INPUT',
+                    message: 'message is required and must be a string'
+                });
+                return;
+            }
+            structuredLogger.info(`-> POST /api/kairos_attest (uri: ${uri}, outcome: ${outcome})`);
+            const modelIdentity = {
+                modelId: llm_model_id || 'http-api-attest',
+                provider: 'unknown',
+                family: 'unknown'
+            };
+            const qdrantUuid = IDGenerator.qdrantIdFromUri(uri);
+            const basicQualityBonus = outcome === 'success' ? 1 : -0.2;
+            const currentPoint = await qdrantService.retrieveById(qdrantUuid);
+            if (!currentPoint) {
+                res.status(404).json({
+                    error: 'NOT_FOUND',
+                    message: `Memory not found: ${uri}`
+                });
+                return;
+            }
+            const currentMetrics = currentPoint.payload?.quality_metrics || {};
+            const implementationBonus = await modelStats.calculateImplementationBonus(currentMetrics, modelIdentity.modelId, outcome);
+            const totalQualityBonus = basicQualityBonus + implementationBonus + quality_bonus;
+            const metricsUpdate = {
+                retrievalCount: 1,
+                successCount: outcome === 'success' ? 1 : 0,
+                failureCount: outcome === 'failure' ? 1 : 0,
+                lastRated: new Date().toISOString(),
+                lastRater: modelIdentity.modelId,
+                qualityBonus: totalQualityBonus
+            };
+            if (message) {
+                metricsUpdate.usageContext = message;
+            }
+            await qdrantService.updateQualityMetrics(qdrantUuid, metricsUpdate);
+            if (currentPoint.payload) {
+                const { description_short, domain, task, type, tags } = currentPoint.payload;
+                const updatedQualityMetadata = modelStats.calculateStepQualityMetadata(description_short || 'Knowledge step', domain || 'general', task || 'general', type || 'context', tags || [], outcome);
+                await qdrantService.updateQualityMetadata(qdrantUuid, {
+                    step_quality_score: updatedQualityMetadata.step_quality_score,
+                    step_quality: updatedQualityMetadata.step_quality
+                });
+            }
+            await modelStats.processQualityFeedback(modelIdentity.modelId, uri, outcome, totalQualityBonus);
+            if (implementationBonus > 0) {
+                await modelStats.updateImplementationBonus(modelIdentity.modelId, implementationBonus);
+            }
+            const result = {
+                uri: uri,
+                outcome: outcome,
+                quality_bonus: totalQualityBonus,
+                message,
+                rated_at: new Date().toISOString()
+            };
+            const duration = Date.now() - startTime;
+            structuredLogger.info(`kairos_attest completed in ${duration}ms`);
+            res.status(200).json({
+                results: [result],
+                total_rated: 1,
+                total_failed: 0,
+                metadata: { duration_ms: duration }
+            });
+        }
+        catch (error) {
+            const duration = Date.now() - startTime;
+            structuredLogger.error(`kairos_attest failed in ${duration}ms`, error);
+            res.status(500).json({
+                error: 'ATTEST_FAILED',
+                message: error instanceof Error ? error.message : 'Failed to attest step completion',
+                duration_ms: duration
+            });
+        }
+    });
+}
+//# sourceMappingURL=http-api-attest.js.map

package/dist/http/http-api-attest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-api-attest.js","sourceRoot":"","sources":["../../src/http/http-api-attest.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAEjE,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC1D,OAAO,EAAE,UAAU,EAAE,MAAM,kCAAkC,CAAC;AAE9D;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAoB,EAAE,aAA4B;IAC/E,GAAG,CAAC,IAAI,CAAC,oBAAoB,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;QAC9C,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAE7B,IAAI,CAAC;YACD,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,aAAa,GAAG,CAAC,EAAE,OAAO,EAAE,YAAY,EAAE,GAAG,GAAG,CAAC,IAAI,CAAC;YAE5E,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;gBAClC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;oBACjB,KAAK,EAAE,eAAe;oBACtB,OAAO,EAAE,sCAAsC;iBAClD,CAAC,CAAC;gBACH,OAAO;YACX,CAAC;YAED,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;gBACxD,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;oBACjB,KAAK,EAAE,eAAe;oBACtB,OAAO,EAAE,wDAAwD;iBACpE,CAAC,CAAC;gBACH,OAAO;YACX,CAAC;YAED,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;gBAC1C,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;oBACjB,KAAK,EAAE,eAAe;oBACtB,OAAO,EAAE,0CAA0C;iBACtD,CAAC,CAAC;gBACH,OAAO;YACX,CAAC;YAED,gBAAgB,CAAC,IAAI,CAAC,oCAAoC,GAAG,cAAc,OAAO,GAAG,CAAC,CAAC;YAEvF,MAAM,aAAa,GAAG;gBAClB,OAAO,EAAE,YAAY,IAAI,iBAAiB;gBAC1C,QAAQ,EAAE,SAAS;gBACnB,MAAM,EAAE,SAAS;aACpB,CAAC;YAEF,MAAM,UAAU,GAAG,WAAW,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC;YACpD,MAAM,iBAAiB,GAAG,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;YAE3D,MAAM,YAAY,GAAG,MAAM,aAAa,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC;YAClE,IAAI,CAAC,YAAY,EAAE,CAAC;gBAChB,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;oBACjB,KAAK,EAAE,WAAW;oBAClB,OAAO,EAAE,qBAAqB,GAAG,EAAE;iBACtC,CAAC,CAAC;gBACH,OAAO;YACX,CAAC;YAED,MAAM,cAAc,GAAG,YAAY,CAAC,OAAO,EAAE,eAAe,IAAI,EAAE,CAAC;YACnE,MAAM,mBAAmB,GAAG,MAAM,UAAU,CAAC,4BAA4B,CACrE,cAAc,EACd,aAAa,CAAC,OAAO,EACrB,OAAO,CACV,CAAC;YAEF,MAAM,iBAAiB,GAAG,iBAAiB,GAAG,mBAAmB,GAAG,aAAa,CAAC;YAElF,MAAM,aAAa,GAAQ;gBACvB,cAAc,EAAE,CAAC;gBACjB,YAAY,EAAE,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;gBAC3C,YAAY,EAAE,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;gBAC3C,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;gBACnC,SAAS,EAAE,aAAa,CAAC,OAAO;gBAChC,YAAY,EAAE,iBAAiB;aAClC,CAAC;YAEF,IAAI,OAAO,EAAE,CAAC;gBACV,aAAa,CAAC,YAAY,GAAG,OAAO,CAAC;YACzC,CAAC;YAED,MAAM,aAAa,CAAC,oBAAoB,CAAC,UAAU,EAAE,aAAa,CAAC,CAAC;YAEpE,IAAI,YAAY,CAAC,OAAO,EAAE,CAAC;gBACvB,MAAM,EAAE,iBAAiB,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,YAAY,CAAC,OAAO,CAAC;gBAC7E,MAAM,sBAAsB,GAAG,UAAU,CAAC,4BAA4B,CAClE,iBAAiB,IAAI,gBAAgB,EACrC,MAAM,IAAI,SAAS,EACnB,IAAI,IAAI,SAAS,EACjB,IAAI,IAAI,SAAS,EACjB,IAAI,IAAI,EAAE,EACV,OAAO,CACV,CAAC;gBAEF,MAAM,aAAa,CAAC,qBAAqB,CAAC,UAAU,EAAE;oBAClD,kBAAkB,EAAE,sBAAsB,CAAC,kBAAkB;oBAC7D,YAAY,EAAE,sBAAsB,CAAC,YAAY;iBACpD,CAAC,CAAC;YACP,CAAC;YAED,MAAM,UAAU,CAAC,sBAAsB,CACnC,aAAa,CAAC,OAAO,EACrB,GAAG,EACH,OAAO,EACP,iBAAiB,CACpB,CAAC;YAEF,IAAI,mBAAmB,GAAG,CAAC,EAAE,CAAC;gBAC1B,MAAM,UAAU,CAAC,yBAAyB,CAAC,aAAa,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC;YAC3F,CAAC;YAED,MAAM,MAAM,GAAG;gBACX,GAAG,EAAE,GAAG;gBACR,OAAO,EAAE,OAAO;gBAChB,aAAa,EAAE,iBAAiB;gBAChC,OAAO;gBACP,QAAQ,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;aACrC,CAAC;YAEF,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;YACxC,gBAAgB,CAAC,IAAI,CAAC,8BAA8B,QAAQ,IAAI,CAAC,CAAC;YAElE,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;gBACjB,OAAO,EAAE,CAAC,MAAM,CAAC;gBACjB,WAAW,EAAE,CAAC;gBACd,YAAY,EAAE,CAAC;gBACf,QAAQ,EAAE,EAAE,WAAW,EAAE,QAAQ,EAAE;aACtC,CAAC,CAAC;QAEP,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;YACxC,gBAAgB,CAAC,KAAK,CAAC,2BAA2B,QAAQ,IAAI,EAAE,KAAK,CAAC,CAAC;YACvE,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;gBACjB,KAAK,EAAE,eAAe;gBACtB,OAAO,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,kCAAkC;gBACpF,WAAW,EAAE,QAAQ;aACxB,CAAC,CAAC;QACP,CAAC;IACL,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/http/http-api-begin-step.d.ts

@@ -0,0 +1,8 @@
+import express from 'express';
+import { MemoryQdrantStore } from '../services/memory/store.js';
+import type { QdrantService } from '../services/qdrant/service.js';
+/**
+ * Set up API route for kairos_begin (V2: auto-redirect, no next_step/protocol_status/attest_required)
+ */
+export declare function setupBeginStepRoute(app: express.Express, memoryStore: MemoryQdrantStore, qdrantService: QdrantService): void;
+//# sourceMappingURL=http-api-begin-step.d.ts.map

package/dist/http/http-api-begin-step.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-api-begin-step.d.ts","sourceRoot":"","sources":["../../src/http/http-api-begin-step.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAC9B,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAEhE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAOnE;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,CAAC,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,aAAa,EAAE,aAAa,GAAG,IAAI,CAgH5H"}