Space Apps

Tools in the apps scope, callable over space-mcp (tools/call) or space-api (REST) with a wks_live_* key that grants apps.

create_app

Scope: apps:write

Create a new agent-authored Space App (trust_tier='user'). STANDALONE RULE: the app's core function must work for a human with your computer OFF — wire generation through wakato.gateway.* (billed/attributed to the APP), and declare any genuinely machine-dependent work in app_schema.agent_features (a portable skill contract: label + executable instructions + machine_requirements) instead of silently doing it yourself and inserting records. Declare required_capabilities in app_schema; they become consent-pending until a space admin approves them. Authoring is free — no wallet charge. ui_code is VALIDATED on save (real JS syntax check + runtime-fatal lint) and rejected with actionable errors if broken. Required workflow: get_app_sdk_reference → create_app → test_app (actually run it) → publish_app.

create_app_data_record

Scope: apps:write

Create a record in a Space App's data store under a model. record_data should match the app's schema for that model.

define_model

Scope: apps:write

Define/merge a data model (record type) into the app's schema. Data is stored as JSONB; no migration needed.

delete_app

Scope: apps:delete

PERMANENTLY delete an agent-authored Space App: uninstalls it (if published) and removes its code, data records, version history and change log. Cannot be undone — there is no trash. Requires the OPT-IN apps:delete permission, which is NOT part of default/full access; if you can see this tool, the owner explicitly granted it to this key. Prefer update/rollback over delete-and-recreate: deleting destroys user data and history. Pass the app's exact current name in confirm_app_name to confirm.

delete_app_data_record

Scope: apps:write

Delete a record from a Space App's data store.

edit_app_code

Scope: apps:write

PREFERRED way to fix/change an existing app: surgical find-and-replace edits inside ui_code, so you never resend the whole document for a small change (faster, cheaper, and immune to output truncation). Each edit's old_string must match the current code EXACTLY (including whitespace) and be unique unless replace_all. The patched result is validated like a full save (syntax + lint + auto-declared capabilities); a failed patch keeps the previous working code. Read the current code with get_app first. PUBLISHED apps: if this key has the apps Publish permission (apps:run — agent keys have it by default), the patched code goes LIVE immediately with a version snapshot for rollback; without it, edits stage as a pending draft only the space owner can publish. ALWAYS pass change_description.

get_app

Scope: apps:read

Get a single app including its ui_code, app_files and schema.

get_app_data_record

Scope: apps:read

Get one Space App record by id (full record_data).

get_app_logs

Scope: apps:read

Read an app's recent errors so you can diagnose and fix it after a test run: the latest uncaught runtime/render error (e.g. blank render) plus recent SDK-call failures (e.g. a denied capability or gateway error). Call this after a user opens the app if something looks wrong.

get_app_sdk_reference

Scope: apps:read

Get the full window.wakato in-app SDK reference — every method an app's ui_code can call (data, gateway/AI, contacts, sms, messaging, social, assets, calendar, bank, etc.), response shapes, and which capability to declare for each. Call this BEFORE writing or updating an app's ui_code so you use real methods. Free.

get_app_share

Scope: apps:read

Get an app's active external share: full config, the share URL, and headline analytics (page views, unique visitors, total visits, visitor AI spend this month and all-time). Returns { share: null } if the app is not currently shared.

get_app_version

Scope: apps:read

Get one snapshot from an app's version history, including its ui_code and schema — useful to diff against the current code when hunting a regression.

grant_app_capabilities

Scope: apps:run

Approve (enable) an app's requested capabilities so it can use them at runtime — data access, AI models (gateway.*, billed to the space wallet), asset uploads, etc. Grants ONLY capabilities the app declared in required_capabilities (least-privilege). publish_app already auto-grants declared capabilities, so use this mainly to re-enable after a revoke or grant a specific subset. Requires apps:run.

introspect_capabilities

Scope: apps:read

Discover what AI models and services this space can use (and which are enabled vs available-but-off), plus the full list of app capability keys. Call this BEFORE building so you know what to declare and what the user may need to enable.

list_app_data_models

Scope: apps:read

List the data models a Space App actually has records for (model_key + record count). Use this to discover what data the app holds before querying.

list_app_versions

Scope: apps:read

List an app's published version history (every publish_app and rollback records a permanent snapshot). Returns version_number, note, created_at. Use get_app_version for a version's code, rollback_app to restore one.

list_app_visitors

Scope: apps:read

Per-visitor analytics for an app's active external share: email (null for anonymous guests on open public shares), first/last seen, visit count, total time in app, and AI spend. Most recent first, up to 500.

