chore: cleanup old agent-forum location
This commit is contained in:
parent
d455dd4582
commit
9cef5715d4
@ -1,41 +0,0 @@
|
||||
# Agent Forum v4 Assessment & Research Report
|
||||
|
||||
## 1. Overview & Usefulness
|
||||
|
||||
The `agent-forum-v4` blueprint outlines a "Git-Native Agent Collaboration Ecosystem." By shifting from flat Markdown files to structured data (YAML DAGs, SCIP indexes, local vector graphs), the protocol addresses a core limitation of modern AI agents: context window collapse and dependency amnesia.
|
||||
|
||||
**Solving the Pain Points:**
|
||||
You noted that agents frequently lose context and struggle to understand if they are fulfilling requirements without constant spoon-feeding. The proposed shift to a **Semantic Project Management** system directly solves this:
|
||||
- **Dependencies:** Instead of relying on an agent to read a folder and "figure out" what to do, the system uses strict YAML Directed Acyclic Graphs (DAGs). An Evaluator script mathematically determines the critical path. An agent is only ever handed an explicitly unblocked task.
|
||||
- **Context:** Instead of feeding the agent the entire codebase as raw text, the system uses Git Merkle DAG diffing and embedded SQLite vector search to feed the agent precisely the context it needs in milliseconds.
|
||||
|
||||
## 2. Compatibility with the Repository
|
||||
|
||||
The Auth-Yes repository is characterized by a strict, zero-dependency, hermetic environment prioritizing Deno, minimal external SaaS dependencies, and self-contained runtime operations.
|
||||
|
||||
- **High Alignment:** The agent-forum's philosophy of "Local-First / Git-Native" is in perfect harmony with your project's ethos. Eliminating third-party databases in favor of Git Notes and orphan branches ensures the protocol remains portable, cryptographically secure, and isolated.
|
||||
- **Implementation Challenges:** The blueprint relies heavily on advanced tooling (Tree-sitter, SCIP, `sqlite-vec`). Integrating these into a Deno environment without polluting the repository with heavy binary dependencies will require careful execution. We should lean towards WebAssembly (WASM) ports of these tools (e.g., `tree-sitter.wasm`, or Deno's native FFI for SQLite) to keep the repository lightweight.
|
||||
|
||||
## 3. Isolation Strategy (Preventing Bleed)
|
||||
|
||||
To ensure this new protocol does not interfere with the primary intent of Auth-Yes or other target projects, we must implement strict physical and logical boundaries:
|
||||
|
||||
1. **The `.forum/` (or `.agents/`) Namespace:** All protocol-specific files, state machines (`transitions.json`), schemas, and tooling scripts must be entirely contained within a hidden root directory (e.g., `.forum/`). The target repository should have zero awareness of these files.
|
||||
2. **Git Meta-State (Orphan Branches):** The most powerful isolation technique proposed is the use of an Orphan Branch. Dynamic state (telemetry, task completion status, graphs) will be committed to a branch (e.g., `forum/meta-state`) that shares no history with `main`. This ensures the primary branch's `git log` remains pristine and untouched by agent automation.
|
||||
3. **Git Notes for Meta-Thoughts:** By using custom Git Note refs (e.g., `refs/notes/forum/reasoning`), agents can attach vast amounts of JSON metadata, risk assessments, and historical context to a commit without altering the commit hash or the working directory tree.
|
||||
|
||||
## 4. Adapting the Legacy `/tasks` Workflow
|
||||
|
||||
You mentioned appreciating the file naming conventions (visual history), risk assessments, and meta-thoughts of the old system. The goal is to preserve the *value* of these features while upgrading their *format* to be machine-readable.
|
||||
|
||||
- **Visual History & Filenames:** We can retain the descriptive nomenclature (`YYYY-MMDD.[sequence]...[short-description]`) but use it as the **UUID/Key** inside the YAML DAGs rather than just a filename. To preserve the human visual experience, we can write a simple Deno script (`deno task forum:view`) that parses the DAG and orphan branch history to output a beautiful, interactive terminal UI (via Cliffy) or a generated HTML report showing the exact progression of work.
|
||||
- **Risk Assessment & Meta-Thoughts:** In the old system, these were markdown headers. In the new system, an "Adversary" agent will generate these risk assessments as structured JSON. We will store this JSON in **Git Notes** attached to the relevant commits. This ensures the data is tightly coupled to the code changes, never gets lost in a stale markdown file, and can be queried instantly by other agents.
|
||||
- **Human-Readable Projections:** If we ever need a standard Markdown view, a "Translator" agent or script can compile the DAGs, Git Notes, and ASTs and generate a static `tasks-report.md` on demand.
|
||||
|
||||
## 5. Proposed Experimental Path (Proof of Concept)
|
||||
|
||||
We will not build the fully automated loop yet. Instead, we will build foundational experiments in `scratch/agent-forum-experiments/` to verify the hard concepts:
|
||||
|
||||
1. **Git Storage PoC (`git_storage_poc.ts`):** Verify that Deno can programmatically read/write to Git Notes and manipulate an orphan branch without disrupting the current working tree. This proves we can store agent state invisibly.
|
||||
2. **DAG Engine PoC (`dag_engine_poc.ts`):** Create a minimal script that parses a YAML task graph, resolves dependencies (`blocked_by`), and mathematically outputs the exact next task an agent should work on.
|
||||
3. **Local Intelligence PoC (`code_intelligence_poc.ts`):** Experiment with lightweight semantic parsing (e.g., extracting exports or AST structure from a file) to prove we can feed agents structured code intelligence rather than raw strings.
|
||||
@ -1,104 +0,0 @@
|
||||
import { assertEquals } from "https://deno.land/std@0.224.0/testing/asserts.ts";
|
||||
|
||||
/**
|
||||
* Proof of Concept: Local Code Intelligence (AST Parsing)
|
||||
*
|
||||
* In the full implementation, this would use Tree-sitter WASM or SCIP.
|
||||
* For this Deno PoC, we will simulate the extraction of structured data
|
||||
* from raw code by building a lightweight regex-based scanner that
|
||||
* extracts exported function signatures. This proves the concept of
|
||||
* transforming "raw text" into "structured JSON context" for an agent.
|
||||
*/
|
||||
|
||||
export interface ExportSymbol {
|
||||
name: string;
|
||||
type: "function" | "class" | "const";
|
||||
signature: string;
|
||||
}
|
||||
|
||||
export function extractExports(sourceCode: string): ExportSymbol[] {
|
||||
const exports: ExportSymbol[] = [];
|
||||
|
||||
// A naive regex for PoC purposes to find exported functions
|
||||
// Matches: export function foo(bar: string): void {
|
||||
const functionRegex = /export\s+(?:async\s+)?function\s+([a-zA-Z0-9_]+)\s*\(([^)]*)\)(?:\s*:\s*([^ {]+))?/g;
|
||||
|
||||
let match;
|
||||
while ((match = functionRegex.exec(sourceCode)) !== null) {
|
||||
const name = match[1];
|
||||
const args = match[2].trim();
|
||||
const returnType = match[3] ? match[3].trim() : "any";
|
||||
|
||||
exports.push({
|
||||
name,
|
||||
type: "function",
|
||||
signature: `(${args}) => ${returnType}`,
|
||||
});
|
||||
}
|
||||
|
||||
// Matches: export const foo = ...
|
||||
const constRegex = /export\s+const\s+([a-zA-Z0-9_]+)\s*=/g;
|
||||
while ((match = constRegex.exec(sourceCode)) !== null) {
|
||||
exports.push({
|
||||
name: match[1],
|
||||
type: "const",
|
||||
signature: "const",
|
||||
});
|
||||
}
|
||||
|
||||
return exports;
|
||||
}
|
||||
|
||||
// In a real scenario, tests would be separated. For this PoC, we will run the tests here.
|
||||
if (import.meta.main) {
|
||||
console.log("Running Local Code Intelligence PoC tests...");
|
||||
|
||||
const mockSourceCode = `
|
||||
import { stuff } from "somewhere";
|
||||
|
||||
/**
|
||||
* Calculates a complex value.
|
||||
*/
|
||||
export async function calculateValue(input: number, mode: string): Promise<number> {
|
||||
return input * 2;
|
||||
}
|
||||
|
||||
// An internal helper
|
||||
function internalHelper() {
|
||||
return true;
|
||||
}
|
||||
|
||||
export const MAX_RETRIES = 5;
|
||||
|
||||
export function doSomethingElse(): void {
|
||||
console.log(MAX_RETRIES);
|
||||
}
|
||||
`;
|
||||
|
||||
try {
|
||||
const extracted = extractExports(mockSourceCode);
|
||||
|
||||
assertEquals(extracted.length, 3);
|
||||
|
||||
const calcFunc = extracted.find(e => e.name === "calculateValue");
|
||||
assertEquals(calcFunc?.type, "function");
|
||||
assertEquals(calcFunc?.signature, "(input: number, mode: string) => Promise<number>");
|
||||
|
||||
const maxRetries = extracted.find(e => e.name === "MAX_RETRIES");
|
||||
assertEquals(maxRetries?.type, "const");
|
||||
|
||||
const doSomething = extracted.find(e => e.name === "doSomethingElse");
|
||||
assertEquals(doSomething?.type, "function");
|
||||
assertEquals(doSomething?.signature, "() => void");
|
||||
|
||||
console.log("✅ Local Code Intelligence PoC successful: Extracted structured context from raw source.");
|
||||
|
||||
// Simulate what the agent would actually see:
|
||||
console.log("\n--- Agent Context Payload ---");
|
||||
console.log(JSON.stringify(extracted, null, 2));
|
||||
console.log("-----------------------------\n");
|
||||
|
||||
} catch (err) {
|
||||
console.error("❌ Local Code Intelligence PoC failed:", err);
|
||||
}
|
||||
}
|
||||
@ -1,105 +0,0 @@
|
||||
import { assertEquals } from "https://deno.land/std@0.224.0/testing/asserts.ts";
|
||||
import { parse } from "https://deno.land/std@0.224.0/yaml/mod.ts";
|
||||
|
||||
/**
|
||||
* Proof of Concept: Semantic Task DAG Engine
|
||||
*
|
||||
* This module demonstrates how we can parse a strict YAML Directed Acyclic Graph (DAG)
|
||||
* of tasks to calculate the critical path and ensure agents are only ever handed
|
||||
* explicitly unblocked tasks.
|
||||
*/
|
||||
|
||||
export interface TaskNode {
|
||||
id: string;
|
||||
title: string;
|
||||
blocked_by: string[];
|
||||
status: "pending" | "in-progress" | "complete";
|
||||
}
|
||||
|
||||
export class TaskDAG {
|
||||
private nodes: Map<string, TaskNode> = new Map();
|
||||
|
||||
constructor(yamlContent: string) {
|
||||
const rawNodes = parse(yamlContent) as TaskNode[];
|
||||
for (const node of rawNodes) {
|
||||
this.nodes.set(node.id, {
|
||||
...node,
|
||||
blocked_by: node.blocked_by || [],
|
||||
status: node.status || "pending",
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns a list of tasks that are fully unblocked and ready to be worked on.
|
||||
*/
|
||||
getUnblockedTasks(): TaskNode[] {
|
||||
const unblocked: TaskNode[] = [];
|
||||
for (const node of this.nodes.values()) {
|
||||
if (node.status === "complete") continue;
|
||||
|
||||
const isBlocked = node.blocked_by.some(
|
||||
(depId) => this.nodes.get(depId)?.status !== "complete"
|
||||
);
|
||||
|
||||
if (!isBlocked) {
|
||||
unblocked.push(node);
|
||||
}
|
||||
}
|
||||
return unblocked;
|
||||
}
|
||||
|
||||
markComplete(taskId: string) {
|
||||
const node = this.nodes.get(taskId);
|
||||
if (node) {
|
||||
node.status = "complete";
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// In a real scenario, tests would be separated. For this PoC, we will run the tests here.
|
||||
if (import.meta.main) {
|
||||
console.log("Running DAG Engine PoC tests...");
|
||||
|
||||
const yamlInput = `
|
||||
- id: task_1
|
||||
title: Setup Git Notes PoC
|
||||
status: complete
|
||||
- id: task_2
|
||||
title: Setup DAG Engine PoC
|
||||
blocked_by: [task_1]
|
||||
status: pending
|
||||
- id: task_3
|
||||
title: Setup Local Intelligence PoC
|
||||
blocked_by: [task_1, task_2]
|
||||
status: pending
|
||||
- id: task_4
|
||||
title: Write Assessment Report
|
||||
blocked_by: [task_1]
|
||||
status: pending
|
||||
`;
|
||||
|
||||
try {
|
||||
const dag = new TaskDAG(yamlInput);
|
||||
|
||||
// Initially, task_2 and task_4 should be unblocked because task_1 is complete.
|
||||
let unblocked = dag.getUnblockedTasks();
|
||||
assertEquals(unblocked.length, 2);
|
||||
assertEquals(unblocked[0].id, "task_2");
|
||||
assertEquals(unblocked[1].id, "task_4");
|
||||
|
||||
// Mark task_2 as complete. Now task_3 should still be blocked because task_4 has no effect,
|
||||
// wait, task_3 is blocked by task_1 and task_2. Since both will be complete, task_3 should unlock.
|
||||
dag.markComplete("task_2");
|
||||
unblocked = dag.getUnblockedTasks();
|
||||
|
||||
// Unblocked should now be task_3 and task_4
|
||||
assertEquals(unblocked.length, 2);
|
||||
assertEquals(unblocked.find(t => t.id === "task_3")?.id, "task_3");
|
||||
assertEquals(unblocked.find(t => t.id === "task_4")?.id, "task_4");
|
||||
|
||||
console.log("✅ DAG Engine PoC successful: Correctly calculated unblocked tasks.");
|
||||
} catch (err) {
|
||||
console.error("❌ DAG Engine PoC failed:", err);
|
||||
}
|
||||
}
|
||||
@ -1,71 +0,0 @@
|
||||
import { assert, assertEquals } from "https://deno.land/std@0.224.0/testing/asserts.ts";
|
||||
|
||||
/**
|
||||
* Proof of Concept: Git Storage (Notes & Orphan Branches)
|
||||
*
|
||||
* This module demonstrates how we can use Deno's `Deno.Command` API to interact
|
||||
* with Git Notes and Orphan Branches to store agent state and metadata without
|
||||
* polluting the main working tree.
|
||||
*/
|
||||
|
||||
async function runGitCmd(args: string[]): Promise<string> {
|
||||
const cmd = new Deno.Command("git", {
|
||||
args,
|
||||
stdout: "piped",
|
||||
stderr: "piped",
|
||||
});
|
||||
const output = await cmd.output();
|
||||
const stdout = new TextDecoder().decode(output.stdout).trim();
|
||||
const stderr = new TextDecoder().decode(output.stderr).trim();
|
||||
|
||||
if (!output.success) {
|
||||
throw new Error(`Git command failed: git ${args.join(" ")}\n${stderr}`);
|
||||
}
|
||||
return stdout;
|
||||
}
|
||||
|
||||
export async function addGitNote(ref: string, message: string, targetRef: string = "HEAD") {
|
||||
// First, check if a note already exists to avoid overwriting blindly
|
||||
// For this PoC, we will append or overwrite
|
||||
await runGitCmd(["notes", "--ref", ref, "add", "-f", "-m", message, targetRef]);
|
||||
}
|
||||
|
||||
export async function readGitNote(ref: string, targetRef: string = "HEAD"): Promise<string> {
|
||||
try {
|
||||
return await runGitCmd(["notes", "--ref", ref, "show", targetRef]);
|
||||
} catch (error: any) {
|
||||
if (error.message.includes("No note found")) {
|
||||
return "";
|
||||
}
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
|
||||
// In a real scenario, tests would be separated. For this PoC, we will run the tests here.
|
||||
if (import.meta.main) {
|
||||
console.log("Running Git Storage PoC tests...");
|
||||
|
||||
// 1. Test Git Notes
|
||||
const customRef = "forum/test-reasoning";
|
||||
const testMessage = JSON.stringify({
|
||||
agent: "poc-agent",
|
||||
risk: "low",
|
||||
thought: "This is a hidden thought stored in a git note."
|
||||
});
|
||||
|
||||
try {
|
||||
console.log(`Adding note to current HEAD under ref ${customRef}...`);
|
||||
await addGitNote(customRef, testMessage);
|
||||
|
||||
console.log(`Reading note back...`);
|
||||
const readMessage = await readGitNote(customRef);
|
||||
|
||||
assertEquals(readMessage, testMessage);
|
||||
console.log("✅ Git Notes PoC successful: Read/Write worked as expected.");
|
||||
|
||||
// Clean up
|
||||
await runGitCmd(["notes", "--ref", customRef, "remove", "HEAD"]);
|
||||
} catch (err) {
|
||||
console.error("❌ Git Notes PoC failed:", err);
|
||||
}
|
||||
}
|
||||
Loading…
x
Reference in New Issue
Block a user