helixor-agent-sdk 0.4.33__tar.gz

helixor_agent_sdk-0.4.33/PKG-INFO

@@ -0,0 +1,25 @@
+Metadata-Version: 2.4
+Name: helixor-agent-sdk
+Version: 0.4.33
+Summary: Public Helixor agent authoring, client SDK, CLI and Pi bridge.
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+
+# Helixor agent SDK
+
+Public authoring, CLI commands, generated clients, templates and Pi bridge.
+The `helixor` CLI depends on this package. It contains no agent service,
+pricing/usage engine, draft store or authoring assistant prompts.
+
+`helixor agent check` validates local structure. Deployment admission on the
+selected service validates prices, budgets and policy rules before execution.
+Python callers can request structural checks with `load_agent(path,
+check_prices=False)`; the default price admission requires the private runtime.
+
+A shared deployment is cloud hosted (development or production) and uses its
+team/tenant authorization. A local deployment is the user's personal sandbox.
+Select the authorized cloud service with `--to`; local execution requires the
+matching private runtime and never grants cloud permissions.

helixor_agent_sdk-0.4.33/README.md

@@ -0,0 +1,15 @@
+# Helixor agent SDK
+
+Public authoring, CLI commands, generated clients, templates and Pi bridge.
+The `helixor` CLI depends on this package. It contains no agent service,
+pricing/usage engine, draft store or authoring assistant prompts.
+
+`helixor agent check` validates local structure. Deployment admission on the
+selected service validates prices, budgets and policy rules before execution.
+Python callers can request structural checks with `load_agent(path,
+check_prices=False)`; the default price admission requires the private runtime.
+
+A shared deployment is cloud hosted (development or production) and uses its
+team/tenant authorization. A local deployment is the user's personal sandbox.
+Select the authorized cloud service with `--to`; local execution requires the
+matching private runtime and never grants cloud permissions.

helixor_agent_sdk-0.4.33/pyproject.toml

