KDCube Use Cases: Problem In, Solution Out

---

The format is strict: problem in, solution out. Features appear only when a problem summons them. New problems get appended as we meet them — links to go deeper close every section. And KDCube is an app runtime, not only an agent runtime — it serves agentic apps and non-agentic ones alike, so the problems below span both: scheduled jobs, published sites, and shared workspaces as much as agent turns.

01 We already have an agent — rewriting it is not an option

Keep the decision runtime and connect only the seams the product needs:

• The existing loop stays responsible for decisions: graphs, prompts, tools, checkpoints, and domain code keep their jobs. One execute_core seam maps bound turn input into the agent and maps its stream and answer back to KDCube.
• Scaled serving is stateless between turns: a fresh graph instance is built for one user/conversation turn and then discarded. Shared/checkpointed storage carries continuity; only true connections are reused, so another worker can serve the next turn.
• Serve it through the surface you need: REST, webhook, Telegram, streaming chat, MCP, or a KDCube widget can point to the same hosted agent.
• The reference is concrete: ported-langgraph-agents@2026-07-13 hosts two LangGraph agents behind one dispatcher, with conversation reload, conversation-scoped capabilities, shared storage, and optional KDCube workspace/ISO-exec tools without turning them into ReAct.

DOCSsettle-your-solutionhosted-agent-conversation

02 Deploy and update an app without rebuilding its product logic

A KDCube app adds those runtime seams without requiring every product to use every KDCube surface:

• Declare only what this app provides: agents, API operations, jobs, MCP, widgets, named services, or a website can be added independently.
• Keep product dependencies explicit: surfaces.as_consumer connects Python tools, MCP servers, named services, and UI components without publishing them as the app's own surfaces.
• Configuration, secret references, storage ownership, interfaces, tests, and release metadata travel with the app package and stay synchronized.
• Deploy or update from source/ref: descriptor-driven loading and app reload preserve the product boundary while the platform supplies ingress, identity, streaming, and accounting.

DOCShow-to-write-an-appdelivery-and-updatedescriptor

03 Our domain has useful data and actions, but the agent cannot discover them

Wrap the existing functionality once as a named-service realm: a domain that explains its objects, searches, and permitted actions before the agent uses them.

• The realm introduces itself: the agent starts with provider.about and object.schema to learn what the domain contains, how its objects are named, how to find them, and what actions are allowed. This is the ontologic interface: the domain teaches its vocabulary and rules at runtime.
• The agent explores instead of guessing: list and search return small results with stable object refs; the agent follows a ref to read one object or run a declared, bounded action.
• Complete data remains reachable: long collections paginate, while large objects and files travel through signed delivery or into an agent's turn workspace instead of flooding every model prompt.
• One declaration serves every client: a hosted agent uses the generic named-service tools, an external agent such as Claude Code connects through MCP, and apps or widgets resolve the same refs. Caller grants and provider-side permissions still guard every operation.

DOCSbuild-a-named-servicenamed-servicesnamed-services-mcp

04 Agents and the keys to your accounts

Credentials are a lifecycle (consent → refresh → live rejection → explain → upgrade → revoke); homegrown builds cover the happy path. Connection Hub covers the loop while trusted integration code, not the model or generated-code executor, resolves provider credentials:

• Tools declare claims, not secret handling. The SDK resolves the current user's connected account and provider token inside trusted server-side code. Normal OAuth/OIDC services can be configured from endpoints, connector-app secrets, and claim-to-scope mappings; unusual protocols can still supply a provider-specific adapter.
• Live 401 → refresh once → retry once → only then mark the account + reconnect card deep-linking it, provider's real error preserved.
• Every denial is structured: reason, labeled candidates, retry hint, and an absolute Connection Hub deep link that lands on the exact fix — from chat or from an external agent relaying it.
• External agents get their own grants (mail:read, slack:write), tier-picked by the user at consent time — separate from provider claims, revocable, consent-snapshot-bound.

DOCSconnection-hubdelegate-to-external-clientsecrets-lifecycle

