mikoshi 0.1.2 → 0.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NEETlabs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PROVENANCE.md

@@ -0,0 +1,14 @@
+# Provenance
+
+Mikoshi's agent system is an independent implementation.
+
+- It is informed by black-box behavior of agentic developer tools.
+- It does not copy proprietary source code, prompts, event names, or protocol strings from other products.
+- Agent/runtime contracts in Mikoshi use `mk_`-prefixed event names, lifecycle types, and state transitions implemented in this repository.
+
+Design goals:
+
+- Deterministic state transitions (`IDLE`, `PLANNING`, `AWAITING_PERMISSION`, `EXECUTING`, `FINALIZING`).
+- Auditable capability grants (`filesystem.write`, `process.spawn`, `network.external`).
+- Typed runtime events rendered by UI; raw tool payloads are not intended for direct UI display.
+- Multi-tool execution with sequential default and isolated parallel option.

package/README.md

@@ -2,7 +2,13 @@
 npm install -g mikoshi
 ```
 
-✨ Mikoshi — private local code search + MCP
+✨ Mikoshi — Context Engine for Private local code search + MCP
+
+This system is an independent implementation inspired by publicly observable behavior of agentic developer tools.
+The agent runtime, tool lifecycle, permission flow, and event protocol are clean-room implementations using `mk_`-prefixed types and events.
+
+## Provenance
+See `PROVENANCE.md` for implementation provenance and design constraints.
 
 ## Install
 ```bash
@@ -20,6 +26,21 @@ MCP
 mikoshi-mcp
 ```
 
+Interactive permissions
+```text
+/permissions
+# configure: filesystem.write, process.spawn, network.external
+```
+
+Models
+```text
+/models
+# provider: openai or anthropic
+# API keys are stored per provider+model
+# openai models: gpt-5.2, gpt-5.2-codex, gpt-5.2-pro
+# anthropic models: claude-sonnet-4-5, claude-haiku-4-5, claude-opus-4-6
+```
+
 Codex MCP config (config.toml)
 ```toml
 [mcp_servers.mikoshi]