@@ -0,0 +1,17 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "helixor-agent-sdk"
+version = "0.4.33"
+description = "Public Helixor agent authoring, client SDK, CLI and Pi bridge."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = ["httpx>=0.27", "pydantic>=2.0", "pyyaml>=6.0"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+helixor_agent = ["bridge/*.mjs", "templates/*/agent.yaml", "templates/*/tools.py", "templates/*/skills/*/SKILL.md"]

helixor_agent_sdk-0.4.33/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

helixor_agent_sdk-0.4.33/src/helixor_agent/__init__.py

@@ -0,0 +1,16 @@
+"""Helixor agents: a folder of instructions, skills and tools, run on Pi.
+
+    from helixor_agent import tool      # mark a function in tools.py
+    from helixor_agent import Agent     # call a deployed agent
+    from helixor_agent import state_dir # files a tool keeps between calls (runtime: {state: ...})
+"""
+
+from pkgutil import extend_path
+
+__path__ = extend_path(__path__, __name__)
+
+from helixor_agent.client import Agent, AgentCallError, AgentReply
+from helixor_agent.tool import tool
+from helixor_agent.tool_state import state_dir
+
+__all__ = ["Agent", "AgentCallError", "AgentReply", "state_dir", "tool"]

helixor_agent_sdk-0.4.33/src/helixor_agent/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from helixor_agent.cli import main
+
+sys.exit(main())

helixor_agent_sdk-0.4.33/src/helixor_agent/bridge/agent-bridge.mjs

@@ -0,0 +1,395 @@
+// Helixor agent bridge: runs one Pi agent session for one conversation.
+//
+// Protocol: JSON lines. stdin carries requests from the Python side, stdout
+// carries replies. Nothing else may write to stdout, so console output goes to
+// stderr.
+//
+//   -> {"type":"init","agent":{...},"model_api_key":"...","session_file":"..."|null,"session_dir":"...",
+//       "local_model":{"base_url":"http://127.0.0.1:8860/v1","context_window":32768,"max_tokens":4096}|null}
+//   <- {"type":"ready","session_file":"...","skills":[...],"diagnostics":[...]}
+//   -> {"type":"message","text":"..."}
+//   <- {"type":"tool_call","id":"...","name":"...","args":{...}}
+//   -> {"type":"tool_result","id":"...","ok":true,"result":...} | {"ok":false,"error":"..."}
+//   <- {"type":"tool_rejected","name":"...","args":{...},"error":"..."}   (never reached Python: bad arguments
+//                                                                         or a blocked tool; the model sees the error)
+//   <- {"type":"model_call_request","id":"m1","provider":"...","model":"...","prompt_chars":N,
+//       "max_tokens":N}                    (before EVERY model call; nothing is sent until
+//   -> {"type":"model_call_decision","id":"m1","ok":true} | {"ok":false,"code":"...","detail":"..."}   Python answers)
+//   <- {"type":"model_call","id":"m1","provider","model","latency_ms","max_tokens","stop_reason","error",
+//       "usage":{"input","output","cache_read","cache_write","total"},"raw_usage":{...provider fields...},"pi_cost_usd"}
+//   <- {"type":"reply","text":"...","tool_calls":[{"tool","args","ok"}],"skills_used":["..."],
+//       "usage":{"input","output","cache_read","cache_write","total","model_calls"}}
+//   <- {"type":"stopped","code":"...","detail":"...","tool_calls":[...],"usage":{...}}   (a model call was refused:
+//                                                                         the turn ends, the model was not called)
+//   <- {"type":"error","code":"...","detail":"..."}
+//
+// Metering: every model call goes through meteredStream, which asks Python first (budgets, the usage ledger)
+// and reports the call's tokens, latency and the provider's own usage fields after it. Pi's cost figure is
+// passed along as a cross-check only; Python prices calls from its own versioned table.
+//
+// Pi's built-in tools are off except `read`, and `read` may open files only
+// under the agent's skills folder: that is how Pi loads a skill when a task
+// matches its description. The agent's own tools run on the Python side; the
+// bridge only forwards calls and results, so a tool can never be faked here.
+//
+// A `local` provider is an OpenAI-compatible chat completions server on loopback (model:
+// local/<name> in agent.yaml). It is registered here as a custom Pi provider with the
+// openai-completions API; its placeholder key never leaves loopback.
+
+import { createInterface } from 'node:readline'
+import { resolve, sep } from 'node:path'
+import { mkdirSync } from 'node:fs'
+
+import {
+  createAgentSession,
+  DefaultResourceLoader,
+  ModelRuntime,
+  SessionManager,
+  SettingsManager,
+} from '@earendil-works/pi-coding-agent'
+import { getModel } from '@earendil-works/pi-ai/compat'
+
+console.log = (...args) => console.error(...args)
+console.info = (...args) => console.error(...args)
+
+function emit(obj) {
+  process.stdout.write(JSON.stringify(obj) + '\n')
+}
+
+function fail(code, detail) {
+  emit({ type: 'error', code, detail: String(detail ?? '') })
+}
+
+let session = null
+let pending = new Map()
+let callSeq = 0
+let turnCalls = null
+let turnSkills = null
+let busy = false
+let forwarded = new Set()
+let started = new Map()
+let modelSeq = 0
+let decisions = new Map()
+let stopped = null
+let providerUsage = null
+let maxOutputTokens = null
+const LOOPBACK = new Set(['127.0.0.1', '::1', '[::1]', 'localhost'])
+
+function isLoopback(url) {
+  try {
+    const u = new URL(url)
+    return (u.protocol === 'http:' || u.protocol === 'https:') && !u.username && !u.password &&
+      (LOOPBACK.has(u.hostname) || /^127\.\d+\.\d+\.\d+$/.test(u.hostname))
+  } catch {
+    return false
+  }
+}
+
+// The Pi model for `local/<name>`: openai-completions against the loopback server, tools on,
+// thinking requested off per call through the chat template (enable_thinking), no key needed.
+function localModelConfig(name, local, apiKey) {
+  return {
+    name: 'Local open-weight model (loopback)',
+    baseUrl: local.base_url,
+    apiKey,
+    api: 'openai-completions',
+    models: [
+      {
+        id: name,
+        name: `local/${name}`,
+        api: 'openai-completions',
+        reasoning: true,
+        input: ['text'],
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+        contextWindow: local.context_window,
+        maxTokens: local.max_tokens,
+        compat: {
+          supportsStore: false,
+          supportsDeveloperRole: false,
+          supportsReasoningEffort: false,
+          supportsUsageInStreaming: true,
+          maxTokensField: 'max_tokens',
+          thinkingFormat: 'chat-template',
+          chatTemplateKwargs: { enable_thinking: { $var: 'thinking.enabled' } },
+        },
+      },
+    ],
+  }
+}
+
+function skillsGuard(skillsDir, allowed) {
+  const root = skillsDir ? resolve(skillsDir) + sep : null
+  return (pi) => {
+    pi.on('provider_stream_event', async (event) => {
+      // The provider's own usage fields, as it reported them (Anthropic message_start / message_delta, OpenAI chunks).
+      const data = event.data ?? {}
+      const usage = data.usage ?? data.message?.usage
+      if (providerUsage && usage && typeof usage === 'object') Object.assign(providerUsage, usage)
+    })
+    pi.on('tool_call', async (event) => {
+      if (!allowed.has(event.toolName)) {
+        return { block: true, reason: `TOOL_NOT_ALLOWED: ${event.toolName} is not one of this agent's tools` }
+      }
+      if (event.toolName === 'read') {
+        const target = resolve(skillsDir || '/', String(event.input?.path ?? ''))
+        if (!root || !(target + sep).startsWith(root)) {
+          return { block: true, reason: 'READ_OUTSIDE_SKILLS: read may only open this agent\'s skill files' }
+        }
+        const skill = target.slice(root.length).split(sep)[0]
+        if (skill && !turnSkills?.includes(skill)) turnSkills?.push(skill)
+      }
+      return undefined
+    })
+  }
+}
+
+function agentTool(def) {
+  return {
+    name: def.name,
+    label: def.name,
+    description: def.description,
+    parameters: def.parameters,
+    execute: async (toolCallId, params) => {
+      forwarded.add(toolCallId)
+      const id = `c${++callSeq}`
+      const result = await new Promise((resolveCall) => {
+        pending.set(id, resolveCall)
+        emit({ type: 'tool_call', id, name: def.name, args: params ?? {} })
+      })
+      turnCalls?.push({ tool: def.name, args: params ?? {}, ok: !!result.ok, ...(result.ok ? {} : { error: result.error }) })
+      const body = result.ok ? result.result : { error: true, detail: result.error }
+      return {
+        content: [{ type: 'text', text: JSON.stringify(body) }],
+        details: body,
+        ...(result.ok ? {} : { isError: true }),
+      }
+    },
+  }
+}
+
+async function init(req) {
+  const agent = req.agent
+  if (!req.model_api_key) return fail('AGENT_MODEL_KEY_MISSING', `no API key for ${agent.provider}`)
+
+  const stateDir = req.state_dir
+  mkdirSync(stateDir, { recursive: true })
+  const modelRuntime = await ModelRuntime.create({
+    authPath: `${stateDir}/auth.json`,
+    modelsPath: `${stateDir}/models.json`,
+  })
+  let model
+  if (agent.provider === 'local') {
+    const local = req.local_model
+    if (!local?.base_url) return fail('LOCAL_MODEL_UNAVAILABLE', 'no endpoint for the local model')
+    if (!isLoopback(local.base_url)) return fail('LOCAL_MODEL_URL_NOT_LOOPBACK', local.base_url)
+    modelRuntime.registerProvider('local', localModelConfig(agent.model, local, req.model_api_key))
+    model = modelRuntime.getModel('local', agent.model)
+    if (!model) return fail('AGENT_MODEL_UNKNOWN', `local/${agent.model} could not be registered`)
+  } else {
+    model = getModel(agent.provider, agent.model)
+    if (!model) return fail('AGENT_MODEL_UNKNOWN', `${agent.provider}/${agent.model} is not a model this runtime knows`)
+    await modelRuntime.setRuntimeApiKey(agent.provider, req.model_api_key)
+  }
+
+  const settingsManager = SettingsManager.inMemory({
+    compaction: { enabled: true },
+    retry: { enabled: true, maxRetries: 1 },
+    enableInstallTelemetry: false,
+    enableAnalytics: false,
+  })
+
+  const toolNames = agent.tools.map((t) => t.name)
+  const hasSkills = (agent.skill_dirs ?? []).length > 0
+  const allowed = new Set([...toolNames, ...(hasSkills ? ['read'] : [])])
+
+  const resourceLoader = new DefaultResourceLoader({
+    cwd: agent.root,
+    agentDir: stateDir,
+    settingsManager,
+    noExtensions: true,
+    noSkills: true,
+    additionalSkillPaths: agent.skill_dirs ?? [],
+    noPromptTemplates: true,
+    noThemes: true,
+    noContextFiles: true,
+    systemPrompt: agent.instructions,
+    extensionFactories: [skillsGuard(agent.skills_root, allowed)],
+  })
+  await resourceLoader.reload()
+  const loaded = resourceLoader.getSkills()
+
+  let sessionManager
+  if (req.session_file) sessionManager = SessionManager.open(req.session_file, req.session_dir, agent.root)
+  else if (req.session_dir) sessionManager = SessionManager.create(agent.root, req.session_dir)
+  else sessionManager = SessionManager.inMemory(agent.root)
+
+  const created = await createAgentSession({
+    cwd: agent.root,
+    agentDir: stateDir,
+    model,
+    thinkingLevel: 'off',
+    modelRuntime,
+    resourceLoader,
+    settingsManager,
+    sessionManager,
+    tools: [...allowed],
+    customTools: agent.tools.map(agentTool),
+  })
+  session = created.session
+  maxOutputTokens = agent.max_output_tokens ?? null
+  session.agent.streamFunction = meteredStream(session.agent.streamFunction)
+  const ownTools = new Set(toolNames)
+  session.subscribe((event) => {
+    if (event.type === 'tool_execution_start') started.set(event.toolCallId, event.args)
+    if (event.type !== 'tool_execution_end') return
+    const args = started.get(event.toolCallId)
+    started.delete(event.toolCallId)
+    if (forwarded.delete(event.toolCallId) || !event.isError || !ownTools.has(event.toolName)) return
+    // Rejected before it reached Python (arguments that fail the tool's schema, or a blocked call):
+    // the model got the error as the tool result; Python records it.
+    const text = (event.result?.content ?? []).map((c) => c?.text ?? '').join(' ').trim()
+    turnCalls?.push({ tool: event.toolName, args: args ?? {}, ok: false, error: text })
+    emit({ type: 'tool_rejected', name: event.toolName, args: args ?? {}, error: text || 'rejected' })
+  })
+  emit({
+    type: 'ready',
+    session_file: session.sessionFile ?? null,
+    skills: (loaded.skills ?? []).map((s) => s.name),
+    diagnostics: (loaded.diagnostics ?? []).map((d) => d.message ?? String(d)),
+  })
+}
+
+function ask(request) {
+  return new Promise((resolveAsk) => {
+    decisions.set(request.id, resolveAsk)
+    emit(request)
+  })
+}
+
+function promptChars(context) {
+  try {
+    return JSON.stringify({ s: context?.systemPrompt ?? '', m: context?.messages ?? [], t: context?.tools ?? [] }).length
+  } catch {
+    return 0
+  }
+}
+
+// Every model call: ask Python first; on a refusal the model is NOT called (the turn ends with "stopped").
+function meteredStream(original) {
+  return async (model, context, options) => {
+    const id = `m${++modelSeq}`
+    const maxTokens = maxOutputTokens ?? options?.maxTokens ?? model.maxTokens
+    const chars = promptChars(context)
+    const decision = await ask({
+      type: 'model_call_request', id, provider: model.provider, model: model.id,
+      prompt_chars: chars, max_tokens: maxTokens,
+    })
+    if (!decision.ok) {
+      stopped = stopped ?? { code: decision.code || 'AGENT_BUDGET_EXCEEDED', detail: decision.detail || '' }
+      throw new Error(`${stopped.code}: ${stopped.detail}`)
+    }
+    const raw = {}
+    providerUsage = raw
+    const t0 = Date.now()
+    const response = await original(model, context, { ...options, maxTokens })
+    response.result().then((m) => {
+      const u = m?.usage ?? {}
+      emit({
+        type: 'model_call', id, provider: model.provider, model: model.id, latency_ms: Date.now() - t0,
+        max_tokens: maxTokens, prompt_chars: chars, stop_reason: m?.stopReason ?? null,
+        error: m?.errorMessage ?? null,
+        usage: { input: u.input ?? 0, output: u.output ?? 0, cache_read: u.cacheRead ?? 0, cache_write: u.cacheWrite ?? 0,
+                 total: u.totalTokens ?? 0 },
+        raw_usage: raw, pi_cost_usd: u.cost?.total ?? null,
+      })
+    }, (e) => {
+      emit({ type: 'model_call', id, provider: model.provider, model: model.id, latency_ms: Date.now() - t0,
+             max_tokens: maxTokens, error: String(e?.message ?? e), usage: {}, raw_usage: raw })
+    })
+    return response
+  }
+}
+
+function lastAssistant() {
+  const messages = session.messages ?? []
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (messages[i]?.role === 'assistant') return messages[i]
+  }
+  return null
+}
+
+function turnUsage(from) {
+  const out = { input: 0, output: 0, cache_read: 0, cache_write: 0, total: 0, model_calls: 0 }
+  for (const m of (session.messages ?? []).slice(from)) {
+    if (m?.role !== 'assistant' || !m.usage) continue
+    out.model_calls += 1
+    out.input += m.usage.input ?? 0
+    out.output += m.usage.output ?? 0
+    out.cache_read += m.usage.cacheRead ?? 0
+    out.cache_write += m.usage.cacheWrite ?? 0
+    out.total += m.usage.totalTokens ?? 0
+  }
+  return out
+}
+
+async function message(req) {
+  if (!session) return fail('AGENT_NOT_READY', 'init first')
+  if (busy) return fail('AGENT_BUSY', 'one message at a time per conversation')
+  busy = true
+  turnCalls = []
+  turnSkills = []
+  stopped = null
+  const before = (session.messages ?? []).length
+  try {
+    await session.prompt(String(req.text ?? ''))
+    if (stopped) {
+      return emit({ type: 'stopped', ...stopped, tool_calls: turnCalls, skills_used: turnSkills, usage: turnUsage(before) })
+    }
+    const last = lastAssistant()
+    if (last?.stopReason === 'error' || last?.errorMessage) {
+      return fail('AGENT_MODEL_ERROR', last.errorMessage || 'the model call failed')
+    }
+    const text = session.getLastAssistantText() ?? ''
+    if (!text.trim()) return fail('AGENT_EMPTY_REPLY', 'the model returned no text')
+    emit({ type: 'reply', text, tool_calls: turnCalls, skills_used: turnSkills, usage: turnUsage(before) })
+  } catch (error) {
+    if (stopped) emit({ type: 'stopped', ...stopped, tool_calls: turnCalls, skills_used: turnSkills, usage: turnUsage(before) })
+    else fail('AGENT_TURN_FAILED', error?.message ?? error)
+  } finally {
+    stopped = null
+    busy = false
+    turnCalls = null
+    turnSkills = null
+  }
+}
+
+const rl = createInterface({ input: process.stdin })
+rl.on('line', (line) => {
+  if (!line.trim()) return
+  let req
+  try {
+    req = JSON.parse(line)
+  } catch {
+    return fail('BRIDGE_BAD_JSON', line.slice(0, 200))
+  }
+  if (req.type === 'model_call_decision') {
+    const done = decisions.get(req.id)
+    if (done) {
+      decisions.delete(req.id)
+      done(req)
+    }
+    return
+  }
+  if (req.type === 'tool_result') {
+    const done = pending.get(req.id)
+    if (done) {
+      pending.delete(req.id)
+      done(req)
+    }
+    return
+  }
+  if (req.type === 'init') return void init(req).catch((e) => fail('AGENT_INIT_FAILED', e?.message ?? e))
+  if (req.type === 'message') return void message(req)
+  fail('BRIDGE_UNKNOWN_REQUEST', req.type)
+})
+rl.on('close', () => process.exit(0))