05 Working the company's mail and Slack on delegated trust

Two authorization gates, one coherent operation:

• Two gates, explicit: delegated namespace grants authorize the calling client at the KDCube boundary; connected-account claims authorize trusted KDCube code to call the provider for the current user.
• Consent is demand-driven — the attempt is the ask. Tools stay available; the one that hits a missing claim returns a structured ask scoped to exactly that tool's claims (never the provider's union) and raises a consent card with two exits — approve, or turn off the tools that need it — while the turn keeps working.
• Multi-account is explicit: labeled results; actions never pick an account silently.
• Files cross the boundary through signed download URLs and upload slots — bytes over HTTP, never inside tool calls.

DOCSmailslackhosting

06 Generated code without ambient platform access

KDCube separates the requester, the materialized workspace, the isolated executor, and trusted tools:

• The agent proposes; trusted resolvers decide. Logical refs and paths are untrusted locators; the resolver binds the current tenant/project/user/authority before materializing bytes.
• The executor receives a sparse workspace: in split Docker it has no network, platform or app storage roots, deployment descriptors, provider credentials, or another user's workspace.
• Trusted tools stay outside: approved calls cross the supervisor socket and execute under the carried request identity, grants, provider claims, and economics context.
• The contract is reusable: KDCube ReAct and externally authored agents such as LangGraph can use the same pull/workspace/ISO-exec boundary. Declared output files are hosted and delivery is verified rather than assumed.

DOCSexecution-boundariescross-runtime-contextiso-runtime

07 A coding agent inside automation, trusted by machines

The Claude Code harness makes the work machine-checkable:

• Dedicated, mapped workspace per session.
• Framed structured output: the agent declares what it did, in which files.
• Validators inspect exactly the declared edits; only validated work is committed.
• Deterministic session binding to user + conversation — follow-up and steer turns resume the same context. In production inside the news pipeline.

DOCSclaude-codeagent-integration

08 Scheduled pipelines that sometimes need judgement

Correct — and KDCube agrees. What decides between a cron and an agent is the trigger:

• Clock + known path → cron. The news pipeline (gather, rank, publish daily) is exactly "cron calls LLM", in production.
• A person asks → agent turn. One open intent, four domains, the plan made mid-turn.
• An event fires → conversation work. Reactive ingress appends the event to the ordered lane and admits a wake for the app's @on_reactive_event surface. If a turn is already live, eligible events fold into it; only eligible followups add bounded iteration credit.
• A wall appears → dialogue. Missing consent becomes a one-click question to the user — and dialogue is not schedulable.

Both run in the same app, on the same budget line. A scheduled step that starts needing judgement becomes an agent turn — no rewrite.

DOCSclaude-codebundle-lifecycleconversation-events

09 A timer should schedule any app work, not only agent loops

A schedule is a first-class app trigger; the app declares jobs, the platform runs them:

• Declare scheduled jobs in the app package — any operation, not only an agent turn: a report build, a sync, a publish, a cleanup.
• Runs under the app's identity and accounting — the same tenant/project/user scoping and per-run spend attribution as an interactive request; no side stack to reconcile.
• The ordered lane and long-run protection apply — a scheduled run enters the same lane, with the runtime's guard against a run that overstays its window.
• The same guard rails as a person's access — a scheduled step that needs a provider token resolves it through Connection Hub, per run, exactly like a human turn.

DOCSscheduled-jobsconversation-schedulerlongrun-protection

10 Machine access that is born disposable

Automation access is its own credential type:

• A token bound to declared resources and grants, with an expiry.
• Created and revoked in Connection Hub → Delegated by KDCube: the Granted access list shows every grant — manual tokens and OAuth-connected apps alike — each with its own Revoke.
• Revocation is immediate: record deleted, bound session logged out, next call rejected.
• Same guard rails as human access, on a credential meant to be thrown away.

DOCSautomation-access

11 The answer arrives while the agent is still working

Every conversation carries an ordered event lane; systems the agent triggers answer back into it, and the answers feed the input loop:

