You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs: rewrite Emergent Design + Ecosystem table in calmer voice
Two parts of the README read like LLM-stack copy: the Emergent Design
section name-checked "chat-completion wrappers" and "load-bearing
security boundary," and the Ecosystem table left two registry packages
(agentos-skills-registry, agentos-extensions-registry) unmentioned.
Rewrote both:
- Emergent Design now anchors on a single PKD epigraph at the top of
the section, leads with the mechanics directly, and uses a personal
Mars Genesis anecdote (security-officer agent forging the drought
constraint tool) instead of the abstract "agent extends its own
capability surface" framing. HEXACO Optional kept as opt-in with the
same code example. The "why emergent" closer is one tight paragraph
rather than two.
- Ecosystem table now includes agentos-skills-registry and
agentos-extensions-registry with a one-sentence explanation of why
the registry/content split exists (a host can pull the discovery +
auto-loader without bundling the full curated tree as a dep, and
the registry layer also accommodates community-contributed packs
once they're vetted).
The PKD epigraph is the single quote anchor for the section so the
README doesn't accumulate extra literary citations.
Two capabilities that distinguish AgentOS from chat-completion wrappers and from frameworks that hard-code an agent's affordances at startup.
54
+
> "So we and our elaborately evolving computers may meet each other halfway."
55
+
>
56
+
> — Philip K. Dick, *The Android and the Human*, 1972
55
57
56
-
### Runtime Tool Forging
57
-
58
-
**An agent can write itself a new tool at runtime, get the tool reviewed, and run it inside a sandbox, all in one turn.** That tool then becomes available for the rest of the session and for future agents in the same runtime.
58
+
Two pieces matter. Memory survives across turns. The agent's tool surface can grow within a session. Pass an optional personality vector and the runtime composes the three into behavior the prompt did not specify.
59
59
60
-
The mechanics, in order:
61
-
62
-
1.**Detect the gap.** Mid-decision, an agent notices the next step needs a function it doesn't have. (Example from a Mars Genesis run: a security officer agent decides it needs `compute_resource_allocation_under_drought_constraint(state) → priorityList` to make a defensible recommendation.)
63
-
2.**Forge.** The agent writes a TypeScript function. The function's input/output is described by a Zod schema; the function body is generated by the LLM from the agent's stated intent.
64
-
3.**Judge.** A separate LLM call ("judge") reads the forged function alongside the agent's stated intent and approves or rejects it. Mismatch rejects.
65
-
4.**Sandbox-execute.** Approved functions run inside a [V8 isolate](https://github.com/laverdet/isolated-vm) with a 128 MB heap and a 10-second wall clock. No filesystem, no network, no `eval`, no dynamic import. The sandbox is the load-bearing security boundary.
66
-
5.**Catalog and reuse.** Approved tools land in a discoverable tool index. Future turns invoke them via `call_forged_tool(name, args)`. Reuse costs tens of tokens. A forge costs full LLM tokens, so cost flattens after the first few turns of a long-running session.
60
+
### Runtime Tool Forging
67
61
68
-
In practice this is the difference between "the agent can do what we wrote handlers for" and "the agent can extend its own capability surface when the task warrants it." See the [emergent-tools post](https://agentos.sh/en/blog/emergent-tools-hexaco-leaders) for the live walkthrough.
62
+
An agent, mid-decision, decides it needs a function it doesn't have. It writes the function in TypeScript with a Zod-described input and output. A separate LLM call reads the forged function alongside the agent's stated intent and either approves or rejects. Approved functions run in a [V8 isolate](https://github.com/laverdet/isolated-vm) sandbox: 128 MB heap, 10-second wall clock, no filesystem, no network, no `eval`, no dynamic import. Approved tools land in a discoverable index. Future turns invoke them via `call_forged_tool(name, args)`. A forge costs full LLM tokens; reuse costs tens. Cost flattens after the first few turns.
69
63
70
-
### Optional HEXACO Personality
64
+
The first time I saw a security-officer agent in a Mars Genesis run forge `compute_resource_allocation_under_drought_constraint(state) → priorityList`, I assumed the function was hallucinated and would not run. It ran. The judge approved it. The next turn used it. Three turns later, the science officer was calling the same tool because the colony state had become the kind that needed it. Nothing about that path was scripted.
71
65
72
-
**HEXACO traits are opt-in. Most AgentOS deployments never touch personality and behave personality-neutral.** The runtime works exactly the same with or without a personality vector.
66
+
### HEXACO Personality (optional)
73
67
74
-
When you do pass a personality vector, the runtime treats it as a structured signal that biases retrieval, decision routing, and tool selection. Same agent, same prompt, same tool set: a high-Openness leader and a high-Conscientiousness leader produce measurably different outcomes because the kernel weights different memories and different tools differently.
68
+
Most agents you build with AgentOS never touch personality. The runtime works the same with or without a trait vector.
HEXACO covers six factors ([Honesty-Humility, Emotionality, Extraversion, Agreeableness, Conscientiousness, Openness](https://hexaco.org/)). The personality vector is editable, inspectable, and removable on consent. The implementation is in the kernel, not in a prompt; prompt-only personality dissolves under pressure, kernel-encoded personality survives.
87
+
When you pass a vector, the kernel uses it. Retrieval is biased toward memories the trait vector resonates with, decision routing weights specialists differently, tool selection picks differently among legitimate options. Same agent, same prompt, same tools: a high-Openness leader and a high-Conscientiousness leader make measurably different decisions because the kernel weighted different evidence. The bias lives in the kernel, not in a prompt; prompt-only personality dissolves under pressure. The vector is editable, inspectable, and removable on consent.
94
88
95
-
### Why "emergent"
89
+
### Why this composes into emergence
96
90
97
-
Memory + Runtime Tool Forging + (optional) HEXACO produce behavior the prompt did not specify and the developer did not predict in advance. In a Paracosm Mars Genesis run, two leaders with the same starting state, same agent roster, same seed diverge by turn six: one because the personality biased its specialists toward different memories, one because a forged tool from turn two became the obvious next move on turn five.
91
+
Mars Genesis: two leaders, same starting state, same agent roster, same seed. By turn six they have diverged. Not because the prompt diverged. Because the personality vector biased one leader's specialists toward memories the other's didn't surface, and because a tool one specialist forged on turn two became the obvious next move on turn five for one side and not the other. Same world, two histories.
98
92
99
-
Nothing about that emergence is mystical. It's the combination of (a) durable memory that survives across turns, (b) a tool surface that can grow within a session, and (c) optional personality biasing the choices among them. Each capability is documented and configurable; the surprises come from how they compose.
93
+
Durable memory plus a tool surface that can grow plus optional personality biasing the choices among them. Each capability is configurable. The surprises are in how they compose, not in the components.
100
94
101
95
---
102
96
@@ -275,16 +269,18 @@ Or pass `apiKey` inline on any call. Auto-detection order: OpenAI → Anthropic
|[`@framers/agentos-bench`](https://github.com/framersai/agentos-bench)| Open benchmark harness with 95% confidence intervals, judge-FPR probes, per-case run JSONs (MIT-licensed; agentos itself is Apache 2.0) |
|[paracosm](https://www.npmjs.com/package/paracosm)| AI agent swarm simulation engine |
286
-
287
-
**Extensions auto-pickup at startup.** The runtime walks the curated registry plus user-supplied extension paths, resolves each pack's `createExtensionPack(context)` factory, and registers tools, guardrails, and channels without manual wiring. The same model applies to skills: SKILL.md files are auto-discovered from the curated registry and any local `skills/` directory, with capability gating and HITL approval for side-effecting installs. See [extensions architecture](https://docs.agentos.sh/architecture/extension-loading) for the full loading model.
|[`@framers/agentos-extensions-registry`](https://www.npmjs.com/package/@framers/agentos-extensions-registry)| The discovery + auto-loader layer for the extensions catalog. Consumers wire this in to make curated extension packs available without packaging the entire extensions tree as a dependency. Separating the registry layer from the content layer lets a host pull the index without pulling the implementations. |
277
+
|[`@framers/agentos-skills`](https://www.npmjs.com/package/@framers/agentos-skills)| 88 curated SKILL.md skills covering common tasks. |
278
+
|[`@framers/agentos-skills-registry`](https://www.npmjs.com/package/@framers/agentos-skills-registry)| The discovery + auto-loader layer for the skills catalog. Same split as the extensions registry: a host imports this when it wants the curated skill index without bundling the full skills tree. Registries also serve community-contributed packs once they're vetted. |
279
+
|[`@framers/agentos-bench`](https://github.com/framersai/agentos-bench)| Open benchmark harness. Bootstrap 95% CIs at 10k resamples, judge false-positive-rate probes per benchmark, per-case run JSONs at fixed seed. MIT-licensed (the rest of AgentOS is Apache 2.0). |
|[`paracosm`](https://www.npmjs.com/package/paracosm)| AI agent swarm simulation engine that uses AgentOS as its substrate. |
282
+
283
+
**Extensions and skills auto-load at startup.** The runtime walks each registry plus any user-supplied paths, resolves each pack's `createExtensionPack(context)` factory or SKILL.md frontmatter, and registers tools, guardrails, channels, and skills without manual wiring. Capability gating and HITL approval gates apply to side-effecting installs. See [extensions architecture](https://docs.agentos.sh/architecture/extension-loading) for the full loading model.
0 commit comments