helixor_agent_sdk-0.4.33/src/helixor_agent/bundles.py

@@ -0,0 +1,66 @@
+"""Deterministic application bundles shared by clients and services."""
+
+from __future__ import annotations
+
+import hashlib
+import io
+import tarfile
+from pathlib import Path
+
+_BUNDLE_SKIP = {"__pycache__", ".git", ".helixor", ".venv", "node_modules"}
+
+def _shipped(root: Path) -> list[Path]:
+    out = []
+    for path in sorted(root.rglob("*")):
+        rel = path.relative_to(root)
+        if any(part in _BUNDLE_SKIP or part.startswith(".") for part in rel.parts):
+            continue
+        if path.is_file():
+            out.append(path)
+    return out
+
+
+def pack_folder(root: Path) -> bytes:
+    """The folder as a gzip tarball, without caches, VCS data or local keys.
+
+    Deterministic: the same files give the same bytes (no timestamps, owners or umask in the archive; a file is
+    0644, or 0755 when executable), so a downloaded draft deployed from the CLI is byte-for-byte the bundle the
+    browser would deploy.
+    """
+    return pack_files(_shipped(root), root)
+
+
+def bundle_sha256(data: bytes) -> str:
+    """The hash of a packed bundle (what ``pack_folder`` returns)."""
+    return hashlib.sha256(data).hexdigest()
+
+
+def pack_files(paths: list[Path], root: Path) -> bytes:
+    """Some of a folder's files as a gzip tarball, the same way ``pack_folder`` packs them."""
+    import gzip
+
+    buf = io.BytesIO()
+    with gzip.GzipFile(filename="", fileobj=buf, mode="wb", mtime=0) as gz, \
+            tarfile.open(fileobj=gz, mode="w", format=tarfile.GNU_FORMAT) as tar:
+        for path in sorted(paths):
+            data = path.read_bytes()
+            info = tarfile.TarInfo(path.relative_to(root).as_posix())
+            info.size = len(data)
+            info.mode = 0o755 if path.stat().st_mode & 0o111 else 0o644
+            info.mtime, info.uid, info.gid, info.uname, info.gname = 0, 0, 0, "", ""
+            tar.addfile(info, io.BytesIO(data))
+    return buf.getvalue()
+
+
+def unpack_bundle(data: bytes, dest: Path) -> None:
+    dest.mkdir(parents=True, exist_ok=False)
+    with tarfile.open(fileobj=io.BytesIO(data), mode="r:gz") as tar:
+        tar.extractall(dest, filter="data")
+
+
+def folder_digest(root: Path) -> str:
+    """Changes exactly when a shipped file's path or content changes."""
+    digest = hashlib.sha256()
+    for path in _shipped(root):
+        digest.update(str(path.relative_to(root)).encode() + b"\0" + hashlib.sha256(path.read_bytes()).digest())
+    return digest.hexdigest()[:20]