@elisym/sdk 0.4.0 → 0.5.0

package/dist/agent-store.d.cts

@@ -0,0 +1,334 @@
+import { z } from 'zod';
+
+/**
+ * Zod schemas for elisym.yaml (public source of truth) and secrets.json (private).
+ * Shared between CLI (provider mode) and MCP (customer mode, future provider mode).
+ */
+
+declare const AgentNameSchema: z.ZodString;
+declare const PaymentSchema: z.ZodObject<{
+    chain: z.ZodLiteral<"solana">;
+    network: z.ZodEnum<["devnet"]>;
+    address: z.ZodString;
+    token: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    chain: "solana";
+    network: "devnet";
+    address: string;
+    token?: string | undefined;
+}, {
+    chain: "solana";
+    network: "devnet";
+    address: string;
+    token?: string | undefined;
+}>;
+declare const LlmSchema: z.ZodObject<{
+    provider: z.ZodEnum<["anthropic", "openai"]>;
+    model: z.ZodString;
+    max_tokens: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    provider: "anthropic" | "openai";
+    model: string;
+    max_tokens: number;
+}, {
+    provider: "anthropic" | "openai";
+    model: string;
+    max_tokens?: number | undefined;
+}>;
+declare const SecurityFlagsSchema: z.ZodObject<{
+    withdrawals_enabled: z.ZodDefault<z.ZodBoolean>;
+    agent_switch_enabled: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    withdrawals_enabled: boolean;
+    agent_switch_enabled: boolean;
+}, {
+    withdrawals_enabled?: boolean | undefined;
+    agent_switch_enabled?: boolean | undefined;
+}>;
+/**
+ * elisym.yaml schema. Public - committed to git.
+ * Agent name NOT stored here - derived from containing folder name.
+ */
+declare const ElisymYamlSchema: z.ZodObject<{
+    /** Human-readable name shown in UI (optional). Falls back to folder name. */
+    display_name: z.ZodOptional<z.ZodString>;
+    description: z.ZodDefault<z.ZodString>;
+    /** Relative path (to this YAML) or absolute URL. */
+    picture: z.ZodOptional<z.ZodString>;
+    /** Relative path (to this YAML) or absolute URL. */
+    banner: z.ZodOptional<z.ZodString>;
+    relays: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    payments: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        chain: z.ZodLiteral<"solana">;
+        network: z.ZodEnum<["devnet"]>;
+        address: z.ZodString;
+        token: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        chain: "solana";
+        network: "devnet";
+        address: string;
+        token?: string | undefined;
+    }, {
+        chain: "solana";
+        network: "devnet";
+        address: string;
+        token?: string | undefined;
+    }>, "many">>;
+    llm: z.ZodOptional<z.ZodObject<{
+        provider: z.ZodEnum<["anthropic", "openai"]>;
+        model: z.ZodString;
+        max_tokens: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        provider: "anthropic" | "openai";
+        model: string;
+        max_tokens: number;
+    }, {
+        provider: "anthropic" | "openai";
+        model: string;
+        max_tokens?: number | undefined;
+    }>>;
+    security: z.ZodDefault<z.ZodObject<{
+        withdrawals_enabled: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+        agent_switch_enabled: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+    }, "strip", z.ZodTypeAny, {
+        withdrawals_enabled?: boolean | undefined;
+        agent_switch_enabled?: boolean | undefined;
+    }, {
+        withdrawals_enabled?: boolean | undefined;
+        agent_switch_enabled?: boolean | undefined;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    description: string;
+    relays: string[];
+    payments: {
+        chain: "solana";
+        network: "devnet";
+        address: string;
+        token?: string | undefined;
+    }[];
+    security: {
+        withdrawals_enabled?: boolean | undefined;
+        agent_switch_enabled?: boolean | undefined;
+    };
+    display_name?: string | undefined;
+    picture?: string | undefined;
+    banner?: string | undefined;
+    llm?: {
+        provider: "anthropic" | "openai";
+        model: string;
+        max_tokens: number;
+    } | undefined;
+}, {
+    display_name?: string | undefined;
+    description?: string | undefined;
+    picture?: string | undefined;
+    banner?: string | undefined;
+    relays?: string[] | undefined;
+    payments?: {
+        chain: "solana";
+        network: "devnet";
+        address: string;
+        token?: string | undefined;
+    }[] | undefined;
+    llm?: {
+        provider: "anthropic" | "openai";
+        model: string;
+        max_tokens?: number | undefined;
+    } | undefined;
+    security?: {
+        withdrawals_enabled?: boolean | undefined;
+        agent_switch_enabled?: boolean | undefined;
+    } | undefined;
+}>;
+type ElisymYaml = z.infer<typeof ElisymYamlSchema>;
+type PaymentEntry = z.infer<typeof PaymentSchema>;
+type LlmEntry = z.infer<typeof LlmSchema>;
+type SecurityFlags = z.infer<typeof SecurityFlagsSchema>;
+/**
+ * secrets.json schema. Private - .gitignore.
+ * Values may be plaintext or `encrypted:v1:...` blobs (AES-256-GCM + scrypt).
+ */
+declare const SecretsSchema: z.ZodObject<{
+    nostr_secret_key: z.ZodString;
+    solana_secret_key: z.ZodOptional<z.ZodString>;
+    llm_api_key: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    nostr_secret_key: string;
+    solana_secret_key?: string | undefined;
+    llm_api_key?: string | undefined;
+}, {
+    nostr_secret_key: string;
+    solana_secret_key?: string | undefined;
+    llm_api_key?: string | undefined;
+}>;
+type Secrets = z.infer<typeof SecretsSchema>;
+interface MediaCacheEntry {
+    url: string;
+    sha256: string;
+    uploaded_at: string;
+}
+declare const MediaCacheEntrySchema: z.ZodType<MediaCacheEntry>;
+declare const MediaCacheSchema: z.ZodRecord<z.ZodString, z.ZodType<MediaCacheEntry, z.ZodTypeDef, MediaCacheEntry>>;
+type MediaCache = z.infer<typeof MediaCacheSchema>;
+
+/**
+ * Path helpers for .elisym/ layout.
+ *
+ * Project-local (walk up from CWD until .git or $HOME):
+ *   <project>/.elisym/<name>/{elisym.yaml, .secrets.json, .media-cache.json, .jobs.json, .gitignore}
+ *
+ * Home-global (~/.elisym/<name>/): same file structure.
+ *
+ * Node.js only - relies on `node:fs`/`node:os`/`node:path`.
+ */
+declare const ELISYM_DIRNAME = ".elisym";
+declare const YAML_FILENAME = "elisym.yaml";
+declare const SECRETS_FILENAME = ".secrets.json";
+declare const MEDIA_CACHE_FILENAME = ".media-cache.json";
+declare const JOBS_FILENAME = ".jobs.json";
+declare const GITIGNORE_FILENAME = ".gitignore";
+declare const SKILLS_DIRNAME = "skills";
+/** ~/.elisym/ */
+declare function homeElisymDir(): string;
+/**
+ * Walk up from `startDir` looking for `.elisym/` directory.
+ * Stops at (a) the first `.git` directory/file, (b) `$HOME`, (c) filesystem root,
+ * or (d) MAX_WALK_UP_DEPTH iterations. Returns absolute path or null.
+ */
+declare function findProjectElisymDir(startDir: string): string | null;
+interface AgentPaths {
+    dir: string;
+    yaml: string;
+    secrets: string;
+    mediaCache: string;
+    jobs: string;
+    gitignore: string;
+    skills: string;
+}
+/** Compute all file/dir paths for an agent given its root directory. */
+declare function agentPaths(agentDir: string): AgentPaths;
+
+/**
+ * Agent resolution: find <name>/elisym.yaml via project-local walk-up, fallback to home.
+ */
+
+type AgentSource = 'project' | 'home';
+interface ResolvedAgent {
+    name: string;
+    dir: string;
+    source: AgentSource;
+    /** true when both a project-local and a home-global agent exist with the same name. */
+    shadowsGlobal: boolean;
+}
+/**
+ * Resolve an agent by name. Precedence: project-local beats home-global.
+ * Returns null if not found in either location.
+ */
+declare function resolveAgent(name: string, cwd: string): ResolvedAgent | null;
+/** Return project-local agent dir if its YAML exists, else null. */
+declare function resolveInProject(name: string, cwd: string): string | null;
+/** Return home-global agent dir if its YAML exists, else null. */
+declare function resolveInHome(name: string): string | null;
+/** Path to the .elisym root (project or home) for a given target. */
+declare function elisymRootFor(target: AgentSource, cwd: string): string | null;
+
+/**
+ * Load an agent: parse elisym.yaml + .secrets.json, decrypt if encrypted.
+ */
+
+interface LoadedAgent {
+    name: string;
+    dir: string;
+    source: AgentSource;
+    yaml: ElisymYaml;
+    secrets: Secrets;
+    /** true when at least one secret field was encrypted on disk. */
+    encrypted: boolean;
+    shadowsGlobal: boolean;
+}
+/** Raw resolve + read + parse, no decryption yet. Useful for ergonomic list views. */
+declare function readAgentPublic(resolved: ResolvedAgent): Promise<{
+    resolved: ResolvedAgent;
+    yaml: ElisymYaml;
+}>;
+/**
+ * Load an agent by name. Searches project-local first, then home.
+ * Throws with clear error if missing or if encrypted secrets lack a passphrase.
+ */
+declare function loadAgent(name: string, cwd: string, passphrase?: string): Promise<LoadedAgent>;
+/** Load an agent whose location was already resolved. */
+declare function loadResolvedAgent(resolved: ResolvedAgent, passphrase?: string): Promise<LoadedAgent>;
+
+/**
+ * Write agent files: elisym.yaml, .secrets.json, .gitignore, and create agent dirs.
+ */
+
+interface CreateAgentDirOptions {
+    target: AgentSource;
+    name: string;
+    cwd: string;
+    /**
+     * For `target: 'project'`: if no .elisym/ dir exists above cwd,
+     * where should we create one? Defaults to cwd.
+     */
+    projectRoot?: string;
+}
+interface CreatedAgentDir {
+    dir: string;
+    paths: AgentPaths;
+    source: AgentSource;
+    createdNewElisymRoot: boolean;
+}
+/**
+ * Create (or reuse) the directory layout for a new agent. Idempotent: if the
+ * agent directory already exists, returns its paths without overwriting.
+ * Writes `.gitignore` in project-local .elisym/ on first creation.
+ */
+declare function createAgentDir(options: CreateAgentDirOptions): Promise<CreatedAgentDir>;
+/** Write elisym.yaml atomically. Validates via Zod before writing. */
+declare function writeYaml(agentDir: string, yaml: ElisymYaml): Promise<void>;
+/**
+ * Write .secrets.json atomically. If `passphrase` is given, encrypts all
+ * plaintext secret fields (already-encrypted values are left as-is).
+ */
+declare function writeSecrets(agentDir: string, secrets: Secrets, passphrase?: string): Promise<void>;
+/** Atomic write: temp file + rename. Preserves mode. */
+declare function writeFileAtomic(path: string, data: string | Buffer, mode: number): Promise<void>;
+
+/**
+ * List all agents discoverable from the current working directory:
+ *   - project-local: nearest .elisym/ (walk up to first .git or $HOME)
+ *   - home-global: ~/.elisym/
+ * Project-local entries shadow home-global entries with the same name.
+ */
+
+interface ListedAgent {
+    name: string;
+    source: AgentSource;
+    dir: string;
+    /** display_name from YAML, if present. */
+    displayName?: string;
+    /** true when this entry is project-local and a home-global agent with the same name exists. */
+    shadowsGlobal: boolean;
+}
+/** List agents in both locations, deduping by name (project wins). */
+declare function listAgents(cwd: string): Promise<ListedAgent[]>;
+
+/**
+ * Media cache: maps local image paths to uploaded URLs + sha256.
+ * On each start, the CLI hashes the file and skips re-upload if the hash matches.
+ */
+
+/** Read .media-cache.json. Returns empty object if missing or corrupt. */
+declare function readMediaCache(agentDir: string): Promise<MediaCache>;
+declare function writeMediaCache(agentDir: string, cache: MediaCache): Promise<void>;
+/** Compute sha256 hex of a file's contents. */
+declare function hashFile(filePath: string): Promise<string>;
+/**
+ * Look up a cached URL for a local file path. Returns the cached URL if
+ * the file's current hash matches the cache entry; otherwise null.
+ */
+declare function lookupCachedUrl(cache: MediaCache, relativePath: string, absolutePath: string): Promise<string | null>;
+declare function newCacheEntry(url: string, sha256: string): MediaCacheEntry;
+
+export { AgentNameSchema, type AgentPaths, type AgentSource, type CreateAgentDirOptions, type CreatedAgentDir, ELISYM_DIRNAME, type ElisymYaml, ElisymYamlSchema, GITIGNORE_FILENAME, JOBS_FILENAME, type ListedAgent, type LlmEntry, LlmSchema, type LoadedAgent, MEDIA_CACHE_FILENAME, type MediaCache, type MediaCacheEntry, MediaCacheEntrySchema, MediaCacheSchema, type PaymentEntry, PaymentSchema, type ResolvedAgent, SECRETS_FILENAME, SKILLS_DIRNAME, type Secrets, SecretsSchema, type SecurityFlags, SecurityFlagsSchema, YAML_FILENAME, agentPaths, createAgentDir, elisymRootFor, findProjectElisymDir, hashFile, homeElisymDir, listAgents, loadAgent, loadResolvedAgent, lookupCachedUrl, newCacheEntry, readAgentPublic, readMediaCache, resolveAgent, resolveInHome, resolveInProject, writeFileAtomic, writeMediaCache, writeSecrets, writeYaml };

