AI Operating System — Marvia Kernel

Marvia-18

AI orchestrates the platform; business logic stays external

Every action derives from assembled context, resolves to a discovered capability and executes as a validated command with a cost estimate attached.

user-intentcontext-assemblyreasoningcapability-discoverycommand-planningexecutionresponselearning

provider-agnostic

OpenAI, Gemini, Claude, OpenRouter, Ollama and future providers sit behind one router contract.

byok-ready

A workspace may bring its own key; credentials stay in the vault and never reach prompts.

context-first

Every action derives from assembled, versioned, workspace-isolated context.

tool-first

Capabilities are exposed as executable commands, never as free-text side effects.

capability-driven

Commands, reports and widgets are discovered dynamically from registries.

explainable

Every action carries reasoning, cost and alternatives.

deterministic

Prefer a deterministic path whenever one exists for the intent.

human-approval

Approval modes are always, never, high-risk or workspace policy.

workspace-scoped

Context, memory and policy never cross a workspace boundary.

cost-aware

Tokens, credits and execution time are estimated before execution.

Context assembly

Fourteen ordered sources, versioned per workspace

Compression drops the lowest-order optional sources first and never a required one.

Sources

workspace: Workspace identity, plan, locale and policy set.
project?: Active project, goals and members.
website?: Website under analysis with its verified ownership.
snapshot?: Latest immutable snapshot version for the website.
knowledge-graph?: Nodes and edges derived from the snapshot.
uwo?: Universal Website Object — the public contract for extensions.
reports?: Recent reports and their health scores.
findings?: Open findings by priority and severity.
knowledge-objects?: Content-engine knowledge relevant to the intent.
extensions: Installed extensions and the capabilities they contribute.
connectors?: Connected providers and their sync health.
history?: Prior commands, outcomes and rejections in this workspace.
preferences: User preferences: language, verbosity, approval mode.
mission?: The workspace mission that frames every recommendation.

Rules

— Assembly is automated; no surface hand-builds a context object.
— Every assembled context is versioned and cacheable by source fingerprint.
— A context never contains data from another workspace.
— Compression drops the lowest-order optional sources first, never required ones.

Standards

— Context first: no action without assembled context.
— Command first: only validated commands execute.
— Capability first: discovery is dynamic, never hardcoded.
— No provider lock-in and no hidden logic.
— Everything observable, explainable and auditable.

Prompt and memory

Eight prompt layers, seven memory layers

Prompts compose in a fixed order; memory never mixes workspaces.

Prompt layers

system: Kernel identity, safety rules and output contract.
workspace: Mission, tone, language and workspace policy.
project: Project goals, audience and constraints.
extension: Instructions contributed by an installed extension.
capability: How to use one discovered capability correctly.
task: The concrete task derived from user intent.
temporary: Single-turn overrides that are never persisted.
personalplanned: Per-user preferences and style.

— Templates are registry entries with a semantic version; a published version is immutable.
— Layers compose in declared order and a lower layer can never remove a higher rule.
— Variables are declared; an undeclared interpolation fails closed.
— Secrets, keys and raw credentials are never interpolated into a prompt.

Memory layers

workspaceuntil deleted: Durable facts, decisions and constraints for the workspace.
projectproject lifetime: Project-scoped goals, glossary and prior outcomes.
sessionsession: Conversation state for the active session.
temporarysingle run: Scratch memory for one execution plan.
knowledgeuntil superseded: Derived knowledge objects promoted from snapshots and reports.
learningrolling window: What worked, what was rejected and which plans failed.
personaluser lifetime: Per-user memory across workspaces.

— Memory never mixes workspaces; a read is always workspace-scoped.
— Writes are incremental and additive; a correction supersedes rather than rewrites history.
— Temporary memory is discarded when its plan settles, successfully or not.
— Learning memory records rejections so the planner stops re-proposing them.
— Every memory write is attributed to an actor and auditable.

Planning and commands

Plans are derived, commands are validated

There is no intent-to-command lookup table; the planner reads whatever capabilities the workspace can actually run.

plannedvalidatingawaiting-approvalreservedexecutingsettledfailedrolled-backcancelled

Example plan

01 Capturesnapshot.create: Run the snapshot pipeline and version the result.
02 Analyseextension.seo.run: Execute the installed SEO extension against the UWO.
03 Reportreport.generate: Assemble findings into the fixed report structure.
04 Insightinsight.derive: Score health, group risks and rank opportunities.

— Plans are generated from discovered capabilities; there is no intent-to-command lookup table.
— A step whose dependency failed is skipped, not retried blindly.
— Total cost is the sum of step estimates plus reasoning tokens, computed before approval.
— A plan carries its reasoning and at least one alternative when one exists.

Validation checks

permission: The actor holds every permission the capability declares.
policy: The workspace policy allows this capability and provider.
credits: The wallet can reserve the estimated cost before execution.
risk: Risk level is compared against the workspace approval mode.
input: Arguments validate against the capability's declared schema.

— A capability the workspace cannot run is filtered out, never shown disabled to the model.
— Capabilities are contributed by the kernel, extensions and connectors through one registry.
— Each capability declares permissions, credit cost and risk before it can be planned.

Command domains

website-analysisconnector-synccontent-generationlearningmarketplaceextensionsreportsexportsnotificationsautomation

