nyakore

nyakore is a minimal runtime environment for session-first multi-agent systems. It's the runtime core only — it does not own agent definitions, prompts, or product-specific behavior. Those belong to external definition repos (e.g. nyako).

Status

Intentionally small bootstrap implementation focused on:

• persistent session registry and deterministic routing
• NNP session-to-session messaging (see docs/nnp.md and docs/nnp-runtime.md)
• per-session runtime folders and run records
• thin launcher around pi's interactive host (attach)
• thin gateway for background work and detached remote exec
• TOML-based runtime config for external multi-agent setups

Source layout

src/app/                process entrypoints such as daemon and pi-backed attach host
src/auth/               credential loading and auth flows
src/cli/                CLI command registration and operator-facing handlers
src/config/             TOML parsing and runtime config loading
src/core/task/          task capability and registry
src/core/schedule/      recurring runtime schedules
src/core/workspace/     workspace capability and registry
src/core/               runtime kernel: sessions, routing, scheduling, orchestration
src/channels/           transport adapters such as Telegram that feed the runtime through gateway
src/gateway/            thin HTTP gateway, job store, and remote-control helpers
src/nnp/                NekoNeko Protocol messaging registry, tools, and orchestration
src/runtime/            runtime delivery, resume, timeout, and other host-policy adapters
src/pi/                 thin integration layer around published pi packages
src/project/            project-side tool and skill loading
~/.nyakore/             generated local runtime state and local secrets

src/core/ should remain the smallest layer possible. Move subsystems out of core rather than letting it become a grab bag.

Config layout

Project definitions live at the project root; machine-local state and secrets live under ~/.nyakore/.

