@xopcai/xopc 0.0.206 → 0.0.207

package/dist/src/storage/sqlite/migrations/123_remove_v2_compaction_boundaries.sql

@@ -0,0 +1,25 @@
+DELETE FROM transcript_fts
+WHERE entry_id IN (
+  SELECT entry_id
+  FROM transcript_entries
+  WHERE entry_kind = 'compaction'
+);
+
+DELETE FROM transcript_entries
+WHERE entry_kind = 'compaction';
+
+UPDATE sessions
+SET
+  compacted_count = 0,
+  message_count = (
+    SELECT COUNT(*)
+    FROM transcript_entries e
+    WHERE e.session_id = sessions.session_id
+      AND e.entry_kind = 'message'
+  ),
+  estimated_tokens = (
+    SELECT COALESCE(SUM((length(COALESCE(json_extract(e.payload_json, '$.content'), '')) + 3) / 4), 0)
+    FROM transcript_entries e
+    WHERE e.session_id = sessions.session_id
+      AND e.entry_kind = 'message'
+  );

package/dist/src/storage/sqlite/migrations/runner.d.ts

@@ -3,7 +3,7 @@ import type { ApplyMigrationsOptions } from './types.js';
 /** Baseline schema version applied from schema.sql on first open. */
 export declare const XOPC_DB_BASELINE_SCHEMA_VERSION = 11;
 /** Latest schema version this release supports (increment when adding migrations). */
-export declare const XOPC_DB_SCHEMA_VERSION = 122;
+export declare const XOPC_DB_SCHEMA_VERSION = 123;
 export declare function resolveMigrationsDir(override?: string): string;
 /**
  * Apply sequential SQL migrations from (currentVersion + 1) through targetVersion.

package/dist/src/storage/sqlite/migrations/runner.js

@@ -12,7 +12,7 @@ const log = createLogger("Sqlite:Migrations");
 /** Baseline schema version applied from schema.sql on first open. */
 const XOPC_DB_BASELINE_SCHEMA_VERSION = 11;
 /** Latest schema version this release supports (increment when adding migrations). */