package/dist/agent-store.d.ts

@@ -0,0 +1,334 @@
+import { z } from 'zod';
+
+/**
+ * Zod schemas for elisym.yaml (public source of truth) and secrets.json (private).
+ * Shared between CLI (provider mode) and MCP (customer mode, future provider mode).
+ */
+
+declare const AgentNameSchema: z.ZodString;
+declare const PaymentSchema: z.ZodObject<{
+    chain: z.ZodLiteral<"solana">;
+    network: z.ZodEnum<["devnet"]>;
+    address: z.ZodString;
+    token: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    chain: "solana";
+    network: "devnet";
+    address: string;
+    token?: string | undefined;
+}, {
+    chain: "solana";
+    network: "devnet";
+    address: string;
+    token?: string | undefined;
+}>;
+declare const LlmSchema: z.ZodObject<{
+    provider: z.ZodEnum<["anthropic", "openai"]>;
+    model: z.ZodString;
+    max_tokens: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    provider: "anthropic" | "openai";
+    model: string;
+    max_tokens: number;
+}, {
+    provider: "anthropic" | "openai";
+    model: string;
+    max_tokens?: number | undefined;
+}>;
+declare const SecurityFlagsSchema: z.ZodObject<{
+    withdrawals_enabled: z.ZodDefault<z.ZodBoolean>;
+    agent_switch_enabled: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    withdrawals_enabled: boolean;
+    agent_switch_enabled: boolean;
+}, {
+    withdrawals_enabled?: boolean | undefined;
+    agent_switch_enabled?: boolean | undefined;
+}>;
+/**
+ * elisym.yaml schema. Public - committed to git.
+ * Agent name NOT stored here - derived from containing folder name.
+ */
+declare const ElisymYamlSchema: z.ZodObject<{
+    /** Human-readable name shown in UI (optional). Falls back to folder name. */
+    display_name: z.ZodOptional<z.ZodString>;
+    description: z.ZodDefault<z.ZodString>;
+    /** Relative path (to this YAML) or absolute URL. */
+    picture: z.ZodOptional<z.ZodString>;
+    /** Relative path (to this YAML) or absolute URL. */
+    banner: z.ZodOptional<z.ZodString>;
+    relays: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    payments: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        chain: z.ZodLiteral<"solana">;
+        network: z.ZodEnum<["devnet"]>;
+        address: z.ZodString;
+        token: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        chain: "solana";
+        network: "devnet";
+        address: string;
+        token?: string | undefined;
+    }, {
+        chain: "solana";
+        network: "devnet";
+        address: string;
+        token?: string | undefined;
+    }>, "many">>;
+    llm: z.ZodOptional<z.ZodObject<{
+        provider: z.ZodEnum<["anthropic", "openai"]>;
+        model: z.ZodString;
+        max_tokens: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        provider: "anthropic" | "openai";
+        model: string;
+        max_tokens: number;
+    }, {
+        provider: "anthropic" | "openai";
+        model: string;
+        max_tokens?: number | undefined;
+    }>>;
+    security: z.ZodDefault<z.ZodObject<{
+        withdrawals_enabled: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+        agent_switch_enabled: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+    }, "strip", z.ZodTypeAny, {
+        withdrawals_enabled?: boolean | undefined;
+        agent_switch_enabled?: boolean | undefined;
+    }, {
+        withdrawals_enabled?: boolean | undefined;
+        agent_switch_enabled?: boolean | undefined;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    description: string;
+    relays: string[];
+    payments: {
+        chain: "solana";
+        network: "devnet";
+        address: string;
+        token?: string | undefined;
+    }[];
+    security: {
+        withdrawals_enabled?: boolean | undefined;
+        agent_switch_enabled?: boolean | undefined;
+    };
+    display_name?: string | undefined;
+    picture?: string | undefined;
+    banner?: string | undefined;
+    llm?: {
+        provider: "anthropic" | "openai";
+        model: string;
+        max_tokens: number;
+    } | undefined;
+}, {
+    display_name?: string | undefined;
+    description?: string | undefined;
+    picture?: string | undefined;
+    banner?: string | undefined;
+    relays?: string[] | undefined;
+    payments?: {
+        chain: "solana";
+        network: "devnet";
+        address: string;
+        token?: string | undefined;
+    }[] | undefined;
+    llm?: {
+        provider: "anthropic" | "openai";
+        model: string;
+        max_tokens?: number | undefined;
+    } | undefined;
+    security?: {
+        withdrawals_enabled?: boolean | undefined;
+        agent_switch_enabled?: boolean | undefined;
+    } | undefined;
+}>;
+type ElisymYaml = z.infer<typeof ElisymYamlSchema>;
+type PaymentEntry = z.infer<typeof PaymentSchema>;
+type LlmEntry = z.infer<typeof LlmSchema>;
+type SecurityFlags = z.infer<typeof SecurityFlagsSchema>;
+/**
+ * secrets.json schema. Private - .gitignore.
+ * Values may be plaintext or `encrypted:v1:...` blobs (AES-256-GCM + scrypt).
+ */
+declare const SecretsSchema: z.ZodObject<{
+    nostr_secret_key: z.ZodString;
+    solana_secret_key: z.ZodOptional<z.ZodString>;
+    llm_api_key: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    nostr_secret_key: string;
+    solana_secret_key?: string | undefined;
+    llm_api_key?: string | undefined;
+}, {
+    nostr_secret_key: string;
+    solana_secret_key?: string | undefined;
+    llm_api_key?: string | undefined;
+}>;
+type Secrets = z.infer<typeof SecretsSchema>;
+interface MediaCacheEntry {
+    url: string;
+    sha256: string;
+    uploaded_at: string;
+}
+declare const MediaCacheEntrySchema: z.ZodType<MediaCacheEntry>;
+declare const MediaCacheSchema: z.ZodRecord<z.ZodString, z.ZodType<MediaCacheEntry, z.ZodTypeDef, MediaCacheEntry>>;
+type MediaCache = z.infer<typeof MediaCacheSchema>;
+
+/**
+ * Path helpers for .elisym/ layout.
+ *
+ * Project-local (walk up from CWD until .git or $HOME):
+ *   <project>/.elisym/<name>/{elisym.yaml, .secrets.json, .media-cache.json, .jobs.json, .gitignore}
+ *
+ * Home-global (~/.elisym/<name>/): same file structure.
+ *
+ * Node.js only - relies on `node:fs`/`node:os`/`node:path`.
+ */
+declare const ELISYM_DIRNAME = ".elisym";
+declare const YAML_FILENAME = "elisym.yaml";
+declare const SECRETS_FILENAME = ".secrets.json";
+declare const MEDIA_CACHE_FILENAME = ".media-cache.json";
+declare const JOBS_FILENAME = ".jobs.json";
+declare const GITIGNORE_FILENAME = ".gitignore";
+declare const SKILLS_DIRNAME = "skills";
+/** ~/.elisym/ */
+declare function homeElisymDir(): string;
+/**
+ * Walk up from `startDir` looking for `.elisym/` directory.
+ * Stops at (a) the first `.git` directory/file, (b) `$HOME`, (c) filesystem root,
+ * or (d) MAX_WALK_UP_DEPTH iterations. Returns absolute path or null.
+ */
+declare function findProjectElisymDir(startDir: string): string | null;
+interface AgentPaths {
+    dir: string;
+    yaml: string;
+    secrets: string;
+    mediaCache: string;
+    jobs: string;
+    gitignore: string;
+    skills: string;
+}
+/** Compute all file/dir paths for an agent given its root directory. */
+declare function agentPaths(agentDir: string): AgentPaths;
+
+/**
+ * Agent resolution: find <name>/elisym.yaml via project-local walk-up, fallback to home.
+ */
+
+type AgentSource = 'project' | 'home';
+interface ResolvedAgent {
+    name: string;
+    dir: string;
+    source: AgentSource;
+    /** true when both a project-local and a home-global agent exist with the same name. */
+    shadowsGlobal: boolean;
+}
+/**
+ * Resolve an agent by name. Precedence: project-local beats home-global.
+ * Returns null if not found in either location.
+ */
+declare function resolveAgent(name: string, cwd: string): ResolvedAgent | null;
+/** Return project-local agent dir if its YAML exists, else null. */
+declare function resolveInProject(name: string, cwd: string): string | null;
+/** Return home-global agent dir if its YAML exists, else null. */
+declare function resolveInHome(name: string): string | null;
+/** Path to the .elisym root (project or home) for a given target. */
+declare function elisymRootFor(target: AgentSource, cwd: string): string | null;
+
+/**
+ * Load an agent: parse elisym.yaml + .secrets.json, decrypt if encrypted.
+ */
+
+interface LoadedAgent {
+    name: string;
+    dir: string;
+    source: AgentSource;
+    yaml: ElisymYaml;
+    secrets: Secrets;
+    /** true when at least one secret field was encrypted on disk. */
+    encrypted: boolean;
+    shadowsGlobal: boolean;
+}
+/** Raw resolve + read + parse, no decryption yet. Useful for ergonomic list views. */
+declare function readAgentPublic(resolved: ResolvedAgent): Promise<{
+    resolved: ResolvedAgent;
+    yaml: ElisymYaml;
+}>;
+/**
+ * Load an agent by name. Searches project-local first, then home.
+ * Throws with clear error if missing or if encrypted secrets lack a passphrase.
+ */
+declare function loadAgent(name: string, cwd: string, passphrase?: string): Promise<LoadedAgent>;
+/** Load an agent whose location was already resolved. */
+declare function loadResolvedAgent(resolved: ResolvedAgent, passphrase?: string): Promise<LoadedAgent>;
+
+/**
+ * Write agent files: elisym.yaml, .secrets.json, .gitignore, and create agent dirs.
+ */
+
+interface CreateAgentDirOptions {
+    target: AgentSource;
+    name: string;
+    cwd: string;
+    /**
+     * For `target: 'project'`: if no .elisym/ dir exists above cwd,
+     * where should we create one? Defaults to cwd.
+     */
+    projectRoot?: string;
+}
+interface CreatedAgentDir {
+    dir: string;
+    paths: AgentPaths;
+    source: AgentSource;
+    createdNewElisymRoot: boolean;
+}
+/**
+ * Create (or reuse) the directory layout for a new agent. Idempotent: if the
+ * agent directory already exists, returns its paths without overwriting.
+ * Writes `.gitignore` in project-local .elisym/ on first creation.
+ */
+declare function createAgentDir(options: CreateAgentDirOptions): Promise<CreatedAgentDir>;
+/** Write elisym.yaml atomically. Validates via Zod before writing. */
+declare function writeYaml(agentDir: string, yaml: ElisymYaml): Promise<void>;
+/**
+ * Write .secrets.json atomically. If `passphrase` is given, encrypts all
+ * plaintext secret fields (already-encrypted values are left as-is).
+ */
+declare function writeSecrets(agentDir: string, secrets: Secrets, passphrase?: string): Promise<void>;
+/** Atomic write: temp file + rename. Preserves mode. */
+declare function writeFileAtomic(path: string, data: string | Buffer, mode: number): Promise<void>;
+
+/**
+ * List all agents discoverable from the current working directory:
+ *   - project-local: nearest .elisym/ (walk up to first .git or $HOME)
+ *   - home-global: ~/.elisym/
+ * Project-local entries shadow home-global entries with the same name.
+ */
+
+interface ListedAgent {
+    name: string;
+    source: AgentSource;
+    dir: string;
+    /** display_name from YAML, if present. */
+    displayName?: string;
+    /** true when this entry is project-local and a home-global agent with the same name exists. */
+    shadowsGlobal: boolean;
+}
+/** List agents in both locations, deduping by name (project wins). */
+declare function listAgents(cwd: string): Promise<ListedAgent[]>;
+
+/**
+ * Media cache: maps local image paths to uploaded URLs + sha256.
+ * On each start, the CLI hashes the file and skips re-upload if the hash matches.
+ */
+
+/** Read .media-cache.json. Returns empty object if missing or corrupt. */
+declare function readMediaCache(agentDir: string): Promise<MediaCache>;
+declare function writeMediaCache(agentDir: string, cache: MediaCache): Promise<void>;
+/** Compute sha256 hex of a file's contents. */
+declare function hashFile(filePath: string): Promise<string>;
+/**
+ * Look up a cached URL for a local file path. Returns the cached URL if
+ * the file's current hash matches the cache entry; otherwise null.
+ */
+declare function lookupCachedUrl(cache: MediaCache, relativePath: string, absolutePath: string): Promise<string | null>;
+declare function newCacheEntry(url: string, sha256: string): MediaCacheEntry;
+
+export { AgentNameSchema, type AgentPaths, type AgentSource, type CreateAgentDirOptions, type CreatedAgentDir, ELISYM_DIRNAME, type ElisymYaml, ElisymYamlSchema, GITIGNORE_FILENAME, JOBS_FILENAME, type ListedAgent, type LlmEntry, LlmSchema, type LoadedAgent, MEDIA_CACHE_FILENAME, type MediaCache, type MediaCacheEntry, MediaCacheEntrySchema, MediaCacheSchema, type PaymentEntry, PaymentSchema, type ResolvedAgent, SECRETS_FILENAME, SKILLS_DIRNAME, type Secrets, SecretsSchema, type SecurityFlags, SecurityFlagsSchema, YAML_FILENAME, agentPaths, createAgentDir, elisymRootFor, findProjectElisymDir, hashFile, homeElisymDir, listAgents, loadAgent, loadResolvedAgent, lookupCachedUrl, newCacheEntry, readAgentPublic, readMediaCache, resolveAgent, resolveInHome, resolveInProject, writeFileAtomic, writeMediaCache, writeSecrets, writeYaml };