Manifest Schema

Complete reference for manifest.json (schema version 2).

Top-Level Fields

Field	Type	Required	Description
`schemaVersion`	number	Yes	Must be `2`
`id`	string	Yes	Unique identifier (lowercase alphanumeric + hyphens)
`name`	string	Yes	Human-readable name
`description`	string	Yes	What the trik does
`version`	string	Yes	Semantic version
`agent`	object	Yes	Agent definition (mode, domain, prompts)
`tools`	object	No	Tool declarations
`capabilities`	object	No	Session and storage capabilities (enforced at publish, install, and runtime)
`limits`	object	No	Execution constraints
`entry`	object	Yes	Code entry point
`config`	object	No	Configuration requirements
`author`	string	No	Author name
`repository`	string	No	Repository URL
`license`	string	No	License identifier

Full Schema Example

Conversational Mode


{
  "schemaVersion": 2,
  "id": "article-curator",
  "name": "Article Curator",
  "description": "Finds and curates articles based on your interests.",
  "version": "1.0.0",
 
  "agent": {
    "mode": "conversational",
    "handoffDescription": "Talk to the article curator to find, filter, and curate articles on any topic. Supports multi-turn refinement of search criteria.",
    "systemPromptFile": "./prompts/system.md",
    "model": {
      "provider": "anthropic",
      "capabilities": ["tool_use"],
      "temperature": 0.3
    },
    "domain": ["content curation", "article search", "RSS feeds"]
  },
 
  "tools": {
    "searchArticles": {
      "description": "Search for articles by topic",
      "logTemplate": "Searched for articles: found {{count}} results in {{category}}",
      "logSchema": {
        "count": { "type": "integer", "minimum": 0 },
        "category": { "type": "string", "enum": ["news", "blogs", "research", "docs"] }
      }
    }
  },
 
  "capabilities": {
    "session": {
      "enabled": true,
      "maxDurationMs": 1800000
    },
    "storage": {
      "enabled": true,
      "maxSizeBytes": 104857600,
      "persistent": true
    }
  },
 
  "limits": {
    "maxTurnTimeMs": 30000
  },
 
  "entry": {
    "module": "./dist/agent.js",
    "export": "default",
    "runtime": "node"
  },
 
  "config": {
    "required": [
      { "key": "API_KEY", "description": "API key for the article service" }
    ],
    "optional": [
      { "key": "MAX_RESULTS", "description": "Maximum results per search", "default": "20" }
    ]
  },
 
  "author": "molefas",
  "repository": "https://github.com/molefas/article-curator",
  "license": "MIT"
}

Tool Mode


{
  "schemaVersion": 2,
  "id": "weather-tools",
  "name": "Weather Tools",
  "description": "Get current weather and forecasts for any city.",
  "version": "1.0.0",
 
  "agent": {
    "mode": "tool",
    "domain": ["weather", "forecasting"]
  },
 
  "tools": {
    "getWeather": {
      "description": "Get current weather for a city",
      "inputSchema": {
        "type": "object",
        "properties": {
          "city": { "type": "string", "minLength": 1, "maxLength": 100 }
        },
        "required": ["city"]
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "temperature": { "type": "number" },
          "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] },
          "condition": { "type": "string", "enum": ["sunny", "cloudy", "rainy", "snowy", "windy", "stormy"] }
        },
        "required": ["temperature", "unit", "condition"]
      },
      "outputTemplate": "Current weather: {{temperature}} {{unit}}, {{condition}}"
    }
  },
 
  "limits": {
    "maxTurnTimeMs": 10000
  },
 
  "entry": {
    "module": "./dist/tools.js",
    "export": "default",
    "runtime": "node"
  },
 
  "config": {
    "required": [
      { "key": "WEATHER_API_KEY", "description": "API key for the weather service" }
    ]
  }
}

ID Format


article-curator
weather-tools

Must start with a lowercase letter
Lowercase letters, numbers, and hyphens only
Pattern: ^[a-z][a-z0-9-]*$
Must be unique in the registry

Note: The id field is the trik’s bare name. When published, the registry combines this with the publisher’s verified scope to form the scoped name (e.g., @alice/weather-tools), which is used for resource isolation (storage, config, containers).

Agent