• The consent flow is the worked story: a tool attempt raises the ask; the user approves in Connection Hub in parallel; the grant lands in the lane as a conversation event, folds into the live turn — and the agent circles back and finishes.
• Any system can answer back: approvals, callbacks, and alerts publish into a lane scoped by tenant/project/user/conversation/agent; a live turn folds eligible events in lane order.
• Wakeup and meaning are separate: reactive ingress atomically stores the event and admits a bodyless wake. A retained task_payload decides whether unconsumed work can start a continuation; passive events wait for a live or future turn.
• Folding is total: every consumed event advances the turn's bookkeeping, even one that renders nothing — an unreadable event can never wedge a completion.

DOCSconversation-eventsbundle-eventsconnection-hub

12 One workspace, many humans

One deployment is bound to one tenant/project and may serve many users concurrently. The runtime carries the authenticated user and authority through request and cross-runtime boundaries.

• Scoped stores and resolvers: user-owned conversations, memories, connected accounts, settings, and budgets are resolved through the current request identity — not a model-supplied user id.
• Per-conversation tuning inside an admin grant: users can save a model and capability set for one conversation; nothing widens beyond the app inventory (section 13 is the deep dive).
• The scene is the shared room: summonable widgets, auth-gated chips, cross-widget drag under the dragging user's identity.
• Per-user economics from day one.

DOCSsceneeconomics-integration

13 One conversation, one saved agent setup

The app config grants the ceiling; each conversation stores its own full selection:

• Config grants the inventory: surfaces.as_consumer.agents.<id> and supported_models define what the app allows; the user can only narrow it.
• Each conversation owns a saved selection: model, tools, skills, MCP tools, named-service operations, and helper-agent choice do not leak into another conversation.
• Edits are a local draft: only Save changes persists them. Sending a message does not silently save capabilities; switching conversations discards unsaved edits.
• A future-conversation baseline is optional: a new conversation materializes it once, or starts from app configuration when no baseline exists. Later baseline edits do not rewrite old conversations.

DOCSconstruct-react-agentuser-settingschat-with-react-agent

14 One app needs to provide services and consume others

KDCube makes the direction part of the app contract:

• surfaces.as_provider says what this app exposes: API, widget, MCP, app visibility, managed auth, and default-chat intent.
• surfaces.as_consumer says what this app uses: Python tools, MCP service connections, named-service namespaces, UI resolvers, and Scene components.
• Each agent gets its own inventory: two agents in one app can consume different tools and service operations without changing the app's public surfaces.
• The directions do not leak: consuming another app's MCP server does not republish it; exposing an API does not automatically make it callable by the app's agents.

DOCSdescriptormcpagent-integration

15 Context that stays lean as capability grows

One principle: context carries bounded representations and refs; owning services hold bytes.

• Tools: a fixed named-service grammar replaces a growing set of near-synonym integration verbs; each realm self-describes its nouns, filters, operations, and action payloads.
• Payloads: lean hits carry ref, title, and snippet; bytes are fetched or hosted outside model context through workspace materialization, signed downloads, or staged uploads.
• History: searchable (conv:), never replayed; working summaries compress each turn.
• Cache: durable instructions cached; a per-turn ANNOUNCE tail carries only what changed.

DOCSnamed-services-mcpcontext-cachinghosting

16 Knowing where the context came from

Lineage survives when context enters as addressable objects instead of anonymous pasted text.

• Context objects retain canonical refs (conv:fi:…, mem:…, cnv:…, provider-owned refs); the owning resolver decides what the current requester may read.
• Search hits carry their paths back to the turn and event they came from.
• Board pins keep provenance; sharing a board shares it.
• The per-turn timeline is the ledger — "what was it looking at" is a query.

DOCScanvasconversation-search

17 Memory that survives the session

Two kinds of remembering, separated because they decay differently:

