CoCreate Server AI

Headless AI execution for a CoCreate server. The module connects an AI runtime to existing server services, streams responses over WebSocket, and keeps tenant boundaries outside model control.

The GitHub Copilot SDK is the runtime adapter. The public contract remains CoCreate data and messages: callers do not interact with SDK sessions directly.

Runtime contract

Initialize the module with the complete CoCreate server object:

import ServerAI from "@cocreate/ai";

server.ai = await ServerAI.init(server);

The following server capabilities are used:

• server.crud.send(data) for configuration, history, and virtual files
• server.api.send(data) for configured external APIs
• server.send(data) for server and worker routing
• server.wsManager.send(data) for browser messages
• server.files, server.storage, server.routes, and server.autoscaler for their corresponding tools

server.crud.send, server.wsManager.on, and server.wsManager.send are required parts of the server runtime. The module uses them directly and does not maintain defensive substitutes for an incomplete server object.

WebSocket messages

The primary interface is a WebSocket message:

{
    method: "ai.chat",
    uuid: "one-shot-request-uuid",
    ai: {
        prompt: "Create a customer through our configured Stripe API",
        conversation_id: "optional-existing-conversation-id",
        provider: "copilot",
        model: "gpt-5-mini",
        context: {}
    }
}

Socket authentication places organization_id, host, user_id, and clientId on the top-level data object before this module receives it. The AI runtime reads that canonical data directly; values inside ai or tool arguments cannot replace the authenticated context.

Every response uses method: "ai.chat". stream_id correlates every message in the stream, while the one-shot request uuid is returned only by the terminal message. Responses target the current clientId with broadcast: false and streaming messages use log: false.

{
    method: "ai.chat",
    stream_id: "stable-stream-id",
    ai: {
        status: "streaming",
        conversation_id: "...",
        delta: "partial text"
    }
}

{
    method: "ai.chat",
    stream_id: "stable-stream-id",
    uuid: "original-request-uuid",
    ai: {
        status: "complete",
        conversation_id: "...",
        content: "complete response"
    }
}

Failures use the same method with ai.status: "error", the same stream_id, and the terminal request uuid.

Programmatic API

init(server) returns:

• config, the final merged AI configuration
• send(data) to execute and stream one turn
• stop() to stop cached runtime clients

Conversation headers are stored in ai-conversations. Individual turns are stored in ai-messages and reference conversation_id. Client-side conversation listing, reading, and deletion use the normal CoCreate CRUD interface rather than additional AI methods.

Providers

Provider definitions live in ai.providers. Credentials and base URLs are resolved from active records in the tenant's apis collection. Credentials never fall back to another organization.

{
    providers: {
        copilot: {
            api: "copilot",
            type: "copilot",
            models: {
                default: "gpt-5-mini",
                allowed: ["gpt-5-mini"]
            }
        },
        openai: {
            api: "openai",
            type: "openai",
            wireApi: "responses",
            models: {
                default: "gpt-5-mini",
                allowed: ["gpt-5-mini", "gpt-5"]
            }
        }
    }
}

copilot uses the API record key as a GitHub token. Other provider types use the SDK's custom-provider session interface and use the URL from that active API record. Supported custom types are openai, azure, and anthropic.

Tools and security

Tool names, descriptions, and parameter schemas are application-owned configuration under ai.tools. The files in src/tools contain only executable handlers and security enforcement. At runtime each handler is matched to its configuration by tool name.

Request-sensitive tools capture the authenticated organization_id, while shared tool handlers receive the authenticated request context when bound to a session. Tenant identity is not part of any model-facing tool schema.

The default tools bridge to CRUD, configured APIs, virtual and optional local files, client sockets, server routing, cluster storage and topology, dynamic routes, and autoscaling.

Platform operations require the authenticated organization to equal server.organization_id. Local filesystem tools are disabled by default. When enabled, paths remain confined to localFsRoot; built-in shell and unrestricted file permissions remain denied.

Configuration

Configuration is loaded from @cocreate/config under ai and merged with matching servers_config records of type: "ai".

Common keys include enabled, defaultProvider, providers, tools, systemInstructions, defaultStorageTarget, allowLocalFileSystem, allowUnconfirmedLocalWrite, localFsRoot, and publicPath. Each provider owns its default and allowed models.

The application-owned seed configuration lives in CoCreate-app/src/apps/servers/configs/config/ai.js. This package reads the resulting servers_config records at runtime and does not publish its own seed copy.

Test

npm test

License

AGPL-3.0. See LICENSE.