The agent block defines how the trik operates. This is the core of the v2 manifest.

Agent Definition


interface AgentDefinition {
  mode: 'conversational' | 'tool';
  handoffDescription?: string;
  systemPrompt?: string;
  systemPromptFile?: string;
  model?: ModelPreferences;
  domain: string[];
}

Mode

Mode	Description
`conversational`	Agent with LLM. Receives user messages via handoff, can have multi-turn conversations, transfers back when done.
`tool`	Exports native tools to the main agent. No handoff, no session, no LLM. Tools execute directly.

Fields by Mode

Field	Conversational	Tool
`mode`	Required	Required
`handoffDescription`	Required (10-500 chars)	Must not be present
`systemPrompt`	One of systemPrompt/systemPromptFile required	Unnecessary (warning)
`systemPromptFile`	One of systemPrompt/systemPromptFile required	Unnecessary (warning)
`model`	Optional	Optional
`domain`	Required (min 1 tag)	Required (min 1 tag)

handoffDescription

The handoffDescription generates the handoff tool that the main agent uses to route users to your trik. Write it as a clear description of what the user can do with your trik.


{
  "handoffDescription": "Talk to the article curator to find, filter, and curate articles on any topic. Supports multi-turn refinement of search criteria."
}

Required for conversational mode
Minimum 10 characters, maximum 500 characters
Must not be present for tool mode

systemPrompt / systemPromptFile

Define the system prompt for your conversational agent. Use one or the other, not both.


{
  "systemPrompt": "You are an article curator. Help users find and organize articles."
}

Or load from a file:


{
  "systemPromptFile": "./prompts/system.md"
}

systemPromptFile is relative to the manifest directory
Exactly one is required for conversational mode
Both are mutually exclusive (error if both present)

model (ModelPreferences)


{
  "model": {
    "provider": "anthropic",
    "capabilities": ["tool_use"],
    "temperature": 0.3
  }
}

Field	Type	Description
`provider`	string	Provider hint: `"anthropic"`, `"openai"`, `"any"`
`capabilities`	string[]	Required model capabilities, e.g., `["tool_use"]`
`temperature`	number	Generation temperature (0.0 - 2.0)

domain

An array of domain tags describing the trik’s area of expertise. Used for routing decisions and registry search.


{
  "domain": ["content curation", "article search", "RSS feeds"]
}

At least one tag is required
Use specific tags. Generic tags like "general", "utility", "misc" produce a validation warning.

Tools

The tools block declares the tools your trik uses. The structure differs between conversational and tool mode.


interface ToolDeclaration {
  description: string;
  logTemplate?: string;
  logSchema?: Record<string, JSONSchema>;
  inputSchema?: JSONSchema;
  outputSchema?: JSONSchema;
  outputTemplate?: string;
}

Conversational Mode Tools

For conversational triks, tools are metadata for logging and quality scoring. The actual runtime tool schemas live in your code (as LangChain tools).


{
  "tools": {
    "searchArticles": {
      "description": "Search for articles by topic",
      "logTemplate": "Searched for articles: found {{count}} results in {{category}}",
      "logSchema": {
        "count": { "type": "integer", "minimum": 0 },
        "category": { "type": "string", "enum": ["news", "blogs", "research", "docs"] }
      }
    }
  }
}

Field	Required	Description
`description`	Yes	What the tool does
`logTemplate`	No	Template for log entries. Placeholders: `{{field}}`
`logSchema`	No	Schema for log template placeholder values

Tool Mode Tools

For tool-mode triks, tools define the full runtime contract. The gateway uses these schemas for input validation, output validation, and template-based responses.


{
  "tools": {
    "getWeather": {
      "description": "Get current weather for a city",
      "inputSchema": {
        "type": "object",
        "properties": {
          "city": { "type": "string", "minLength": 1, "maxLength": 100 }
        },
        "required": ["city"]
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "temperature": { "type": "number" },
          "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] },
          "condition": { "type": "string", "enum": ["sunny", "cloudy", "rainy", "snowy"] }
        },
        "required": ["temperature", "unit", "condition"]
      },
      "outputTemplate": "Current weather: {{temperature}} {{unit}}, {{condition}}"
    }
  }
}

