Unified Store Tools

// Store data in working memory
// Tool call from LLM:
{
  "name": "store_set",
  "arguments": {
    "store": "notes",
    "key": "api_response",
    "data": {
      "description": "Full API response from /users endpoint",
      "value": { "users": ["Alice", "Bob", "Charlie"] },
      "tier": "findings",
      "priority": "high"
    }
  }
}

// Retrieve data
{
  "name": "store_get",
  "arguments": {
    "store": "notes",
    "key": "api_response"
  }
}

// Query memory entries
{
  "name": "store_action",
  "arguments": {
    "store": "notes",
    "action": "query",
    "params": { "tier": "findings", "pattern": "api_*" }
  }
}

// Clean up raw tier
{
  "name": "store_action",
  "arguments": {
    "store": "notes",
    "action": "cleanup_raw"
  }
}

// Store live state visible directly in context
{
  "name": "store_set",
  "arguments": {
    "store": "whiteboard",
    "key": "current_state",
    "data": {
      "description": "Processing state for current task",
      "value": { "step": 3, "status": "active" },
      "priority": "high"
    }
  }
}

// Delete an entry
{
  "name": "store_delete",
  "arguments": {
    "store": "whiteboard",
    "key": "temp_data"
  }
}

// List all entries
{
  "name": "store_list",
  "arguments": {
    "store": "whiteboard"
  }
}

// Set a persistent instruction
{
  "name": "store_set",
  "arguments": {
    "store": "instructions",
    "key": "personality",
    "data": {
      "content": "Always be friendly and helpful. Use clear, simple language."
    }
  }
}

// Remove an instruction
{
  "name": "store_delete",
  "arguments": {
    "store": "instructions",
    "key": "personality"
  }
}

// Clear all instructions
{
  "name": "store_action",
  "arguments": {
    "store": "instructions",
    "action": "clear",
    "params": { "confirm": true }
  }
}

// Store user preference
{
  "name": "store_set",
  "arguments": {
    "store": "user_info",
    "key": "theme",
    "data": {
      "value": "dark",
      "description": "User preferred theme"
    }
  }
}

// Get all user info
{
  "name": "store_get",
  "arguments": {
    "store": "user_info"
  }
}

// Clear all user info
{
  "name": "store_action",
  "arguments": {
    "store": "user_info",
    "action": "clear",
    "params": { "confirm": true }
  }
}

// Documentation check: complete example
import {
  BasePluginNextGen,
  type IStoreHandler,
  type StoreEntrySchema,
  type StoreGetResult,
  type StoreSetResult,
  type StoreDeleteResult,
  type StoreListResult,
  type StoreActionResult,
} from 'oneringai';

class SnippetsPlugin extends BasePluginNextGen implements IStoreHandler {
  readonly name = 'snippets';

  private snippets = new Map<string, { text: string; createdAt: number }>();

  getStoreSchema(): StoreEntrySchema {
    return {
      storeId: 'snippets',
      displayName: 'Snippets',
      description: 'Text snippets keyed by name',
      usageHint: 'Use for: quick reusable text snippets.',
      setDataFields: 'text (required): Snippet content',
    };
  }

  // IStoreHandler implementation
  async storeGet(key?: string): Promise<StoreGetResult> {
    if (key) {
      const snippet = this.snippets.get(key);
      return snippet ? { found: true, key, entry: snippet } : { found: false, key };
    }
    // For this custom snippets store only, return all entries when key is omitted
    const entries = Array.from(this.snippets.entries()).map(([k, v]) => ({ key: k, ...v }));
    return { found: true, entries };
  }

  async storeSet(key: string, data: Record<string, unknown>): Promise<StoreSetResult> {
    const text = data.text as string;
    if (!text) return { success: false, key, error: 'Missing "text" field' };
    this.snippets.set(key, { text, createdAt: Date.now() });
    return { success: true, key, message: `Snippet "${key}" saved` };
  }

  async storeDelete(key: string): Promise<StoreDeleteResult> {
    const deleted = this.snippets.delete(key);
    return { deleted, key };
  }

  async storeList(filter?: Record<string, unknown>): Promise<StoreListResult> {
    const entries = Array.from(this.snippets.entries()).map(([k, v]) => ({
      key: k,
      text: v.text,
      createdAt: v.createdAt,
    }));
    return { entries, total: entries.length };
  }

  async storeAction(action: string, params?: Record<string, unknown>): Promise<StoreActionResult> {
    if (action === 'clear') {
      if (!params?.confirm) return { success: false, action, error: 'Requires confirm: true' };
      this.snippets.clear();
      return { success: true, action, message: 'All snippets cleared' };
    }
    return { success: false, action, error: `Unknown action: ${action}` };
  }

  // Standard plugin methods
  getInstructions(): string | null { return 'Use store_set("snippets", key, { text }) to save text snippets.'; }
  async getContent(): Promise<string | null> { return null; }
  getContents(): unknown { return Object.fromEntries(this.snippets); }
  getTools() { return []; }  // No plugin-specific tools needed; store_* tools handle everything
}

const ctx = AgentContextNextGen.create({ model: 'gpt-4.1' });
ctx.registerPlugin(new SnippetsPlugin());

// Now the LLM can use:
// store_set("snippets", "meeting", { text: "Discussed Q3 roadmap" })
// store_get("snippets", "meeting")
// store_list("snippets")
// store_action("snippets", "clear", { confirm: true })