@namzu/sdk 62.1.0 → 62.2.1

package/src/runtime/query/index.ts

@@ -7,6 +7,7 @@ import {
 } from '../../advisory/index.js'
 import { AuthorizationGate } from '../../authorization/gate.js'
 import { SkillGrantSet } from '../../authorization/skill-grant.js'
+import type { ConsolidationScreen } from '../../compaction/consolidation.js'
 import { repairToolMessageHistory, toolHistoryRepairChanged } from '../../compaction/dangling.js'
 import { extractFromUserMessage } from '../../compaction/extractor.js'
 import { WorkingStateManager } from '../../compaction/manager.js'
@@ -963,6 +964,13 @@ export interface QueryParams {
 	 */
 	consolidateInto?: MemoryStore
 
+	/**
+	 * What a consolidation may quote. Absent keeps the task, decisions,
+	 * discoveries and failures verbatim; a host whose store is recalled into
+	 * later prompts sets it to drop or neutralise what should not persist.
+	 */
+	consolidationScreen?: ConsolidationScreen
+
 	/**
 	 * Optional neutral working-memory seam. When set, the iteration loop
 	 * re-renders the provider's string into a single pinned leading system

package/src/store/index.ts

@@ -37,6 +37,8 @@ export {
 	isMemoryName,
 	slugifyMemoryName,
 } from './memory/naming.js'
+export { findSecretShape } from './memory/secrets.js'
+export type { SecretScanOptions, SecretShape } from './memory/secrets.js'
 export type { MemoryContentRejection } from './memory/naming.js'
 export { MemoryRevisionConflictError } from './memory/revision.js'
 

package/src/store/memory/secrets.ts

@@ -0,0 +1,105 @@
+/**
+ * Secret shapes: text that looks like a credential and must not be written to
+ * a memory. A memory is recalled into later prompts, sent to providers and
+ * kept on disk in the clear, so a key saved once is a key leaked many times.
+ *
+ * The match is on shape only. It names a reason code and never returns the
+ * matched text, so a caller can log the code without logging the secret.
+ */
+
+export type SecretShape =
+	| 'private_key'
+	| 'provider_token'
+	| 'jwt'
+	| 'credentialed_url'
+	| 'high_entropy'
+
+const PATTERNS: readonly (readonly [SecretShape, RegExp])[] = [
+	['private_key', /-----BEGIN [A-Z ]*PRIVATE KEY(?: BLOCK)?-----/],
+	[
+		'provider_token',
+		new RegExp(
+			[
+				'\\bsk-(?:ant-|proj-|live-|or-v1-)?[A-Za-z0-9_-]{20,}',
+				'\\bgh[pousr]_[A-Za-z0-9]{30,}',
+				'\\bgithub_pat_[A-Za-z0-9_]{30,}',
+				'\\bglpat-[A-Za-z0-9_-]{16,}',
+				'\\bxox[abposr]-[A-Za-z0-9-]{10,}',
+				'\\b(?:AKIA|ASIA)[A-Z0-9]{16}\\b',
+				'\\bAIza[A-Za-z0-9_-]{35}\\b',
+				'\\bnvapi-[A-Za-z0-9_-]{20,}',
+				'\\bnpm_[A-Za-z0-9]{30,}',
+				'\\b[sr]k_(?:live|test)_[A-Za-z0-9]{16,}',
+				'\\bSG\\.[A-Za-z0-9_-]{16,}\\.[A-Za-z0-9_-]{16,}',
+				'\\bhf_[A-Za-z0-9]{30,}',
+				'\\bBearer\\s+[A-Za-z0-9._~+/-]{24,}=*',
+			].join('|'),
+		),
+	],
+	['jwt', /\beyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/],
+	['credentialed_url', /\b[a-z][a-z0-9+.-]*:\/\/[^\s/:@]+:[^\s/@]+@[^\s/]+/i],
+]
+
+/** Shannon entropy of `text`, in bits per character. */
+function entropy(text: string): number {
+	const counts = new Map<string, number>()
+	for (const ch of text) counts.set(ch, (counts.get(ch) ?? 0) + 1)
+	let bits = 0
+	for (const n of counts.values()) {
+		const p = n / text.length
+		bits -= p * Math.log2(p)
+	}
+	return bits
+}
+
+/** How many times the token switches between a letter and a digit. */
+function letterDigitSwitches(token: string): number {
+	let switches = 0
+	let previous: 'letter' | 'digit' | undefined
+	for (const ch of token) {
+		const kind = /\d/.test(ch) ? 'digit' : /[A-Za-z]/.test(ch) ? 'letter' : undefined
+		if (kind === undefined) continue
+		if (previous !== undefined && previous !== kind) switches += 1
+		previous = kind
+	}
+	return switches
+}
+
+/**
+ * Random, not merely long: a long identifier with a trailing number
+ * (`DecisionsAbcDefGhi1234567890`) has mixed case and a digit but few
+ * letter-digit switches and a low spread, a key has both. A path-like token
+ * is a path.
+ */
+function looksRandom(token: string): boolean {
+	return (
+		!token.includes('/') &&
+		/[A-Z]/.test(token) &&
+		/[a-z]/.test(token) &&
+		letterDigitSwitches(token) >= 4 &&
+		entropy(token) >= 4.5
+	)
+}
+
+export interface SecretScanOptions {
+	/**
+	 * Also flag a long unbroken run of mixed-case letters and digits that looks
+	 * random. Off by default: it can flag an identifier a person meant to keep,
+	 * which is right for text nobody chose and wrong for text somebody did.
+	 */
+	readonly entropy?: boolean
+}
+
+/** The first secret shape `text` has, or `undefined`. */
+export function findSecretShape(
+	text: string,
+	options: SecretScanOptions = {},
+): SecretShape | undefined {
+	for (const [shape, pattern] of PATTERNS) if (pattern.test(text)) return shape
+	if (options.entropy === true) {
+		for (const token of text.match(/[A-Za-z0-9+/_=-]{32,}/g) ?? []) {
+			if (looksRandom(token)) return 'high_entropy'
+		}
+	}
+	return undefined
+}

package/src/tools/memory/save.ts

@@ -5,6 +5,7 @@ import type { MemoryStore } from '../../types/memory/index.js'
 import type { ToolDefinition } from '../../types/tool/index.js'
 import { defineTool } from '../defineTool.js'
 import { memoryFieldsSchema } from './fields.js'
+import { refuseSecret } from './secret-guard.js'
 
 export function buildSaveMemoryTool(store: MemoryStore): ToolDefinition {
 	return defineTool({
@@ -13,6 +14,7 @@ export function buildSaveMemoryTool(store: MemoryStore): ToolDefinition {
 			'Save one memory for later sessions in this project: a single fact that the code, the history and the docs do not already hold.',
 			'Choose a type: user (who the person is and how they like to work), feedback (a rule they gave about how to work), project (a fact or decision about the work), reference (where to look for something).',
 			'For feedback and project memories, write the rule or fact first, then a line starting "Why:" and a line starting "How to apply:".',
+			'Never save a secret: an API key, token, password, private key or a URL with credentials in it is refused.',
 			'Link a related memory by writing [[its-name]] in the content.',
 			'The name must be new: a name another memory holds is refused, and the reply points to update_memory.',
 			"Returns the saved memory's id and name.",
@@ -30,6 +32,8 @@ export function buildSaveMemoryTool(store: MemoryStore): ToolDefinition {
 		destructive: false,
 		concurrencySafe: true,
 		async execute({ title, summary, content, tags, name, description, type }, context) {
+			const refused = refuseSecret([title, summary, content, description, ...(tags ?? [])])
+			if (refused) return refused
 			try {
 				const { entry } = await store.create({
 					title,

package/src/tools/memory/secret-guard.ts

@@ -0,0 +1,23 @@
+import { findSecretShape } from '../../store/memory/secrets.js'
+import type { ToolResult } from '../../types/tool/index.js'
+
+/**
+ * A refusal when any field a model is saving holds a secret, else `undefined`.
+ * The reply names the shape, never the text, so the refusal does not repeat
+ * the secret into the transcript.
+ */
+export function refuseSecret(fields: readonly (string | undefined)[]): ToolResult | undefined {
+	for (const field of fields) {
+		if (field === undefined) continue
+		const shape = findSecretShape(field)
+		if (shape === undefined) continue
+		return {
+			success: false,
+			output:
+				'The memory looks like it contains a secret (an API key, token, password, private key or a URL with credentials). Memories are recalled into later prompts and kept on disk in the clear, so it was not saved. Save where the secret lives (the variable or file name) instead of its value.',
+			error: 'Memory content rejected',
+			data: { reason: 'secret', shape },
+		}
+	}
+	return undefined
+}

package/src/tools/memory/update.ts

@@ -7,6 +7,7 @@ import type { ToolDefinition } from '../../types/tool/index.js'
 import { defineTool } from '../defineTool.js'
 import { memoryFieldsSchema } from './fields.js'
 import { resolveMemoryReference } from './resolve.js'
+import { refuseSecret } from './secret-guard.js'
 
 export function buildUpdateMemoryTool(store: MemoryStore): ToolDefinition {
 	return defineTool({
@@ -52,6 +53,14 @@ export function buildUpdateMemoryTool(store: MemoryStore): ToolDefinition {
 					error: 'Conditional memory update unavailable',
 				}
 			}
+			const refused = refuseSecret([
+				updates.title,
+				updates.summary,
+				updates.content,
+				updates.description,
+				...(updates.tags ?? []),
+			])
+			if (refused) return refused
 			const reference = await resolveMemoryReference(store, id)
 			if (!reference.found) {
 				return {

package/src/turn/index.ts

@@ -22,7 +22,7 @@ export { checkLimitsDetailed, buildLimitConfig } from './LimitChecker.js'
 export type { LimitCheckerState, LimitCheckResult } from './LimitChecker.js'
 
 export { SESSION_MEMORY_TAG, createMemoryPromoter } from './memory-promoter.js'
-export type { MemoryPromoterOptions } from './memory-promoter.js'
+export type { MemoryPromoterOptions, SessionMemoryCategory } from './memory-promoter.js'
 export { createMemoryRecallStep } from './memory-recall.js'
 export type { MemoryRecallOptions } from './memory-recall.js'
 export { createJsonClaimVerifier } from './json-claim-verifier.js'

package/src/turn/memory-promoter.ts

@@ -55,17 +55,33 @@ export interface MemoryPromoterOptions {
 	 * that costs context every time it is retrieved.
 	 */
 	readonly maxPerCategory?: number
+	/**
+	 * Decide whether one extracted claim may become part of a record. Called
+	 * with the candidate's category (`userRequirements`, `decisions`,
+	 * `discoveries`, `failures` or `environment`) and the claim text. A claim
+	 * it rejects is left out; a record with no claim left is not written.
+	 * Defaults to keeping every claim.
+	 */
+	readonly acceptClaim?: (category: SessionMemoryCategory, text: string) => boolean
 }
 
+/** The claim categories of a {@link SessionMemoryCandidate}. */
+export type SessionMemoryCategory = (typeof KNOWLEDGE)[number][0]
+
 /** Everything the candidate knows, as `[heading, items]`, empties dropped. */
 function knowledge(
 	candidate: SessionMemoryCandidate,
 	cap: number,
+	accept: (category: SessionMemoryCategory, text: string) => boolean,
 ): readonly (readonly [string, readonly string[]])[] {
 	const out: (readonly [string, readonly string[]])[] = []
 	for (const [key, heading] of KNOWLEDGE) {
 		const items = [
-			...new Set((candidate[key] as readonly string[]).map((item) => item.trim()).filter(Boolean)),
+			...new Set(
+				(candidate[key] as readonly string[])
+					.map((item) => item.trim())
+					.filter((item) => item !== '' && accept(key, item)),
+			),
 		]
 		if (items.length > 0) out.push([heading, items.slice(0, cap)])
 	}
@@ -115,10 +131,11 @@ export function createMemoryPromoter(options: MemoryPromoterOptions): PromoteMem
 	const cap = options.maxPerCategory ?? 20
 	if (!Number.isSafeInteger(cap) || cap < 1)
 		throw new Error('maxPerCategory must be a positive integer')
+	const accept = options.acceptClaim ?? (() => true)
 	const tags = [SESSION_MEMORY_TAG, ...(options.tags ?? [])]
 
 	return async (candidate: SessionMemoryCandidate): Promise<void> => {
-		const sections = knowledge(candidate, cap)
+		const sections = knowledge(candidate, cap, accept)
 		// Nothing learned, nothing written. Not an empty record: a store full
 		// of rows describing runs that discovered nothing is a store whose
 		// search results are mostly noise, and the model reads that store.