runtime.toml                          # project runtime index
agents/<id>/agent.toml                # per-agent config + prompt assets
tools/<id>/tool.toml                  # project tool manifests
skills/                               # project skills
memory/*.md                           # shared project memory
schedules/*.md                        # declarative recurring schedules

~/.nyakore/config.toml                # machine-local host policy
~/.nyakore/providers/*.toml           # credential files
~/.nyakore/projects/<slug>-<hash>/    # per-project runtime state

runtime.toml:

version = 1
default_agent = "primary-agent"
agents_dir = "agents"
tools_dir = "tools"
skills_dir = "skills"
memory_dir = "memory"
schedules_dir = "schedules"

[[skills.external]]
provider = "github"
repo = "ShigureLab/gh-llm"
skill = "github-conversation"
ref = "main"

~/.nyakore/config.toml:

[paths]
projects_root = "~/.nyakore/projects"

[bash]
adapter = "native"  # or "rtk"

[gateway]
host = "127.0.0.1"
port = 17689
project_root = "~/Projects/nyako"  # optional single-project fallback

[channels.telegram]
# bot_token = "123456:replace-me"
# allowed_chat_ids = ["123456789"]
# default_agent = "primary-agent"

agents/<id>/agent.toml:

id = "primary-agent"
name = "primary-agent"
role = "coordinator"
tools = ["read", "bash", "runtime-session"]

[skills]
enable = ["github-conversation"]
disable = ["nyakore-tool-authoring"]

[model]
model = "minimax-cn/MiniMax-M2.5"
credential = "minimax-default"
thinking = "medium"

tools = [...] declares the exact tool surface — nyakore does not silently grant every tool. credential references ~/.nyakore/providers/*.toml. Run nyakore auth to create or update credentials. [[skills.external]] declares project-visible external skills by repository and skill name; agent-level [skills] then decides which discovered skills are enabled or disabled for that specific agent. nyakore clones the referenced repo, discovers the named skill, and caches the whole skill directory locally so references/ and scripts/ remain available after caching. hooks_dir declares project-managed session lifecycle hooks. Hook modules run during session create/archive/remove and can provision repo state such as optional session-scoped workspaces without hardcoding project policy into nyakore core. Runtime workspaces record project-managed repo bindings and execution directories under runtime state.

Prompt assembly: AGENTS.md → IDENTITY.md → SOUL.md → TOOLS.md → USER.md → memory/*.md → agent MEMORY.md → runtime memory summary.

Quick start

# Setup
pnpm install
nyakore auth
nyakore init

# Interactive session
nyakore attach primary-agent

# Container-like workflow
nyakore run nyako --name nyako
nyakore exec nyako -p "帮我看看这个 PR"
nyakore attach nyako

# Background gateway (normal long-running entrypoint)
nyakore gateway run

# Remote/detached execution
nyakore gateway exec nyako -p "继续当前任务" --wait
nyakore gateway job <job-id>

Use NYAKORE_DATA_ROOT=/tmp/nyakore-demo for isolated experiments. For normal usage, start from the definition repo:

cd ~/Projects/nyako
nyakore gateway run    # one terminal
nyakore attach nyako   # another terminal

nyakore gateway run acquires both gateway and daemon locks, so a separate nyakore daemon for the same data root will refuse to start. nyakore daemon remains available as a worker-only/debug entrypoint.

On Linux or macOS, supervise the gateway as a user service:

nyakore gateway service install
nyakore gateway service status

Development

For local development, run the TypeScript entrypoints directly instead of the published package bin:

pnpm dev:cli -- session list
pnpm dev:cli -- gateway run
pnpm dev:daemon

./bin/nyakore remains as a repo-local helper around the source CLI for the same purpose.

If you want a global nyakore command that points at this checkout, use:

pnpm dev:link

That linked command uses the locally built dist/ output from this repo. After source changes, rerun pnpm build before using the linked global command again. Remove the global link with pnpm dev:unlink.

Releasing

nyakore publishes from GitHub Actions through npm trusted publishing (OIDC). The workflow lives at .github/workflows/release.yml and follows the same tag-first release shape as nearby projects such as yutto and theme-elaina: build artifacts first, then publish from the tagged release run.

CI setup uses the official voidzero-dev/setup-vp@v1 action from the Vite+ docs. That action installs vp, resolves Node.js, configures the package manager, and restores dependency cache, so the workflow does not install pnpm separately.

Before pushing a release tag:

vp check
vp test

Then bump package.json#version, create a matching tag such as v0.1.0, and push it. The workflow uses setup-vp with dependency caching, verifies that the tag matches the package version, runs vp check, vp test, builds dist/nyakore-<version>.tgz, publishes that tarball to npm with OIDC-backed provenance, and creates a draft GitHub Release with the same artifact attached.

npm-side prerequisite: configure this repository as the package's trusted publisher on npm, using the workflow filename release.yml.

Roadmap

Core runtime:

• Extension system for tools, system-prompt injectors, resource providers
• Channel adapters for Telegram/external event sources
• Security model: approval boundaries, secret scopes, tool risk classes
• Agent interaction contracts for delegation and handoff semantics

NNP:

• Simplify around mailbox-backed core with stored messages as truth source
• Gateway transport for cross-process/machine protocol
• Add hardening (reminders, timeouts, recovery) only after core path is stable

Missing primitives:

• External tool bridge (kind = "external")
• Memory pipeline: ingestion, compaction, retrieval
• Workspace and task lifecycle tracking
• Artifact watchers for GitHub events
• Session governance: merging, splitting, archival

Operability:

• CLI ergonomics for diagnostics and health checks
• Structured logs, traces, metrics
• Expanded end-to-end test coverage

Design notes

• Session state stored under ~/.nyakore/projects/<project>/registry/sessions.json
• Agent ids are opaque runtime references; nyakore loads prompts from project definitions but does not own content
• Routing is artifact-first: PR/issue exact match beats repo match
• nyakore attach launches pi's interactive mode; nyakore gateway run is the normal long-running entrypoint
• Only explicit NNP messages count as protocol facts; assistant output is not automatically treated as replies