• Episodic recall (conv:): the temporal record — every turn indexed with its production context. "What did we decide in May" is one search.
• Durable knowledge (mem:): co-managed typed notes — the agent proposes, a reconciler merges, the user edits in the memory widget.
• Linked identities can resolve to one platform subject through explicit connection edges and authority projection; raw external identity does not silently become platform authority.
• Both feed the turn as retrieved, cited context under the lean-hits discipline.

DOCSmemories-reconciliationconversation-search

18 Findings scatter across conversations

Collect each finding as a pin: a URI a named service resolves, with its provenance kept:

• A pin is a reference, not a copy — a mem: / conv: / provider-owned URI that the owning named service resolves on demand, so a pin stays live and permission-checked.
• Provenance travels with the pin — which turn, which source, which event it came from; a board is a provenance-keeping desk, not a bag of dead text.
• The board is a summonable widget — pinboard mounts on the scene and in chat; drop a result onto it, open a pin back to its source.
• Share a board, share its pins — resolution runs under the reader's identity, so a shared board never leaks what the reader may not see.

DOCSpinboardpin-operationspin-integration

19 Prompt-cache costs nobody can attribute

KDCube places context by lifecycle, marks every cold turn, and hands the rebuild decision to the person who pays:

• Placement by lifecycle: durable teaching in the cached instructions; turn-local state in the uncached ANNOUNCE tail — the volatile costs nothing.
• Every deliberate invalidation is marked: the [CACHE] cold-turn marker and cache_cold_turn accounting metadata join the rebuild premium to the causing action — one identifiable component within the turn's spend sum.
• The user holds the policy: accept · confirm · defer-cold · defer-conversation (admin default + bounds); under confirm the composer turns a costly switch into an inline choice.
• Both switches are named, neither silent: a model pick rebuilds in a per-model cache namespace; a capability toggle colds one turn, then caching resumes.

DOCScontext-cachingconstruct-react-agentuser-settings

20 Agent output the web can actually find

A KDCube app publishes selected artifacts as first-class public web content:

• The app declares a public-content provider (@public_content): which items, under which public alias — the platform renders crawlable HTML with JSON-LD, canonical and OG tags at stable URLs.
• Sitemaps come from the registry: publish and retract update the per-alias sitemap; a retracted item serves 410, so stale copies fall out of indexes.
• Publishing is an operation — batched (publish_many: one lock, one generation bump), so a nightly pipeline and a Publish button are the same code path.
• A CDN fronts the origin through rewrite mapping (public URLs stay stable); the app remains the single source of truth.

DOCSpublic-contentpublic-content-providerpublish-discoverable

21 Every new internal tool is a new frontend project

A scene is config + content over a shared host; the widgets come from the apps that own them:

• Components are served widgets iframed from their owning apps — pinboard, chat, memories, usage — declared in surfaces.as_consumer.ui.scene.components (bundle_id + widget_alias).
• Behavior is config: placement: docked|floating, rail, gated auth, drop patterns routed to a target_surface.
• Context moves across surfaces: cross-surface drag, provider-resolved open actions, and surface commands — one widget summons and directs another through a declared contract — are built into the host.
• The reusable host is @kdcube/components-react/scene — a new alias mounts any deployed app's widget.

DOCSscene-configscenesurface-commands

22 The app needs a real website, not only a control-plane view

Declare the built main view as an application-hosted website:

• The declaration stays with the app: alias, hosts, and default status live in bundles.yaml, beside the main-view build they expose.
• Routing is validated and hot: an immutable ApplicationSiteCatalog carries the resolved app target; Redis distributes ordered generations and each proc routes from memory.
• Multipage and SPA paths work: direct files, directory indexes, and root index.html fallback share the standard app UI storage lifecycle.
• The CDN forwards and caches: it preserves the viewer host and rewrites to site-root; it does not own the registry. @public_content remains the separate indexed-record mechanism.

DOCSapplication-siteswebsitedescriptor

· The pattern behind the answers

Five moves keep solving different problems: identity and authority survive every boundary · untrusted requesters ask trusted resolvers · provider and consumer directions stay separate · domains describe themselves behind a fixed grammar · every denial explains its own fix.

· See these mechanisms at work