Field	Required	Description
`description`	Yes	What the tool does
`inputSchema`	Yes	JSON Schema for tool input
`outputSchema`	Yes	JSON Schema for tool output (constrained types)
`outputTemplate`	Yes	Template for output sent to the main LLM

Tool mode requires at least one tool in the tools map.

Log Templates

Log templates create human-readable summaries of tool calls during a handoff session. The gateway fills {{placeholders}} from the tool’s output data.


{
  "logTemplate": "Searched for articles: found {{count}} results in {{category}}",
  "logSchema": {
    "count": { "type": "integer", "minimum": 0 },
    "category": { "type": "string", "enum": ["news", "blogs", "research", "docs"] }
  }
}

Rules:

Every {{placeholder}} in logTemplate must have a matching entry in logSchema
All logSchema values must be constrained types (see TDPS section below)

Output Templates

Output templates control what the main LLM sees when a tool-mode tool executes. The gateway fills {{placeholders}} from the validated output data.


{
  "outputTemplate": "Current weather: {{temperature}} {{unit}}, {{condition}}"
}

Rules:

Every {{placeholder}} in outputTemplate must match a property in outputSchema
Properties in outputSchema not referenced in outputTemplate produce a warning

TDPS Type Constraints

TrikHub uses a Trik Data Provenance System (TDPS) to prevent prompt injection. Values that flow into the main agent’s context must be constrained.

logSchema Constraints

For logSchema, strings must have at least one constraint:

Constraint	Example
`enum`	`{ "type": "string", "enum": ["news", "blogs"] }`
`format`	`{ "type": "string", "format": "date" }`
`pattern`	`{ "type": "string", "pattern": "^[A-Z]{2}$" }`
`maxLength`	`{ "type": "string", "maxLength": 100 }`

Non-string primitives (integer, number, boolean) are always safe and require no additional constraints.

Unconstrained strings (no enum, format, pattern, or maxLength) are rejected.

outputSchema Constraints (Stricter)

For outputSchema in tool-mode triks, the rules are stricter. Strings must have one of:

Constraint	Example
`enum`	`{ "type": "string", "enum": ["sunny", "cloudy"] }`
`format`	`{ "type": "string", "format": "uuid" }`
`pattern`	`{ "type": "string", "pattern": "^[a-z0-9-]+$" }`

maxLength alone is NOT sufficient for outputSchema. A string with only maxLength is still free-form and can carry arbitrary content into the main agent’s context. Use enum, format, or pattern instead.

Non-string primitives (integer, number, boolean) are always safe.

Constraint Summary

Schema	`enum`	`format`	`pattern`	`maxLength` only
`logSchema`	OK	OK	OK	OK
`outputSchema`	OK	OK	OK	Rejected

Capabilities

Enforcement: Capabilities are cross-checked against source code by the scanner. At publish time, undeclared capabilities block publishing. At install time, mismatches produce warnings. At runtime, the gateway enforces each capability (storage quotas, container isolation, registry access).

Session

Cross-turn memory for conversational triks. The gateway creates and manages sessions.


{
  "capabilities": {
    "session": {
      "enabled": true,
      "maxDurationMs": 1800000
    }
  }
}

Field	Type	Default	Description
`enabled`	boolean	—	Required. Enable session support.
`maxDurationMs`	number	1800000	Session timeout in ms (default 30 minutes)

Storage

Persistent key-value storage, scoped per trik. The gateway enforces size quotas.


{
  "capabilities": {
    "storage": {
      "enabled": true,
      "maxSizeBytes": 104857600,
      "persistent": true
    }
  }
}

Field	Type	Default	Description
`enabled`	boolean	—	Required. Enable persistent storage.
`maxSizeBytes`	number	104857600	Max storage size in bytes (default 100MB)
`persistent`	boolean	true	Persist across sessions

Filesystem

Sandboxed file access inside a Docker container. The trik gets a mounted /workspace directory for reading and writing files.


{
  "capabilities": {
    "filesystem": {
      "enabled": true,
      "maxSizeBytes": 524288000
    }
  }
}

Field	Type	Default	Description
`enabled`	boolean	—	Required. Enable filesystem access.
`maxSizeBytes`	number	524288000	Max workspace size in bytes (default 500MB)