-const XOPC_DB_SCHEMA_VERSION = 122;
+const XOPC_DB_SCHEMA_VERSION = 123;
 const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
 function backupBeforeTaskCutover(db, databasePath) {
 	db.exec("PRAGMA wal_checkpoint(FULL)");
@@ -57,7 +57,7 @@ function applySingleMigration(db, migration) {
 * Each step runs in its own transaction and updates schema_meta on success.
 */
 function applyPendingMigrations(db, options = {}) {
-	const targetVersion = options.targetVersion ?? 122;
+	const targetVersion = options.targetVersion ?? 123;
 	let currentVersion = readSchemaVersion(db);
 	if (currentVersion > targetVersion) throw new DatabaseSchemaTooNewError(currentVersion, targetVersion);
 	if (currentVersion >= targetVersion) return currentVersion;
@@ -94,7 +94,7 @@ function applyPendingMigrations(db, options = {}) {
 }
 /** Inspect schema version without mutating the database. */
 function inspectSchemaMigrationStatus(db, options = {}) {
-	const appVersion = options.targetVersion ?? 122;
+	const appVersion = options.targetVersion ?? 123;
 	const dbVersion = readSchemaVersion(db);
 	if (dbVersion > appVersion) return {
 		dbVersion,

package/dist/src/storage/sqlite/migrations/runner.ts

@@ -19,7 +19,7 @@ const log = createLogger('Sqlite:Migrations');
 export const XOPC_DB_BASELINE_SCHEMA_VERSION = 11;
 
 /** Latest schema version this release supports (increment when adding migrations). */
-export const XOPC_DB_SCHEMA_VERSION = 122;
+export const XOPC_DB_SCHEMA_VERSION = 123;
 
 const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
 

package/dist/src/storage/sqlite/schema.js

@@ -32,7 +32,7 @@ function ensureXopcDatabaseSchema(db, options = {}) {
 		currentVersion = 11;
 	}
 	applyPendingMigrations(db, {
-		targetVersion: 122,
+		targetVersion: 123,
 		databasePath: options.databasePath
 	});
 }

package/dist/src/storage/sqlite/transcript-repository.d.ts

@@ -2,11 +2,34 @@ import type { AgentMessage } from '@earendil-works/pi-agent-core';
 import type { CompactionBoundarySummary } from '../../session/types.js';
 import { type TranscriptStoredRow, type XopcTranscriptCompactionEntry } from '../../session/session-context-for-llm.js';
 import { type TranscriptEntryRow } from './row-mappers.js';
+export interface TranscriptSourceEntry {
+    entryId: string;
+    seq: number;
+    createdAt: number;
+    row: TranscriptStoredRow;
+}
+export interface CompactionSourceSnapshot {
+    sessionId: string;
+    lastSeq: number;
+    entries: TranscriptSourceEntry[];
+}
+export interface SessionTranscriptRecallMatch {
+    entryId: string;
+    seq: number;
+    role: string | null;
+    createdAt: number;
+    content: string;
+}
 export declare function appendTranscriptEntry(sessionKey: string, row: TranscriptStoredRow, opts?: {
     sessionId?: string;
     tokenDelta?: number;
 }): TranscriptEntryRow;
-export declare function appendCompactionBoundary(sessionKey: string, row: Omit<XopcTranscriptCompactionEntry, 'baseSeq'>): TranscriptEntryRow;
+export declare function appendCompactionBoundaryIfUnchanged(sessionKey: string, expected: Pick<CompactionSourceSnapshot, 'sessionId' | 'lastSeq'>, row: Omit<XopcTranscriptCompactionEntry, 'baseSeq'>): TranscriptEntryRow | null;
+export declare function loadCompactionSourceSnapshot(sessionKey: string): CompactionSourceSnapshot | null;
+export declare function searchSessionTranscript(sessionKey: string, query: string, options?: {
+    limit?: number;
+    beforeSeq?: number;
+}): SessionTranscriptRecallMatch[];
 export declare function loadTranscriptRowsForSession(sessionKey: string): TranscriptStoredRow[];
 export declare function loadTranscriptHistoryRowsForSession(sessionKey: string): TranscriptStoredRow[];
 export declare function loadTranscriptRows(sessionId: string): TranscriptStoredRow[];

package/dist/src/storage/sqlite/transcript-repository.js

@@ -1,6 +1,7 @@
 import { getSqliteDatabase, runSqliteWriteTransaction } from "./transaction.js";
 import { buildSessionContextForLlm, isRuntimeOnlyTranscriptMessage } from "../../session/session-context-for-llm.js";
 import { classifyStoredRow, estimateTokensFromMessages, extractFtsContent, transcriptEntryRowToStoredRow } from "./row-mappers.js";
+import { escapeFts5Query } from "./fts.js";
 import { getCurrentSessionId, readCurrentSessionId } from "./session-repository.js";
 import { randomUUID } from "node:crypto";
 //#region src/storage/sqlite/transcript-repository.ts
@@ -58,13 +59,15 @@ function appendTranscriptEntry(sessionKey, row, opts) {
 		return inserted;
 	});
 }
-function appendCompactionBoundary(sessionKey, row) {
+function appendCompactionBoundaryIfUnchanged(sessionKey, expected, row) {
 	return runSqliteWriteTransaction((db) => {
 		const sessionId = readCurrentSessionId(db, sessionKey);
 		if (!sessionId) throw new Error(`Session not found: ${sessionKey}`);
+		if (sessionId !== expected.sessionId) return null;
+		if (nextSeq(db, sessionId) - 1 !== expected.lastSeq) return null;
 		const boundary = {
 			...row,
-			baseSeq: nextSeq(db, sessionId) - 1
+			baseSeq: expected.lastSeq
 		};
 		const inserted = insertEntry(db, {
 			sessionId,
@@ -83,6 +86,65 @@ function appendCompactionBoundary(sessionKey, row) {
 		return inserted;
 	});
 }
+function loadCompactionSourceSnapshot(sessionKey) {
+	const db = getSqliteDatabase();
+	const sessionId = getCurrentSessionId(sessionKey);
+	if (!sessionId) return null;
+	const rows = db.prepare(`SELECT entry_id, session_id, seq, entry_kind, role, payload_json, created_at
+       FROM transcript_entries
+       WHERE session_id = ?
+       ORDER BY seq ASC`).all(sessionId);
+	return {
+		sessionId,
+		lastSeq: rows.at(-1)?.seq ?? 0,
+		entries: rows.map((entry) => ({
+			entryId: entry.entry_id,
+			seq: entry.seq,
+			createdAt: entry.created_at,
+			row: transcriptEntryRowToStoredRow(entry)
+		}))
+	};
+}
+function searchSessionTranscript(sessionKey, query, options = {}) {
+	const sessionId = getCurrentSessionId(sessionKey);
+	const normalized = query.trim();
+	if (!sessionId || !normalized) return [];
+	const limit = Math.min(20, Math.max(1, options.limit ?? 8));
+	const beforeSeq = options.beforeSeq ?? Number.MAX_SAFE_INTEGER;
+	const db = getSqliteDatabase();
+	const ftsRows = db.prepare(`SELECT e.entry_id, e.seq, e.role, e.created_at, f.content
+       FROM transcript_fts f
+       JOIN transcript_entries e
+         ON e.session_id = f.session_id AND e.entry_id = f.entry_id
+       WHERE transcript_fts MATCH ?
+         AND f.session_id = ?
+         AND e.entry_kind <> 'compaction'
+         AND e.seq < ?
+       ORDER BY bm25(transcript_fts), e.seq DESC
+       LIMIT ?`).all(escapeFts5Query(normalized), sessionId, beforeSeq, limit);
+	const escapedLike = normalized.replaceAll("\\", "\\\\").replaceAll("%", "\\%").replaceAll("_", "\\_");
+	const literalRows = db.prepare(`SELECT entry_id, seq, role, created_at, payload_json AS content
+       FROM transcript_entries
+       WHERE session_id = ?
+         AND entry_kind <> 'compaction'
+         AND seq < ?
+         AND payload_json LIKE ? ESCAPE '\\'
+       ORDER BY seq DESC
+       LIMIT ?`).all(sessionId, beforeSeq, `%${escapedLike}%`, limit);
+	const seen = /* @__PURE__ */ new Set();
+	return [...ftsRows, ...literalRows].flatMap((row) => {
+		const result = row;
+		if (seen.has(result.entry_id)) return [];
+		seen.add(result.entry_id);
+		return [{
+			entryId: result.entry_id,
+			seq: result.seq,
+			role: result.role,
+			createdAt: result.created_at,
+			content: result.content
+		}];
+	}).slice(0, limit);
+}
 function loadTranscriptRowsForSession(sessionKey) {
 	const sessionId = getCurrentSessionId(sessionKey);
 	if (!sessionId) return [];
@@ -210,7 +272,7 @@ function listCompactionBoundaries(sessionKey) {
 			tokensBefore: payload.tokensBefore,
 			tokensAfter: payload.tokensAfter,
 			summaryPreview: payload.summary.slice(0, 500),
-			restoredFromCompactionId: payload.restoredFromCompactionId
+			audit: payload.audit
 		};
 	});
 }
@@ -221,42 +283,29 @@ function restoreBeforeCompactionBoundary(sessionKey, compactionId) {
 		const boundary = db.prepare(`SELECT seq FROM transcript_entries
          WHERE session_id = ? AND entry_id = ? AND entry_kind = 'compaction'`).get(sessionId, compactionId);
 		if (!boundary) throw new Error(`Compaction boundary not found: ${compactionId}`);
-		const restoredMessages = buildSessionContextForLlm(db.prepare(`SELECT entry_id, session_id, seq, entry_kind, role, payload_json, created_at
+		const removedEntryIds = db.prepare(`SELECT entry_id
+         FROM transcript_entries
+         WHERE session_id = ? AND seq >= ?`).all(sessionId, boundary.seq);
+		for (const entry of removedEntryIds) db.prepare(`DELETE FROM transcript_fts WHERE entry_id = ?`).run(entry.entry_id);
+		db.prepare(`DELETE FROM transcript_entries WHERE session_id = ? AND seq >= ?`).run(sessionId, boundary.seq);
+		const remainingEntries = db.prepare(`SELECT entry_id, session_id, seq, entry_kind, role, payload_json, created_at
          FROM transcript_entries
-         WHERE session_id = ? AND seq < ?
-         ORDER BY seq ASC`).all(sessionId, boundary.seq).map(transcriptEntryRowToStoredRow));
+         WHERE session_id = ?
+         ORDER BY seq ASC`).all(sessionId);
+		const restoredMessages = buildSessionContextForLlm(remainingEntries.map(transcriptEntryRowToStoredRow));
 		if (restoredMessages.length === 0) throw new Error(`No restorable context exists before compaction boundary: ${compactionId}`);
-		const current = db.prepare(`SELECT estimated_tokens FROM sessions WHERE session_key = ?`).get(sessionKey);
 		const tokensAfter = estimateTokensFromMessages(restoredMessages);
-		const baseSeq = nextSeq(db, sessionId) - 1;
-		insertEntry(db, {
-			sessionId,
-			sessionKey,
-			row: {
-				type: "compaction",
-				at: (/* @__PURE__ */ new Date()).toISOString(),
-				baseSeq,
-				plannerVersion: 2,
-				summaryModelRef: "logical-restore",
-				qualityAudit: "disabled",
-				summary: `Restored the effective context that existed before compaction boundary ${compactionId}.`,
-				messages: restoredMessages,
-				firstKeptIndex: 0,
-				tokensBefore: current.estimated_tokens,
-				tokensAfter,
-				restoredFromCompactionId: compactionId
-			}
-		});
+		const compactedCount = remainingEntries.filter((entry) => entry.entry_kind === "compaction").length;
 		const now = Date.now();
 		db.prepare(`UPDATE sessions SET
         message_count = ?,
         estimated_tokens = ?,
-        compacted_count = compacted_count + 1,
+        compacted_count = ?,
         updated_at = ?,
         last_accessed_at = ?,
         last_interaction_at = ?
-      WHERE session_key = ?`).run(restoredMessages.length, tokensAfter, now, now, now, sessionKey);
+      WHERE session_key = ?`).run(restoredMessages.length, tokensAfter, compactedCount, now, now, now, sessionKey);
 	});
 }
 //#endregion
-export { appendCompactionBoundary, appendTranscriptEntry, listCompactionBoundaries, loadLlmMessagesForSession, loadTranscriptHistoryRowsForSession, loadTranscriptRows, loadTranscriptRowsForSession, paginateTranscriptMessages, replaceTranscriptRows, restoreBeforeCompactionBoundary };
+export { appendCompactionBoundaryIfUnchanged, appendTranscriptEntry, listCompactionBoundaries, loadCompactionSourceSnapshot, loadLlmMessagesForSession, loadTranscriptHistoryRowsForSession, loadTranscriptRows, loadTranscriptRowsForSession, paginateTranscriptMessages, replaceTranscriptRows, restoreBeforeCompactionBoundary, searchSessionTranscript };

package/dist/src/user-context/config.d.ts

@@ -17,6 +17,7 @@ export declare const DEFAULT_CONTEXT_COMPACTION_POLICY: {
     summaryTimeoutMs: number;
     summaryRetries: number;
     qualityGuard: boolean;
+    gapAudit: boolean;
     minToolResultKeepChars: number;
     maxActiveTranscriptBytes: number;
     postCompactionSections: string[];
@@ -33,6 +34,7 @@ export declare const ContextCompactionPolicySchema: z.ZodDefault<z.ZodObject<{
     summaryTimeoutMs: z.ZodDefault<z.ZodNumber>;
     summaryRetries: z.ZodDefault<z.ZodNumber>;
     qualityGuard: z.ZodDefault<z.ZodBoolean>;
+    gapAudit: z.ZodDefault<z.ZodBoolean>;
     model: z.ZodOptional<z.ZodString>;
     minToolResultKeepChars: z.ZodDefault<z.ZodNumber>;
     maxActiveTranscriptBytes: z.ZodDefault<z.ZodNumber>;
@@ -81,6 +83,7 @@ export declare const UserMemoryConfigSchema: z.ZodDefault<z.ZodObject<{
             summaryTimeoutMs: z.ZodDefault<z.ZodNumber>;
             summaryRetries: z.ZodDefault<z.ZodNumber>;
             qualityGuard: z.ZodDefault<z.ZodBoolean>;
+            gapAudit: z.ZodDefault<z.ZodBoolean>;
             model: z.ZodOptional<z.ZodString>;
             minToolResultKeepChars: z.ZodDefault<z.ZodNumber>;
             maxActiveTranscriptBytes: z.ZodDefault<z.ZodNumber>;
@@ -188,6 +191,7 @@ export declare const UserContextConfigSchema: z.ZodDefault<z.ZodObject<{
                 summaryTimeoutMs: z.ZodDefault<z.ZodNumber>;
                 summaryRetries: z.ZodDefault<z.ZodNumber>;
                 qualityGuard: z.ZodDefault<z.ZodBoolean>;
+                gapAudit: z.ZodDefault<z.ZodBoolean>;
                 model: z.ZodOptional<z.ZodString>;
                 minToolResultKeepChars: z.ZodDefault<z.ZodNumber>;
                 maxActiveTranscriptBytes: z.ZodDefault<z.ZodNumber>;

package/dist/src/user-context/config.js

@@ -31,6 +31,7 @@ var init_config = __esmMin((() => {
 		summaryTimeoutMs: 18e4,
 		summaryRetries: 2,
 		qualityGuard: true,
+		gapAudit: true,
 		minToolResultKeepChars: 1e3,
 		maxActiveTranscriptBytes: 2e6,
 		postCompactionSections: ["Session Startup", "Red Lines"]
@@ -47,6 +48,7 @@ var init_config = __esmMin((() => {
 		summaryTimeoutMs: z.number().int().min(1e3).max(6e5).default(18e4),
 		summaryRetries: z.number().int().min(0).max(5).default(2),
 		qualityGuard: z.boolean().default(true),
+		gapAudit: z.boolean().default(true),
 		model: z.string().min(1).optional(),
 		minToolResultKeepChars: z.number().int().min(200).default(1e3),
 		maxActiveTranscriptBytes: z.number().int().min(64e3).default(2e6),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xopcai/xopc",
-  "version": "0.0.206",
+  "version": "0.0.207",
   "description": "Local-first AI system that remembers context, coordinates AI, and sustains long-term progress.",
   "type": "module",
   "main": "dist/src/index.js",
@@ -38,7 +38,7 @@
     "desktop",
     "extensions",
     "gateway",
-    "goal-loop-os",
+    "task-loop-os",
     "llm",
     "local-first",
     "mcp",
@@ -164,8 +164,8 @@
     "vitest": "4.1.5",
     "vue": "^3.5.35",
     "@xopcai/endpoint-tools-protocol": "0.0.0",
-    "@xopcai/realtime-protocol": "0.0.0",
     "@xopcai/gateway-contract": "0.0.0",
+    "@xopcai/realtime-protocol": "0.0.0",
     "@xopcai/realtime-client": "0.0.0"
   },
   "scripts": {

package/skills/THIRD_PARTY_NOTICES.md

@@ -4,7 +4,7 @@ The skills in this directory are maintained as part of xopc.
 
 ## 2026-07 built-in capability packs
 
-- `engineering/define-goal` and `creative/algorithmic-art` were designed after reviewing
+- `engineering/define-task` and `creative/algorithmic-art` were designed after reviewing
   Apache-2.0-licensed reference material supplied during product planning. Their instructions and
   assets in this repository were written independently for xopc; no reference files or branding
   are redistributed here.

package/skills/engineering/define-task/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: define-task
+description: Define, create, or refine an explicitly requested persistent xopc Task with a verifiable Task Contract; do not use for ordinary one-off work.
+metadata:
+  xopc:
+    emoji: "🎯"
+    requires_tools:
+      - xopc_use
+      - tool_manual
+---
+
+# Task definition
+
+Use this skill only when the user explicitly asks to define, capture, create, or refine a persistent
+xopc Task. Complete ordinary implementation and one-off requests directly without creating a Task.
+
+## Build the Task Contract
+
+Express the requested result through the current Task Contract fields:
+
+- `objective`: the observable result;
+- `expectedOutputs`: concrete deliverables;
+- `acceptanceCriteria`: checks that prove completion;
+- `constraints`: material boundaries, prohibitions, or required conditions.
+
+Preserve user-stated assumptions, risks, approval requirements, priority, Project association, and
+dependencies when they are available. Do not invent authority or success criteria that materially
+change the request.
+
+## Persist safely
+
+1. Use repository and conversation context to make the contract concrete.
+2. Ask one concise question only when a missing result, acceptance criterion, or boundary would
+   materially change the Task.
+3. Load the `xopc_use` manual before a non-trivial Task mutation.
+4. List and inspect current Tasks before creating one when duplication is plausible. Refine a
+   matching Task through its typed lifecycle instead of creating a competing Task.
+5. Use `createMode: "capture"` unless the user explicitly wants execution to start now. Use
+   `createMode: "start"` only for authorized immediate execution.
+6. Read the current Task version before revising an existing contract, and preserve fields the user
+   did not ask to change because contract revision replaces the complete contract.
+7. Verify the returned Task and report its delivery link when one is provided.
+
+For bugs, include a reproducer and regression check. For performance work, name the metric,
+threshold, method, and run count. For research, name the decision the research must enable and the
+evidence standard.
+
+Read `references/task-contract-rubric.md` when the Task needs a more careful contract review.

package/skills/engineering/define-task/references/task-contract-rubric.md

@@ -0,0 +1,15 @@
+# Define-task contract rubric
+
+Review the Task Contract against these questions:
+
+1. What observable result belongs in `objective`?
+2. Which concrete artifacts or state changes belong in `expectedOutputs`?
+3. Which binary or measurable checks belong in `acceptanceCriteria`?
+4. Which scope boundaries, prohibitions, or required conditions belong in `constraints`?
+5. Does execution require an approval, dependency, credential, or user decision that must be
+   represented before work starts?
+6. Is there already a matching Task that should be inspected or refined instead of duplicated?
+7. Should the Task be captured for later or explicitly started now?
+
+Prefer inspectable evidence: a test passes, an artifact exists, a measured threshold is met, a report
+supports a named decision, or a reviewer accepts stated criteria.