@@ -37,5 +58,3 @@ npm install
 npm test
 mikoshi doctor
 ```
-
-Note: First run may download the local embedding model once.

package/package.json

@@ -1,23 +1,27 @@
 {
   "name": "mikoshi",
-  "version": "0.1.2",
-  "description": "Private local code search + MCP",
+  "version": "0.1.4",
+  "description": "Context Engine for Private local code search + MCP",
+  "license": "MIT",
   "type": "module",
+  "homepage": "https://NEET.gg",
   "bin": {
     "mikoshi": "src/mikoshi/cli.js",
     "mikoshi-mcp": "src/mikoshi/mcp_server/server.js"
   },
   "files": [
     "src/mikoshi/**",
-    "README.md"
+    "README.md",
+    "PROVENANCE.md"
   ],
   "scripts": {
     "test": "node --test",
-    "lint": "node --check ./src/mikoshi/cli.js"
+    "lint": "node --check ./src/mikoshi/cli.js",
+    "audit:unused": "node scripts/audit-unused.js",
+    "prepack": "node scripts/set-git-head.js"
   },
-  "dependencies": {},
-  "optionalDependencies": {
-    "@xenova/transformers": "^2.17.2",
-    "onnxruntime-node": "^1.20.0"
-  }
+  "dependencies": {
+    "@xenova/transformers": "^2.17.2"
+  },
+  "gitHead": "0c4ae59"
 }

package/src/mikoshi/agent_runtime.js

@@ -0,0 +1,291 @@
+export const mk_AgentState = Object.freeze({
+  IDLE: "IDLE",
+  PLANNING: "PLANNING",
+  AWAITING_PERMISSION: "AWAITING_PERMISSION",
+  EXECUTING: "EXECUTING",
+  FINALIZING: "FINALIZING",
+});
+
+function mk_nowIso() {
+  return new Date().toISOString();
+}
+
+function mk_safeText(value) {
+  return String(value || "").trim();
+}
+
+function mk_bool(value) {
+  return value === true;
+}
+
+export class mk_AgentRuntime {
+  constructor({
+    sessionId,
+    onEvent,
+    requestCapability,
+    executeTool,
+    deriveCapability,
+    resolveCapabilityMode,
+  } = {}) {
+    this.sessionId = mk_safeText(sessionId) || `mk_${Date.now().toString(36)}`;
+    this.state = mk_AgentState.IDLE;
+    this.pendingTools = [];
+    this.grantedCapabilities = new Set();
+    this.executionLog = [];
+    this._toolCounter = 0;
+    this._onEvent = typeof onEvent === "function" ? onEvent : () => {};
+    this._requestCapability =
+      typeof requestCapability === "function" ? requestCapability : async () => true;
+    this._executeTool =
+      typeof executeTool === "function" ? executeTool : async () => ({ output: {} });
+    this._deriveCapability = typeof deriveCapability === "function" ? deriveCapability : () => null;
+    this._resolveCapabilityMode =
+      typeof resolveCapabilityMode === "function" ? resolveCapabilityMode : () => "prompt";
+  }
+
+  emit(event) {
+    if (!event || typeof event !== "object") return;
+    const payload = { ...event };
+    this._onEvent(payload);
+  }
+
+  setState(state, context = undefined) {
+    if (!state || this.state === state) return;
+    this.state = state;
+    this.emit({
+      type: "mk_agent.state",
+      state,
+      context: context && typeof context === "object" ? context : undefined,
+    });
+  }
+
+  setIntent(goal, meta = undefined) {
+    this.emit({
+      type: "mk_agent.intent",
+      goal: mk_safeText(goal),
+      meta: meta && typeof meta === "object" ? meta : undefined,
+    });
+  }
+
+  queueTools(calls) {
+    const items = Array.isArray(calls) ? calls : [];
+    const queued = [];
+    for (const call of items) {
+      if (!call || !call.toolName) continue;
+      this._toolCounter += 1;
+      const execution = {
+        id: `mk_tool_${this._toolCounter}`,
+        toolName: mk_safeText(call.toolName),
+        inputs: call.inputs && typeof call.inputs === "object" ? call.inputs : {},
+        approved: mk_bool(call.approved),
+        executedAt: undefined,
+        output: undefined,
+        error: "",
+        isolated: mk_bool(call.isolated),
+        providerToolCallId: mk_safeText(call.providerToolCallId),
+        display: mk_safeText(call.display) || mk_safeText(call.toolName),
+        finalized: false,
+      };
+      this.pendingTools.push(execution);
+      queued.push(execution);
+    }
+    return queued;
+  }
+
+  async executePendingTools({ parallelIsolated = false } = {}) {
+    if (!this.pendingTools.length) {
+      return { toolResults: [], stop: false };
+    }
+    this.setState(mk_AgentState.EXECUTING, { pending: this.pendingTools.length });
+
+    const toolResults = [];
+    let stop = false;
+    const sequential = this.pendingTools.filter((tool) => !tool.isolated || !parallelIsolated);
+    const parallel = this.pendingTools.filter((tool) => tool.isolated && parallelIsolated);
+    const totalSteps = this.pendingTools.length;
+    let stepCursor = 0;
+
+    for (const tool of sequential) {
+      stepCursor += 1;
+      const outcome = await this._executeSingleTool(tool, stepCursor, totalSteps);
+      toolResults.push(outcome.toolResult);
+      if (outcome.stop) {
+        stop = true;
+        break;
+      }
+    }
+
+    if (!stop && parallel.length) {
+      const baseStep = stepCursor;
+      const results = await Promise.all(
+        parallel.map(async (tool, idx) => ({
+          idx,
+          outcome: await this._executeSingleTool(tool, baseStep + idx + 1, totalSteps),
+        }))
+      );
+      results
+        .sort((a, b) => a.idx - b.idx)
+        .forEach(({ outcome }) => {
+          toolResults.push(outcome.toolResult);
+          if (outcome.stop) stop = true;
+        });
+    }
+
+    this.pendingTools = this.pendingTools.filter((tool) => !tool.finalized);
+    return { toolResults, stop };
+  }
+
+  finalize() {
+    this.setState(mk_AgentState.FINALIZING, { pending: this.pendingTools.length });
+    this.pendingTools = [];
+    this.setState(mk_AgentState.IDLE, { pending: 0 });
+  }
+
+  async _executeSingleTool(tool, step, totalSteps) {
+    const capability = mk_safeText(this._deriveCapability(tool)) || "";
+    if (capability && !tool.approved) {
+      const mode = mk_safeText(
+        this._resolveCapabilityMode({
+          capability,
+          toolExecution: tool,
+        })
+      ).toLowerCase();
+      const isPromptMode = !mode || mode === "prompt";
+      if (isPromptMode) {
+        this.setState(mk_AgentState.AWAITING_PERMISSION, {
+          capability,
+          tool_id: tool.id,
+        });
+        this.emit({
+          type: "mk_capability.request",
+          capability,
+          reason: tool.display || tool.toolName,
+        });
+      }
+      const granted = await this._requestCapability({
+        capability,
+        reason: tool.display || tool.toolName,
+        toolExecution: tool,
+      });
+      tool.approved = mk_bool(granted);
+      if (tool.approved) this.grantedCapabilities.add(capability);
+      if (isPromptMode || !tool.approved) {
+        this.emit({
+          type: "mk_capability.receipt",
+          capability,
+          granted: tool.approved,
+          details: {
+            tool_id: tool.id,
+            tool: tool.toolName,
+          },
+        });
+      }
+      if (isPromptMode) {
+        this.setState(mk_AgentState.EXECUTING, { pending: this.pendingTools.length });
+      }
+    }
+
+    this.emit({
+      type: "mk_tool.progress",
+      tool_id: tool.id,
+      step,
+      total_steps: totalSteps,
+    });
+
+    if (!tool.approved && capability) {
+      const error = `Permission denied for ${capability}.`;
+      tool.executedAt = mk_nowIso();
+      tool.error = error;
+      tool.output = { error, capability };
+      tool.finalized = true;
+      const toolResult = {
+        id: tool.id,
+        tool_call_id: tool.providerToolCallId || "",
+        toolUseId: tool.providerToolCallId || "",
+        tool: tool.toolName,
+        input: tool.inputs || {},
+        ok: false,
+        output: tool.output,
+        summary: `denied ${capability}`,
+      };
+      this.executionLog.push({
+        ...toolResult,
+        ts: tool.executedAt,
+      });
+      this.emit({
+        type: "mk_tool.result",
+        tool_id: tool.id,
+        success: false,
+        output: tool.output,
+        error,
+        summary: `denied ${capability}`,
+      });
+      return { toolResult, stop: false };
+    }
+
+    try {
+      const result = await this._executeTool(tool);
+      tool.executedAt = mk_nowIso();
+      tool.output = result?.output || {};
+      const summary = mk_safeText(result?.summary);
+      const toolError = mk_safeText(tool.output?.error);
+      tool.error = toolError;
+      tool.finalized = true;
+      const toolResult = {
+        id: tool.id,
+        tool_call_id: tool.providerToolCallId || "",
+        toolUseId: tool.providerToolCallId || "",
+        tool: tool.toolName,
+        input: tool.inputs || {},
+        ok: !toolError,
+        output: tool.output,
+        summary,
+      };
+      if (mk_safeText(result?.preview)) {
+        toolResult.preview = mk_safeText(result.preview);
+      }
+      this.executionLog.push({
+        ...toolResult,
+        ts: tool.executedAt,
+      });
+      this.emit({
+        type: "mk_tool.result",
+        tool_id: tool.id,
+        success: !toolError,
+        output: tool.output,
+        error: toolError || undefined,
+        summary: summary || (toolError ? toolError : "completed"),
+      });
+      return { toolResult, stop: mk_bool(result?.stop) };
+    } catch (err) {
+      const error = mk_safeText(err?.message || err) || "Tool execution failed.";
+      tool.executedAt = mk_nowIso();
+      tool.error = error;
+      tool.output = { error };
+      tool.finalized = true;
+      const toolResult = {
+        id: tool.id,
+        tool_call_id: tool.providerToolCallId || "",
+        toolUseId: tool.providerToolCallId || "",
+        tool: tool.toolName,
+        input: tool.inputs || {},
+        ok: false,
+        output: tool.output,
+        summary: error,
+      };
+      this.executionLog.push({
+        ...toolResult,
+        ts: tool.executedAt,
+      });
+      this.emit({
+        type: "mk_tool.result",
+        tool_id: tool.id,
+        success: false,
+        output: tool.output,
+        error,
+        summary: error,
+      });
+      return { toolResult, stop: false };
+    }
+  }
+}

package/src/mikoshi/auth.js

@@ -8,7 +8,8 @@ import { DEFAULT_FEATURES, DEFAULT_PLAN } from "./entitlements.js";
 export const DEFAULT_API_BASE_URL = "https://neet.gg";
 
 const AUTH_FILENAME = "auth.json";
-const CONFIG_FILENAME = "config.json";
+const CONFIG_FILENAME = "auth-config.json";
+const LEGACY_CONFIG_FILENAME = "config.json";
 
 export class AuthError extends Error {}
 
@@ -25,18 +26,25 @@ export function configPath() {
   return path.join(indexRoot(), CONFIG_FILENAME);
 }
 
+function legacyConfigPath() {
+  return path.join(indexRoot(), LEGACY_CONFIG_FILENAME);
+}
+
 export function loadBrokerConfig() {
-  const cfgPath = configPath();
-  if (!fs.existsSync(cfgPath)) {
-    return { api_base_url: DEFAULT_API_BASE_URL };
-  }
-  try {
-    const data = JSON.parse(fs.readFileSync(cfgPath, "utf8"));
-    const apiBase = String(data.api_base_url || "").trim().replace(/\/+$/, "");
-    return { api_base_url: apiBase || DEFAULT_API_BASE_URL };
-  } catch {
-    return { api_base_url: DEFAULT_API_BASE_URL };
+  const candidates = [configPath(), legacyConfigPath()];
+  for (const cfgPath of candidates) {
+    if (!fs.existsSync(cfgPath)) continue;
+    try {
+      const data = JSON.parse(fs.readFileSync(cfgPath, "utf8"));
+      const apiBase = String(data.api_base_url || "").trim().replace(/\/+$/, "");
+      if (apiBase) {
+        return { api_base_url: apiBase };
+      }
+    } catch {
+      // ignore invalid config and continue
+    }
   }
+  return { api_base_url: DEFAULT_API_BASE_URL };
 }
 
 export function saveBrokerConfig(apiBaseUrl) {
@@ -150,20 +158,41 @@ async function promptLine(prompt) {
 }
 
 function parsePastePayload(text) {
-  let data;
-  try {
-    data = JSON.parse(text);
-  } catch (err) {
-    throw new AuthError("Invalid JSON response.");
+  const input = String(text || "").trim();
+  if (!input) throw new AuthError("Missing response.");
+  if (input.startsWith("{")) {
+    let data;
+    try {
+      data = JSON.parse(input);
+    } catch {
+      throw new AuthError("Invalid response payload.");
+    }
+    if (!data || typeof data !== "object") throw new AuthError("Invalid response payload.");
+    const code = String(data.code || "");
+    const state = String(data.state || "");
+    if (!code || !state) throw new AuthError("Missing code or state.");
+    return { code, state };
+  }
+
+  const queryPart = input.includes("?") ? input.split("?").pop() : input;
+  const hashPart = queryPart.includes("#") ? queryPart.split("#").pop() : queryPart;
+  const params = new URLSearchParams(hashPart);
+  const codeFromParams = params.get("code");
+  const stateFromParams = params.get("state");
+  if (codeFromParams && stateFromParams) {
+    return { code: codeFromParams, state: stateFromParams };
   }
-  if (!data || typeof data !== "object") throw new AuthError("Invalid JSON response.");
-  const code = String(data.code || "");
-  const state = String(data.state || "");
-  if (!code || !state) throw new AuthError("Missing code or state.");
-  return { code, state };
+
+  const codeMatch = input.match(/code\s*[:=]\s*([A-Za-z0-9._~-]+)/i);
+  const stateMatch = input.match(/state\s*[:=]\s*([A-Za-z0-9._~-]+)/i);
+  if (codeMatch && stateMatch) {
+    return { code: codeMatch[1], state: stateMatch[1] };
+  }
+
+  throw new AuthError("Missing code or state.");
 }
 
-export async function login() {
+export async function login({ promptLabel } = {}) {
   const broker = loadBrokerConfig();
   const state = generateState();
   const verifier = generateCodeVerifier();
@@ -172,7 +201,8 @@ export async function login() {
 
   await openUrl(url);
 
-  const pasted = await promptLine("Paste the JSON response here: ");
+  const promptText = String(promptLabel || "Paste the response here: ");
+  const pasted = await promptLine(promptText);
   const { code, state: returnedState } = parsePastePayload(pasted);
   if (returnedState !== state) {
     throw new AuthError("Invalid state.");