| name | teleton-plugin-builder |
|---|---|
| description | Build and maintain Teleton plugins that comply with the SDK v2 capability and marketplace policy. |
Use this workflow when creating or updating a plugin in this repository.
Before editing, read:
CONTRIBUTING.mdfor the normative contract.compatibility.jsonfor the current SDK policy.plugins/example/index.jsfor a static tool.plugins/example-sdk/index.jsfor an SDK v2 plugin.references/patterns.mdfor safe implementation patterns.
The public API is defined by @teleton-agent/sdk@^2. Do not infer APIs from old plugins.
- Inspect the requested plugin, related manifests and existing tool names.
- Choose a static
toolsarray ortools(sdk). - State the proposed tools, parameters, scopes, categories, secrets and side effects.
- Implement
index.js,manifest.jsonandREADME.md. - Add a
package.jsonand lockfile only when external dependencies are necessary. - Add or update the plugin's
compatibility.jsonentry. - Run
npm run generate; supported production-ready plugins enterregistry.jsonautomatically. - Run the full repository validation commands.
Use a static tools array when the plugin only performs local computation or calls an external API
without Teleton state, Telegram actions, wallet operations, secrets or persistence.
Use tools(sdk) when the plugin needs any public SDK capability:
sdk.telegram;sdk.ton;sdk.secrets;sdk.storageorsdk.db;sdk.pluginConfig;sdk.log;- lifecycle or bot capabilities declared by the SDK.
- SDK plugins declare
sdkVersion: "^2.0.0"in both runtime and disk manifests. - Every tool declares
scopeandcategory. - Action tools are safe under retry and compatible with explicit owner approval.
- Secrets are declared and accessed through
sdk.secrets. - State is stored only through the isolated plugin database or storage SDK.
- External requests have timeouts and bounded inputs and outputs.
- Tool errors never expose credentials, wallet data or unbounded upstream payloads.
Never use:
sdk.telegram.getRawClient();context.bridgeorctx.bridge;- direct GramJS access through Teleton internals;
wallet.json, mnemonic reads or direct signing;- private Teleton modules as an undeclared API;
- global environment variables for secrets.
If the SDK lacks a required capability, do not create an escape hatch. Preserve the plugin as
quarantined, set its range to ^1.0.0, explain the blocker in compatibility.json, and keep it out
of the generated registry.json.
export const manifest = {
name: "my-plugin",
version: "1.0.0",
sdkVersion: "^2.0.0",
description: "Describe the capability",
};
export const tools = (sdk) => [
{
name: "my_plugin_lookup",
description: "Look up a value without changing external state",
scope: "always",
category: "data-bearing",
parameters: {
type: "object",
properties: {
query: { type: "string", minLength: 1, maxLength: 200 },
},
required: ["query"],
},
async execute(params) {
try {
const response = await fetch(
`https://api.example.com/search?q=${encodeURIComponent(params.query)}`,
{ signal: AbortSignal.timeout(15_000) }
);
if (!response.ok) return { success: false, error: `Upstream returned ${response.status}` };
return { success: true, data: await response.json() };
} catch (error) {
sdk.log.warn("Lookup failed");
return { success: false, error: String(error?.message ?? error).slice(0, 500) };
}
},
},
];Run from the repository root with ../teleton-agent available:
npm ci --ignore-scripts
npm run install:plugins
npm run generate
npm run validate
npm test
npm --prefix ../teleton-agent run build:sdk
npm run validate:runtime
npm run audit:pluginsDo not claim completion if any command fails. Do not push, publish or install into a live agent unless the user explicitly requests it.