npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@ikarmic/forge-core

v5.5.2

Published

Agent engine for IKarmic AI Forge. Model loop, tools, MCP, sandbox, memory, compaction, plan mode, skills, hooks.

Readme

@ikarmic/forge-core

The agent engine for IKarmic AI Forge. Shared by the CLI and the VS Code extension.

What's in the box

  • Agent: the model + tool loop with streaming events, manual approval, abort support, multi-turn history.
  • BUILTIN_TOOLS: ten ready-made tools: read_file, write_file, edit_file, list_files, search_files, run_command, fetch_url, sub_agent, memory_read, memory_write.
  • createLanguageModel({ provider, model }): Vercel AI SDK adapter for OpenAI, Anthropic, Google, Ollama, and OpenRouter.
  • resolveModelFromEnv(): picks a provider/model from your environment.
  • MCP integration: loadMcpConfig, connectAll, closeAll, plus a JSON-Schema → Zod converter that turns any MCP server's tools into first-class ToolDefinition objects. Supports stdio, SSE, and streamable-HTTP transports.
  • Tool sandbox: ToolSandbox restricts which tools the agent can call and what those tools can touch (path / command / URL policies). See Sandbox below.
  • Session persistence: saveSession / loadSession / listSessions for multi-turn history that survives a process restart.
  • Cost tracking: lookupPricing + computeCostUsd against a built-in pricing table; surfaced as cost events and costUsd on AgentRunResult.
  • Secret redaction: redact() scrubs provider keys, JWTs, PEM keys, and .env-style secrets from tool output before the model sees them.
  • Tool result cache: ToolResultCache (LRU + TTL, never caches destructive tools) survives across turns within a session.
  • Project memory: buildMemoryBlock() auto-loads .forge/MEMORY.md into the system prompt; memory_read / memory_write / memory_forget tools let the agent record and retire conventions mid-run (typed sections, relevance-ranked injection, stale-ref markers).
  • Plan mode: AgentConfig.planMode runs a single-turn, tool-free pass that emits a numbered plan as text. Pair with an approve/edit/cancel flow.
  • Context compaction: opt-in summarization of older turns when approaching the model's context window. AgentConfig.enableCompaction toggles it; the rest are knobs.
  • Skills system: discoverSkills() finds SKILL.md files in ./skills/, ./.forge/skills/, ~/.forge/skills/. selectSkills() + composeSkillsPrompt() score and inject the top matches for the current task.
  • Lifecycle hooks: HooksBus subscribes to 10 lifecycle events (PreToolUse, PostToolUse, PreCompact, SessionStart, SessionEnd, UserPromptSubmit, SubagentStart, SubagentStop, Notification, Stop). Configure via loadHooksConfig() from ~/.forge/settings.json + .forge/settings.json.

Install

pnpm add @ikarmic/forge-core ai @ai-sdk/anthropic
# (or @ai-sdk/openai, @ai-sdk/google)

Minimal example

import { Agent, resolveModelFromEnv } from '@ikarmic/forge-core';

const agent = new Agent({
  model: resolveModelFromEnv(),
  cwd: process.cwd(),
  auto: true,
});

const result = await agent.run({
  task: 'list all .ts files under src/ and count their lines',
  onEvent: (event) => {
    if (event.type === 'text_delta') process.stdout.write(event.text);
    if (event.type === 'tool_call') console.log(`\n→ ${event.name}(${JSON.stringify(event.args)})`);
  },
});

console.log(`\nDone in ${result.iterations} steps (${result.inputTokens}↑ ${result.outputTokens}↓ tokens)`);

Custom tools

import { z } from 'zod';
import type { ToolDefinition } from '@ikarmic/forge-core';

const gitStatusTool: ToolDefinition = {
  name: 'git_status',
  description: 'Run `git status --short` and return the result.',
  parameters: z.object({}),
  execute: async (_args, ctx) => {
    const { spawn } = await import('node:child_process');
    // ...
    return { ok: true };
  },
};

const agent = new Agent({
  model: resolveModelFromEnv(),
  extraTools: [gitStatusTool],
});

Approval flow

By default, run_command and any tool marked destructive: true require approval via the approve callback. In --auto mode they're approved automatically; in interactive mode the CLI shows a y/n prompt and resolves the returned promise.

const agent = new Agent({
  model: resolveModelFromEnv(),
  approve: async (req) => {
    console.log(`Approve ${req.name}?`);
    return readlineYesNo();
  },
});

Sandbox

ToolSandbox is the security layer for the agent. Two dimensions:

  1. Tool allow/deny lists: strip tools from the model's view entirely.
  2. Per-tool policies: narrow what a still-exposed tool can do.
import { Agent, resolveModelFromEnv } from '@ikarmic/forge-core';

const agent = new Agent({
  model: resolveModelFromEnv(),
  toolSandbox: {
    // Only expose these three tools to the model.
    allowTools: ['read_file', 'list_files', 'search_files'],
    policies: {
      // File tools can only operate inside src/ or tests/.
      read_file: { allowedPaths: ['src/**', 'tests/**'] },
      list_files: { allowedPaths: ['src/**', 'tests/**'] },
      // run_command: only allow npm/pnpm/node invocations, never rm or curl.
      run_command: {
        allowedCommands: [/^(npm|pnpm|node)\b/],
        deniedCommands: [/^rm\b/, /^curl\b/],
      },
      // fetch_url: only allow HTTPS docs endpoints.
      fetch_url: { allowedUrls: [/^https:\/\/docs\./] },
    },
  },
});
  • allowTools is an explicit whitelist (only listed tools survive).
  • denyTools is a blacklist applied to whatever survived allowTools.
  • For path patterns: absolute patterns are anchored, relative patterns match at any depth. * matches a non-separator run, ** crosses separators, X/** also matches X itself.
  • For command / URL patterns: anything you can compile to a RegExp.
  • When both allowedPaths and deniedPaths are set, deniedPaths wins: the user can refine the allowed set but cannot grant access to a denied path.

Violations surface as a normal tool error ([sandbox] Path ... is not in allowedPaths (...)), so the model can recover by trying a different path/command/URL.

The CLI exposes all of the above as flags: see forge --help.

MCP integration

Load tools from any MCP-compatible server and merge them into the agent. Supports stdio, SSE, and streamable-HTTP transports.

import { Agent, loadMcpConfig, connectAll, closeAll } from '@ikarmic/forge-core';

const config = await loadMcpConfig('./forge.mcp.json');
const servers = await connectAll(config);
const mcpTools = servers.flatMap((s) => s.tools);

try {
  const agent = new Agent({
    model: resolveModelFromEnv(),
    extraTools: mcpTools,
  });
  const result = await agent.run({ task: 'use the filesystem tool to list src/' });
  console.log(result.finalText);
} finally {
  await closeAll(servers); // important: spawned processes must be cleaned up
}

MCP tools appear in the agent's prompt with fully-qualified names like mcp__filesystem__read_file so they can't collide with the built-in tool set.

License

Proprietary, free to run with the Forge extension and CLI. See LICENSE. Versions 4.5.0 and earlier stay MIT.