Shell

Command execution inside the container. Requires filesystem to also be enabled. Allows running processes, starting dev servers, and exposing ports to the host.


{
  "capabilities": {
    "shell": {
      "enabled": true,
      "timeoutMs": 30000,
      "maxConcurrent": 3,
      "exposePorts": [3000]
    }
  }
}

Field	Type	Default	Description
`enabled`	boolean	—	Required. Enable shell command execution.
`timeoutMs`	number	30000	Max time per command in ms
`maxConcurrent`	integer	3	Max concurrent processes
`exposePorts`	integer[]	—	Ports to expose from container to host (1–65535). Ports below 1024 are blocked at runtime.

Trik Management

Allows the trik to search, install, uninstall, and upgrade other triks via the registry. The gateway injects a registry context only when this capability is declared. Users are warned about this capability during install.


{
  "capabilities": {
    "trikManagement": {
      "enabled": true
    }
  }
}

Field	Type	Default	Description
`enabled`	boolean	—	Required. Enable trik management.

Limits


{
  "limits": {
    "maxTurnTimeMs": 30000
  }
}

Field	Type	Required	Description
`maxTurnTimeMs`	number	Yes	Maximum time per turn in milliseconds

When limits is present, maxTurnTimeMs is required.

Entry Point


{
  "entry": {
    "module": "./dist/agent.js",
    "export": "default",
    "runtime": "node"
  }
}

Field	Type	Required	Description
`module`	string	Yes	Path to compiled module (relative to trik directory)
`export`	string	Yes	Export name (usually `"default"`)
`runtime`	string	No	`"node"` (default) or `"python"`

Configuration

Declare required and optional configuration values (API keys, tokens, etc.):


{
  "config": {
    "required": [
      { "key": "API_KEY", "description": "API key for the article service" }
    ],
    "optional": [
      { "key": "MAX_RESULTS", "description": "Maximum results per search", "default": "20" }
    ]
  }
}

ConfigRequirement

Field	Type	Required	Description
`key`	string	Yes	Configuration key name
`description`	string	Yes	Human-readable description
`default`	string	No	Default value (typically used with optional configs)

Config values are managed via ~/.trikhub/secrets.json (global) and .trikhub/secrets.json (local). The gateway validates that all required config values are present before executing a trik.

Enforcement Status

Fields have different enforcement behaviors at runtime:

Field	Enforcement	Description
`agent.mode`	Enforced	Gateway loads trik as conversational (handoff) or tool (exposed tools)
`agent.handoffDescription`	Enforced	Gateway generates handoff tool from this description
`agent.domain`	Declarative	Used for routing hints and registry search
`tools.*.logTemplate`	Enforced	Gateway fills templates from tool call output data
`tools.*.logSchema`	Enforced	Validator rejects unconstrained types
`tools.*.inputSchema`	Enforced	Gateway validates tool-mode input against schema
`tools.*.outputSchema`	Enforced	Gateway validates tool-mode output; strips undeclared properties
`tools.*.outputTemplate`	Enforced	Gateway fills template and returns as tool result
`capabilities.session`	Enforced	Gateway creates/manages sessions based on these settings
`capabilities.storage`	Enforced	Gateway provides storage context and enforces quotas
`capabilities.filesystem`	Enforced	Gateway runs trik in Docker container with mounted workspace
`capabilities.shell`	Enforced	Gateway runs trik in Docker container with command execution. Requires filesystem.
`capabilities.trikManagement`	Enforced	Gateway injects registry context only when declared
`limits.maxTurnTimeMs`	Enforced	Gateway aborts trik execution after timeout
`config.required`	Enforced	Gateway validates presence before trik execution
`config.optional`	Declarative	Defaults applied if values not provided

Enforced fields are validated and enforced by the gateway at runtime. Declarative fields inform tooling and registry but are not strictly runtime-enforced.

JSON Schema Types

Supported JSON Schema features in tool declarations:

Type	Supported
`string`	Yes
`integer`	Yes
`number`	Yes
`boolean`	Yes
`array`	Yes
`object`	Yes

Supported keywords:

type, enum, const
properties, required, additionalProperties
items, minItems, maxItems
minimum, maximum, minLength, maxLength
pattern, format
description, default