— Only a validated, registered command executes; free-form model output never becomes a side effect.
— Tool calling is provider-agnostic: the router translates the same command schema per provider.
— Every run is logged with actor, plan, provider, tokens, credits and outcome.
— A failed command releases its reservation and rolls back partial writes.
— Cancellation is available at every step boundary.

Approval, policy and budget

Nothing expensive or risky runs unannounced

Approval is requested before credits are spent, and a denial is written to learning memory with its reason.

Approval modes

alwaysneverhigh-riskworkspace-policy

— Approval is requested before credits are spent, never after.
— A denied plan is recorded in learning memory with its reason.
— Sensitive capabilities always require a manual review regardless of mode.

Policy dimensions

providers: Which providers and models a workspace may reach, including BYOK entries.
capabilities: Which discovered capabilities the AI may plan with.
budget: A per-workspace credit ceiling enforced by the monetization wallet.
restricted-commands: Commands that are never planned automatically.
privacy: Retention and redaction rules applied before a prompt leaves the kernel.
language: Response language and tone for the workspace.

Budget awareness

— Tokens, credits and duration are estimated before execution and shown to the user.
— A high-cost action needs explicit approval even when the mode is never.
— Spend is reserved through the monetization wallet, then settled with the actual cost.
— When the budget is exhausted the planner degrades to cheaper capabilities instead of failing silently.

Providers

Five providers behind one router, BYOK ready

Feature code never names a provider; fallback and streaming are router concerns.

Profiles

OpenAI: cloud · byok · stream · tools
Google Gemini: cloud · byok · stream · tools
Anthropic Claude: cloud · byok · stream · tools
OpenRouter: cloud · byok · stream · tools
Ollama: local · stream · tools

Performance

— Responses stream by default; the first token is the latency budget that matters.
— Assembled context and prompt renders are cached by fingerprint.
— Context compression drops optional sources before it truncates required ones.
— Provider fallback retries with backoff on a declared error class, never on a policy denial.
— Every run is cancellable by the user at a step boundary.

Security

— AIOS never bypasses permissions, credits or the secret vault.
— Workspace policy is evaluated server-side; the client copy is advisory only.
— Third-party extension code runs sandboxed and receives context, not credentials.
— Every prompt, plan, command and approval is written to the audit trail.

Integration

Events in, recommendations out

AIOS listens to the engines it orchestrates and never owns their state.

Consumed events

snapshot.completed: Refresh context and offer the analysis plan.
report.generated: Summarise findings and propose next actions.
learning.completed: Update learning memory and unlock follow-up lessons.
connector.sync.completed: Re-assemble connector context and flag new data.
credits.used: Recompute the remaining budget for the active plan.
extension.installed: Re-run capability discovery for the workspace.

Marketplace recommendations

extension: Suggested when a plan needs a capability the workspace lacks.
blueprint: Suggested when the intent matches a published workflow.
knowledge-pack: Suggested when context is thin for the requested domain.
learning-pack: Suggested after repeated findings in the same category.
connector: Suggested when the required data lives in an unconnected provider.

— A recommendation is never installed automatically; installation follows the marketplace approval flow.
— Recommended assets execute sandboxed under the same capability permissions as any other asset.
— Event reactions are additive: AIOS listens, it does not own the emitting engine.

Context dock

current-context: Which sources were assembled and at what version.
active-capabilities: Capabilities available to the current plan.
provider: Provider and model in use, including BYOK state.
cost: Estimated tokens, credits and duration against the budget.
confidence: Planner confidence and why it chose this route.
execution-plan: Steps, dependencies and live state.

— The dock is read-only except for approval actions.
— Panels are user-configurable and their order is persisted per workspace.
— The dock reflects live plan state; it never caches a stale estimate.

Widgets and SDK

Seven AI widgets and eight define functions

An extension participates in AIOS only through the SDK; no definition can read a secret or skip approval.

AI widgets

Workspace assistantworkspace: Next best actions from open findings and budget.
Project assistantproject: Goal progress and blocked steps for the active project.
Report explainerreport: Explains a finding, its evidence and the fix.
Learning coachlearning: Recommends the next lesson from learning memory.
Asset advisormarketplace: Matches missing capabilities to published assets.
Developer consoledeveloper: Prompt, plan and tool-call inspection for builders.
Support agentsupport: Answers from documentation and workspace history.

AI SDK

definePrompt(template: string, version: string) => PromptTemplate: Register a versioned prompt template.
defineAgent(config: AgentConfig) => Agent: Declare an agent with its capabilities and policy.
defineReasoner(logic: ReasoningFunction) => Reasoner: Contribute a reasoning strategy for an intent class.
definePlanner(planner: PlanningFunction) => Planner: Turn discovered capabilities into an execution plan.
defineMemory(memory: MemoryLayer) => MemoryBinding: Register a workspace-scoped memory layer.
defineContextProvider(provider: ContextSource) => ContextBinding: Add a source to the context assembler.
definePolicy(policy: WorkspacePolicy) => PolicyBinding: Declare provider, capability and budget policy.
defineCapabilityResolver(resolver: CapabilityDiscovery) => ResolverBinding: Contribute capability discovery for a domain.

— The SDK is the only way an extension participates in AIOS.
— Every definition is versioned and owner-attributed in the registry.
— No SDK function can read a secret, mutate a wallet or skip approval.
— SDK versions follow the platform version and stay backwards compatible.