list_apps

Scope: apps:read

List platform-hosted Space Apps in this space (id, name, status, trust tier, granted capabilities).

present_app

Scope: apps:read

Show a Space App live in the user's Space Computer panel (Apps & Pages tab). Call it when you start building or changing an app, or when the user asks to open/see one, so they can watch it live. UI-only signal — succeeds even if the panel is closed, and stores nothing.

preview_app

Scope: apps:read

Static validation of an app: ui_code present, real JS syntax check of every <script> block, capabilities known + declared for every SDK call used, pipelines well-formed. Returns { ok, issues, warnings } — issues BLOCK publish_app. Free. For an actual execution test, use test_app.

publish_app

Scope: apps:run

Publish an app FOR THE FIRST TIME: install it into the space so members can open it AND auto-grant the capabilities it declared so it's ready to use immediately (no separate owner approval step). Least-privilege: only declared capabilities are granted; gateway (AI model) usage bills the space wallet, and the owner can revoke any capability from the App Inspector. BLOCKS if validation fails (syntax errors, missing preact-ready guard, undeclared capabilities) — run test_app first so you publish code you have actually seen run. On an ALREADY-PUBLISHED app with a pending draft, this PROMOTES the draft live (update_app/edit_app_code already do this automatically when you hold this permission). Requires apps:run (Publish).

query_app_data

Scope: apps:read

Read a Space App's stored records for one model (the rows the app's window.wakato.data lives on). Paginated, newest first.

revoke_app_capabilities

Scope: apps:run

Revoke an app's granted capabilities so it can no longer use them at runtime. Omit capabilities to revoke everything, or pass specific keys to revoke a subset. Requires apps:run.

revoke_app_share

Scope: apps:run

Turn off an app's external sharing: the /a/<token> link stops working IMMEDIATELY and every visitor session dies with it. Visitor data and analytics are kept. Sharing again later (share_app) mints a NEW link — the old URL stays dead.

rollback_app

Scope: apps:write

EMERGENCY RESTORE: set the app's live code/schema back to a published version (from list_app_versions) — use this FIRST when a published app is crashing for users, then fix calmly and re-publish. Records the restore as a new version (history stays append-only) and clears the crash latch.

share_app

Scope: apps:run

Share a platform-hosted app with people OUTSIDE the space via an external link (https://wakato.io/a/&lt;token>). Creates the app's single active share, or updates it if one exists (settings apply live). access_level: 'link' = anyone with the link, email-verified · 'invite' = only invited_emails (requires at least one; pass keep_invited_emails to update other settings without resending the list) · 'public' = open link where require_email:false may relax the email gate. AI for visitors is OFF by default; ai_enabled:true REQUIRES visitor_daily_cap AND share_monthly_cap above $0 — visitor AI usage bills the SPACE wallet, so confirm budgets with the owner before enabling. data_mode: 'isolated' (default — each visitor gets a private data sandbox) or 'shared' (visitors work in the space's shared app data); shared_read_models optionally exposes listed models read-only in isolated mode. Returns { share, share_url } — give share_url to the user. Requires the apps Publish permission.

test_app

Scope: apps:read

REALLY RUN the app before publishing: mints a short-lived test URL that renders the app exactly like production (same framework, same sandbox CSP) but answers all window.wakato.* SDK calls with harmless test-mode mocks (no wallet charges, no real data). Open the URL in headless Chrome on your machine and read the verdict: <title> becomes WAKATO_TEST_PASS/WAKATO_TEST_FAIL and <script id="wakato_test_results"> holds JSON with runtime_errors, sdk_calls and a render report. ALWAYS run this after saving ui_code and fix failures before publish_app. Free.

update_app

Scope: apps:write

Update an agent-authored app's ui_code, app_files, schema or metadata. STANDALONE RULE applies: core function via wakato.gateway.* in-app; machine-dependent work declared in app_schema.agent_features and queued via wakato.agent.requestWork — never a silent records-viewer for work you do on your machine. ui_code is VALIDATED on save (real JS syntax check + runtime-fatal lint); a rejected update keeps the previous working code in place. PUBLISHED apps: if this key has the apps Publish permission (apps:run — agent keys have it by default), your change goes LIVE immediately with a version snapshot for rollback; without it, the change is staged as a pending draft only the space owner can publish. ALWAYS pass change_description (one line, owner-facing). After a successful update, run test_app before telling the user it's ready.

update_app_data_record

Scope: apps:write

Update a Space App record. record_data is shallow-merged into the existing record by default; pass replace:true to overwrite it wholesale.