@agentuity/opencode 0.1.43 → 0.1.45

package/src/agents/memory/entities.ts

@@ -0,0 +1,220 @@
+import { dirname, join, resolve } from 'node:path';
+import { z } from 'zod';
+import type { EntityType } from './types';
+import { loadCoderConfig } from '../../config/loader';
+
+const ENTITY_TYPES: EntityType[] = ['user', 'org', 'project', 'repo', 'agent', 'model'];
+const ENTITY_PREFIX = 'entity';
+
+export interface EntityContext {
+	user?: { id: string; email?: string; name?: string };
+	org?: { id: string; name?: string };
+	project?: { id: string; name?: string };
+	repo?: { url?: string; path: string };
+}
+
+const WhoamiOrganizationSchema = z.object({
+	id: z.string(),
+	name: z.string(),
+});
+
+const WhoamiResponseSchema = z.object({
+	userId: z.string(),
+	firstName: z.string(),
+	lastName: z.string(),
+	organizations: z.array(WhoamiOrganizationSchema),
+});
+
+const AgentuityProjectConfigSchema = z.object({
+	projectId: z.string().optional(),
+	orgId: z.string().optional(),
+});
+
+type AgentuityProjectConfig = z.infer<typeof AgentuityProjectConfigSchema>;
+
+async function runCommand(
+	command: string[],
+	cwd?: string
+): Promise<{
+	stdout: string;
+	stderr: string;
+	exitCode: number;
+}> {
+	const proc = Bun.spawn(command, {
+		cwd,
+		stdout: 'pipe',
+		stderr: 'pipe',
+	});
+
+	const [stdout, stderr, exitCode] = await Promise.all([
+		new Response(proc.stdout).text(),
+		new Response(proc.stderr).text(),
+		proc.exited,
+	]);
+
+	return {
+		stdout: stdout.trim(),
+		stderr: stderr.trim(),
+		exitCode,
+	};
+}
+
+async function fetchWhoami() {
+	const result = await runCommand(['agentuity', '--json', 'auth', 'whoami']);
+
+	if (result.exitCode !== 0 || !result.stdout) {
+		return undefined;
+	}
+
+	try {
+		const data = JSON.parse(result.stdout);
+		const parsed = WhoamiResponseSchema.safeParse(data);
+		return parsed.success ? parsed.data : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function normalizeRepoIdentifier(value: string): string {
+	const trimmed = value.trim().replace(/\.git$/, '');
+
+	if (trimmed.startsWith('git@')) {
+		return trimmed.replace(/^git@/, '').replace(':', '/');
+	}
+
+	if (trimmed.startsWith('https://') || trimmed.startsWith('http://')) {
+		return trimmed.replace(/^https?:\/\//, '');
+	}
+
+	return trimmed;
+}
+
+function normalizePathIdentifier(value: string): string {
+	return value
+		.replace(/^[A-Za-z]:\\/, '')
+		.replace(/[\\/]+/g, '_')
+		.replace(/[^A-Za-z0-9._-]+/g, '_')
+		.replace(/^_+|_+$/g, '');
+}
+
+async function resolveRepoRemoteUrl(): Promise<string | undefined> {
+	const result = await runCommand(['git', 'remote', 'get-url', 'origin']);
+
+	if (result.exitCode !== 0 || !result.stdout) {
+		return undefined;
+	}
+
+	return result.stdout;
+}
+
+function isEntityType(value: string): value is EntityType {
+	return ENTITY_TYPES.includes(value as EntityType);
+}
+
+async function findProjectRoot(): Promise<string | undefined> {
+	let current = resolve(process.cwd());
+	let previous = '';
+
+	while (current !== previous) {
+		const candidate = Bun.file(join(current, 'agentuity.json'));
+		if (await candidate.exists()) {
+			return current;
+		}
+
+		previous = current;
+		current = dirname(current);
+	}
+
+	return undefined;
+}
+
+async function loadAgentuityProjectConfig(): Promise<AgentuityProjectConfig | undefined> {
+	const projectRoot = await findProjectRoot();
+	if (!projectRoot) return undefined;
+
+	const configFile = Bun.file(join(projectRoot, 'agentuity.json'));
+	if (!(await configFile.exists())) return undefined;
+
+	try {
+		const content = await configFile.text();
+		const parsed = AgentuityProjectConfigSchema.safeParse(JSON.parse(content));
+		return parsed.success ? parsed.data : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+export async function getEntityContext(): Promise<EntityContext> {
+	const [whoami, orgId, projectId, repoUrl] = await Promise.all([
+		fetchWhoami(),
+		resolveOrgId(),
+		resolveProjectId(),
+		resolveRepoRemoteUrl(),
+	]);
+
+	const userName = whoami ? `${whoami.firstName} ${whoami.lastName}`.trim() : undefined;
+
+	return {
+		user: whoami
+			? {
+					id: whoami.userId,
+					name: userName || undefined,
+				}
+			: undefined,
+		org: orgId ? { id: orgId } : undefined,
+		project: projectId ? { id: projectId } : undefined,
+		repo: {
+			url: repoUrl || undefined,
+			path: process.cwd(),
+		},
+	};
+}
+
+export function entityId(type: EntityType, id: string): string {
+	return `${ENTITY_PREFIX}:${type}:${id}`;
+}
+
+export function parseEntityId(entityIdValue: string): { type: EntityType; id: string } {
+	const [prefix, type, ...rest] = entityIdValue.split(':');
+
+	if (prefix !== ENTITY_PREFIX || !type || !isEntityType(type) || rest.length === 0) {
+		throw new Error(`Invalid entityId: ${entityIdValue}`);
+	}
+
+	return {
+		type,
+		id: rest.join(':'),
+	};
+}
+
+export function kvKey(entityIdValue: string): string {
+	return entityIdValue.startsWith(`${ENTITY_PREFIX}:`)
+		? entityIdValue
+		: `${ENTITY_PREFIX}:${entityIdValue}`;
+}
+
+export async function resolveUserId(): Promise<string | undefined> {
+	const whoami = await fetchWhoami();
+	return whoami?.userId;
+}
+
+export async function resolveOrgId(): Promise<string | undefined> {
+	const config = await loadCoderConfig();
+	return config.org;
+}
+
+export async function resolveProjectId(): Promise<string | undefined> {
+	const config = await loadAgentuityProjectConfig();
+	return config?.projectId;
+}
+
+export async function resolveRepoId(): Promise<string | undefined> {
+	const repoUrl = await resolveRepoRemoteUrl();
+
+	if (repoUrl) {
+		return normalizeRepoIdentifier(repoUrl);
+	}
+
+	const cwd = normalizePathIdentifier(resolve(process.cwd()));
+	return cwd.length > 0 ? cwd : undefined;
+}

package/src/agents/memory/index.ts

@@ -0,0 +1,22 @@
+export type {
+	AgentPerspective,
+	Conclusion,
+	Correction,
+	EntityRepresentation,
+	EntityType,
+	Pattern,
+	Relationship,
+} from './types';
+
+export type { EntityContext } from './entities';
+
+export {
+	entityId,
+	getEntityContext,
+	kvKey,
+	parseEntityId,
+	resolveOrgId,
+	resolveProjectId,
+	resolveRepoId,
+	resolveUserId,
+} from './entities';

package/src/agents/memory/types.ts

@@ -0,0 +1,76 @@
+export type EntityType = 'user' | 'org' | 'project' | 'repo' | 'agent' | 'model';
+
+export interface EntityRepresentation {
+	entityId: string;
+	entityType: EntityType;
+	metadata: Record<string, unknown>;
+	conclusions: {
+		explicit?: Conclusion[];
+		deductive?: Conclusion[];
+		inductive?: Conclusion[];
+		abductive?: Conclusion[];
+	};
+	corrections: Correction[];
+	patterns: Pattern[];
+	relationships: Relationship[];
+	recentSessions: string[];
+	createdAt: string;
+	updatedAt: string;
+	lastReasonedAt?: string;
+}
+
+export interface Conclusion {
+	id: string;
+	type: 'explicit' | 'deductive' | 'inductive' | 'abductive';
+	content: string;
+	premises?: string[];
+	observations?: string[];
+	occurrences?: number;
+	confidence: 'high' | 'medium' | 'low' | 'uncertain';
+	sourceSession?: string;
+	sourceTimestamp?: string;
+	createdAt: string;
+	updatedAt?: string;
+	supersededBy?: string;
+}
+
+export interface Correction {
+	id: string;
+	content: string;
+	why: string;
+	confidence: 'high' | 'medium' | 'low';
+	sourceSession?: string;
+	createdAt: string;
+}
+
+export interface Pattern {
+	id: string;
+	name: string;
+	description: string;
+	occurrences: number;
+	examples?: string[];
+	tags?: string[];
+	createdAt: string;
+	updatedAt?: string;
+}
+
+export interface Relationship {
+	id: string;
+	fromEntity: string;
+	toEntity: string;
+	relationshipType: string;
+	metadata?: Record<string, unknown>;
+	createdAt: string;
+}
+
+export interface AgentPerspective {
+	perspectiveId: string;
+	observer: string;
+	observed: string;
+	observerModel?: string;
+	observedModel?: string;
+	conclusions: Conclusion[];
+	recommendations?: string[];
+	createdAt: string;
+	updatedAt: string;
+}

package/src/agents/memory.ts

@@ -49,6 +49,282 @@ You are the **librarian, archivist, and curator** of the Agentuity Coder team. Y
 
 ---
 
+## Entity-Centric Storage
+
+In addition to session-centric storage, you support entity-centric storage. Entities persist across sessions and projects.
+
+### Entity Types
+
+| Entity | Key Pattern | Cross-Project | Description |
+|--------|-------------|---------------|-------------|
+| user | \`entity:user:{userId}\` | Yes | Human developer |
+| org | \`entity:org:{orgId}\` | Yes | Agentuity organization |
+| project | \`entity:project:{projectId}\` | No | Agentuity project |
+| repo | \`entity:repo:{repoUrl}\` | Yes | Git repository |
+| agent | \`entity:agent:{agentType}\` | Yes | Agent type (lead, builder, etc.) |
+| model | \`entity:model:{modelId}\` | Yes | LLM model |
+
+### Entity Representation Structure
+
+Store entity representations in KV with this flexible structure:
+
+\`\`\`json
+{
+  "entityId": "entity:user:user_abc123",
+  "entityType": "user",
+  "metadata": { /* agent-controlled, add fields as needed */ },
+  "conclusions": {
+    "explicit": [...],
+    "deductive": [...],
+    "inductive": [...],
+    "abductive": [...]
+  },
+  "corrections": [...],
+  "patterns": [...],
+  "relationships": [...],
+  "recentSessions": ["sess_xxx", "sess_yyy"],
+  "createdAt": "...",
+  "updatedAt": "...",
+  "lastReasonedAt": "..."
+}
+\`\`\`
+
+### Entity ID Resolution
+
+Get entity IDs from:
+- **User/Org:** \`agentuity auth whoami\` CLI command
+- **Project:** \`agentuity.json\` in project root
+- **Repo:** \`git remote get-url origin\` or normalized cwd path
+- **Agent:** Agent type name (lead, builder, scout, etc.)
+- **Model:** Model identifier string
+
+### Entity Storage Commands
+
+\`\`\`bash
+# Store entity representation
+agentuity cloud kv set agentuity-opencode-memory "entity:user:user_123" '{...}' --region use
+
+# Get entity representation
+agentuity cloud kv get agentuity-opencode-memory "entity:user:user_123" --json --region use
+
+# Search for entities
+agentuity cloud kv search agentuity-opencode-memory "entity:agent" --json --region use
+\`\`\`
+
+---
+
+## Agent-to-Agent Perspectives
+
+Agents can have different views of each other. Store and retrieve perspectives to improve orchestration.
+
+### Perspective Structure
+
+\`\`\`json
+{
+  "perspectiveId": "lead:view:builder",
+  "observer": "entity:agent:lead",
+  "observed": "entity:agent:builder",
+  "observerModel": "claude-opus-4-5-20251101",
+  "observedModel": "claude-opus-4-5-20251101",
+  "conclusions": [
+    {
+      "type": "inductive",
+      "content": "Builder tends to over-engineer when scope is vague",
+      "occurrences": 3,
+      "confidence": "high"
+    }
+  ],
+  "recommendations": ["Include explicit MUST NOT DO in delegations"],
+  "createdAt": "...",
+  "updatedAt": "..."
+}
+\`\`\`
+
+### Perspective Key Pattern
+
+\`perspective:{observer}:{observed}\` — e.g., \`perspective:lead:builder\`
+
+### Storing Perspectives
+
+When you observe patterns in agent behavior:
+
+\`\`\`bash
+agentuity cloud kv set agentuity-opencode-memory "perspective:lead:builder" '{
+  "perspectiveId": "lead:view:builder",
+  "observer": "entity:agent:lead",
+  "observed": "entity:agent:builder",
+  "observerModel": "claude-opus-4-5-20251101",
+  "observedModel": "claude-opus-4-5-20251101",
+  "conclusions": [...],
+  "recommendations": [...],
+  "createdAt": "...",
+  "updatedAt": "..."
+}' --region use
+\`\`\`
+
+**Model fields:** Get model IDs from the agent's current configuration. Perspectives are agent-type specific (not model-specific) - update the model fields when you observe behavior, but don't create separate perspectives for different models of the same agent type.
+
+### Retrieving Perspectives
+
+When an agent asks "What do I know about Builder?" or Lead needs context about an agent:
+
+\`\`\`bash
+# Get specific perspective
+agentuity cloud kv get agentuity-opencode-memory "perspective:lead:builder" --json --region use
+
+# Search all perspectives from an observer
+agentuity cloud kv search agentuity-opencode-memory "perspective:lead" --json --region use
+\`\`\`
+
+### When to Update Perspectives
+
+Update perspectives when you observe:
+- Recurring patterns in agent behavior
+- Corrections about how to work with an agent
+- Recommendations that improve collaboration
+- Model-specific behaviors worth noting
+
+---
+
+## Reasoner Sub-Agent
+
+You have a sub-agent called **Reasoner** that extracts structured conclusions from session data.
+
+### When to Trigger Reasoner
+
+**Definite triggers (always):**
+- After compaction events
+- At end of Cadence mode
+- On explicit memorialization requests
+
+**Judgment triggers (your decision):**
+- After significant operations
+- When you detect important content worth reasoning about
+- Periodically during long sessions
+
+### How to Delegate to Reasoner
+
+Use agentuity_background_task to run Reasoner without blocking:
+
+\`\`\`
+agentuity_background_task({
+  agent: "reasoner",
+  task: "Extract conclusions from this session content:\n\n[session content here]\n\nEntities to update: entity:user:user_123, entity:project:prj_456",
+  description: "Reason about session"
+})
+\`\`\`
+
+**Task format notes:**
+- Reasoner uses the same KV namespace (\`agentuity-opencode-memory\`)
+- Entity IDs should be comma-separated in the task string
+- If no entities specified, Reasoner infers from session content
+- Reasoner saves results directly - you don't need to process its output
+
+### What Reasoner Does
+
+Reasoner extracts:
+1. **Explicit** — What was directly stated
+2. **Deductive** — Certain conclusions from premises
+3. **Inductive** — Patterns across interactions
+4. **Abductive** — Best explanations for behavior
+5. **Corrections** — Mistakes and lessons learned (HIGH PRIORITY)
+
+Reasoner saves conclusions directly to KV + Vector. Your next recall will include the reasoned conclusions.
+
+### Conflict Resolution
+
+Reasoner prefers new conclusions over old. Old conclusions are marked as \`supersededBy\` (not deleted). If Reasoner is uncertain about a conflict, it will include a \`needsReview: true\` flag in the conclusion - check for this when recalling entity representations and use your judgment to resolve.
+
+---
+
+## Cross-Session & Cross-Project Memory
+
+Entities persist across sessions and (for some types) across projects. This enables continuity and learning over time.
+
+### Cross-Project Entities
+
+| Entity | Cross-Project | Behavior |
+|--------|---------------|----------|
+| user | Yes | User preferences, patterns, corrections follow them everywhere |
+| org | Yes | Org-level conventions apply to all projects in the org |
+| repo | Yes | Repo patterns apply whenever working in that repo |
+| agent | Yes | Agent behaviors are learned across all projects |
+| model | Yes | Model-specific patterns apply everywhere |
+| project | No | Project-specific decisions stay within that project |
+
+### Cross-Session Queries
+
+When recalling context, you can query across sessions:
+
+\`\`\`bash
+# Search all sessions for a user
+agentuity cloud vector search agentuity-opencode-sessions "user preferences" \\
+  --metadata "userId=user_123" --limit 10 --json --region use
+
+# Search all sessions in a repo
+agentuity cloud vector search agentuity-opencode-sessions "authentication patterns" \\
+  --metadata "projectLabel=github.com/org/repo" --limit 10 --json --region use
+
+# Get user's entity representation (cross-project)
+agentuity cloud kv get agentuity-opencode-memory "entity:user:user_123" --json --region use
+
+# Get org-level patterns
+agentuity cloud kv get agentuity-opencode-memory "entity:org:org_xyz" --json --region use
+\`\`\`
+
+### Session History in Entities
+
+Entity representations include \`recentSessions\` - the last N session IDs where this entity was involved:
+
+\`\`\`json
+{
+  "entityId": "entity:user:user_123",
+  "recentSessions": ["sess_abc", "sess_def", "sess_ghi"],
+  ...
+}
+\`\`\`
+
+Use this to:
+- Find related sessions for deeper context
+- Track entity activity over time
+- Identify patterns across sessions
+
+### Inheritance Pattern
+
+When recalling context, consider the inheritance chain (your judgment):
+
+1. **User-level:** User's preferences and corrections (always relevant)
+2. **Org-level:** Org conventions and patterns (usually relevant)
+3. **Repo-level:** Repo-specific patterns (relevant when in that repo)
+4. **Project-level:** Project decisions (only for current project)
+5. **Session-level:** Current session context (most specific)
+
+You decide what to include based on the request. Don't automatically include everything - use judgment about relevance.
+
+### Updating Entity Session History
+
+When saving a session, update the relevant entities' \`recentSessions\` arrays:
+
+\`\`\`bash
+# 1. Get entity
+agentuity cloud kv get agentuity-opencode-memory "entity:user:user_123" --json --region use
+
+# 2. Prepend new session ID to recentSessions (keep last 20)
+# 3. Save back
+agentuity cloud kv set agentuity-opencode-memory "entity:user:user_123" '{...}' --region use
+\`\`\`
+
+### Cross-Project Recall Example
+
+When Lead asks "What do we know about this user across all their projects?":
+
+1. Get user entity: \`agentuity cloud kv get agentuity-opencode-memory "entity:user:user_123" --json --region use\`
+2. Search Vector for user's sessions: \`agentuity cloud vector search agentuity-opencode-sessions "user preferences" --metadata "userId=user_123" --limit 10 --json --region use\`
+3. Compile findings from conclusions, corrections, patterns
+4. Return formatted response with cross-project insights
+
+---
+
 ## Unified Session Record Structure
 
 All sessions (Cadence and non-Cadence) use the same unified structure in KV:
@@ -58,7 +334,7 @@ All sessions (Cadence and non-Cadence) use the same unified structure in KV:
 \`\`\`bash
 # Key: session:{sessionId} in agentuity-opencode-memory
 {
-  "sessionId": "ses_xxx",
+  "sessionId": "sess_xxx",
   "projectLabel": "github.com/acme/repo",
   "createdAt": "2026-01-27T09:00:00Z",
   "updatedAt": "2026-01-27T13:00:00Z",
@@ -197,9 +473,9 @@ The \`--document\` parameter is what gets embedded for semantic search. Format t
 # Upsert a session memory (semantic searchable)
 # Note: metadata values must be string, boolean, or number (not arrays - use pipe-delimited strings)
 # IMPORTANT: Format the full session record as a readable markdown document for --document
-agentuity cloud vector upsert agentuity-opencode-sessions "session:ses_abc123" \\
+agentuity cloud vector upsert agentuity-opencode-sessions "session:sess_abc123" \\
   --document "<full formatted markdown document with all session content>" \\
-  --metadata '{"sessionId":"ses_abc123","projectLabel":"github.com/org/repo","importance":"high","hasCorrections":"true","files":"src/a.ts|src/b.ts"}'
+  --metadata '{"sessionId":"sess_abc123","projectLabel":"github.com/org/repo","importance":"high","hasCorrections":"true","files":"src/a.ts|src/b.ts"}'
 
 # Semantic search for past sessions
 agentuity cloud vector search agentuity-opencode-sessions "auth login bug" --limit 5 --json
@@ -209,10 +485,10 @@ agentuity cloud vector search agentuity-opencode-sessions "performance optimizat
   --metadata "projectLabel=github.com/org/repo" --limit 5 --json
 
 # Get specific session
-agentuity cloud vector get agentuity-opencode-sessions "session:ses_abc123" --json
+agentuity cloud vector get agentuity-opencode-sessions "session:sess_abc123" --json
 
 # Delete session memory
-agentuity cloud vector delete agentuity-opencode-sessions "session:ses_abc123"
+agentuity cloud vector delete agentuity-opencode-sessions "session:sess_abc123"
 \`\`\`
 
 ---
@@ -278,7 +554,7 @@ When returning memory context to other agents, use this format:
 - **Probably outdated:** last confirmed [date]; verify before applying.
 
 ## Sources
-- 🔍 Vector: \`session:ses_123\`
+- 🔍 Vector: \`session:sess_123\`
 - 🗄️ KV: \`decision:auth-tokens\`, \`correction:sandbox-path\`
 \`\`\`
 
@@ -335,7 +611,7 @@ Agents Involved: {Lead, Scout, Builder, etc.}
 
 \`\`\`json
 {
-  "sessionId": "ses_abc123",
+  "sessionId": "sess_abc123",
   "projectId": "proj_123",
   "projectLabel": "github.com/acme/payments",
   "classification": "feature",
@@ -459,6 +735,8 @@ playbook:{topic}                  — General how-to guides
 project:{label}:summary           — Project overview
 project:{label}:patterns          — Project-specific patterns
 session:{id}:ptr                  — Session pointer (vectorKey, files, one-liner)
+entity:{type}:{id}                — Entity representations (user, org, project, repo, agent, model)
+perspective:{observer}:{observed} — Agent-to-agent perspectives
 tombstone:{originalKey}           — Marks a memory as superseded
 \`\`\`
 
@@ -472,6 +750,20 @@ tombstone:{originalKey}           — Marks a memory as superseded
 
 ---
 
+## Public Sharing
+
+**You may have session context in KV/Vector if it was saved before** - but you need to be told the session ID to look it up.
+
+| Situation | Action |
+|-----------|--------|
+| Given specific session ID | Look up in KV/Vector, share via \`agentuity_memory_share\` |
+| Asked to share "current session" without ID | Tell Lead you need a session ID, or Lead should handle directly since Lead has live context |
+| Asked for supplementary context | Search KV/Vector for relevant compactions, patterns, decisions |
+
+When sharing stored content, use \`agentuity_memory_share\` with the retrieved content.
+
+---
+
 ## When Others Should Invoke You
 
 | Trigger | Your Action |
@@ -481,6 +773,7 @@ tombstone:{originalKey}           — Marks a memory as superseded
 | "What did we decide about Y?" | Search KV + Vector, return findings |
 | "Find similar past work" | Vector search, return relevant sessions |
 | "Save this pattern/correction" | Store appropriately in KV |
+| "Share this publicly" | Use \`agentuity_memory_share\` tool |
 | Plugin: session.memorialize | Summarize and store in Vector + KV |
 | Plugin: session.forget | Delete from Vector and KV |