Fix/pr ready

[SuleymanEmirGergin]

Summary by cubic

Ships Hackathon Autopilot and a reliability-focused AgentKit update. Adds a unified transaction builder, structured error handling, safer mainnet guards, improved bridge/staking/trustline tools, plus CI, docs, and tests.

• New Features

  • Hackathon Autopilot skill with 15 modules, templates, and multi-agent orchestration.
  • AgentKitError with stable codes and a friendly error formatter.
  • Unified buildTransaction utility used across contracts, bridge, and stake.
  • New tools: staking, trustline ensure, account balance, token issuance (launchToken) with mainnet safeguards.
  • GitHub Actions CI (build, test, docs) and generated API docs; README/SECURITY updates.

• Migration

  • Set env flags ALLOW_MAINNET_TOKEN_ISSUANCE and ALLOW_MAINNET_BRIDGE if you need mainnet.
  • Update callers to handle AgentKitError by code (e.g., INVALID_ADDRESS, MISSING_TRUSTLINE).
  • AgentConfig adds allowMainnetTokenIssuance; ensure STELLAR_PUBLIC_KEY/PRIVATE_KEY are set.

^{Written for commit 23d17c5. Summary will update on new commits.}

[cubic-dev-ai]

13 issues found across 137 files

Note: This PR contains a large number of files. cubic only reviews up to 75 files per PR, so some files may not have been reviewed.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name=".env.example">

<violation number="1" location=".env.example:23">
P2: Duplicate SRB_PROVIDER_URL in .env.example creates ambiguous network selection and can override a user’s intended mainnet setting.</violation>
</file>

<file name=".agent/skills/hackathon-autopilot/templates/output_figma_flow.md">

<violation number="1" location=".agent/skills/hackathon-autopilot/templates/output_figma_flow.md:33">
P3: Angle-bracket placeholder is parsed as HTML in Markdown and can be hidden in rendered views, making the required prompt insertion unclear.</violation>
</file>

<file name="docs/NEXT_STEPS.md">

<violation number="1" location="docs/NEXT_STEPS.md:14">
P2: Documentation marks CI as completed and references `.github/workflows/ci.yml`, but that workflow file is not present in the repository. This makes the release-readiness checklist inaccurate.</violation>
</file>

<file name="docs/api-reference/index.html">

<violation number="1" location="docs/api-reference/index.html:119">
P2: Broken documentation link: href points to media/api.md, but no such file exists in the repo/output, so users will hit a 404 from the API reference page.</violation>
</file>

<file name="tools/account.ts">

<violation number="1" location="tools/account.ts:30">
P2: Non-native balance mapping assumes asset_code/asset_issuer are always present; Horizon balances can include liquidity_pool_shares with no asset_code/issuer, leading to `undefined:undefined` outputs and incorrect balance data.</violation>
</file>

<file name="README.md">

<violation number="1" location="README.md:147">
P2: Security docs overstate protections by claiming env-level safeguards for all mainnet fund operations, but swap/LP only require `allowMainnet` in code.</violation>
</file>

<file name="lib/tokenIssuance.ts">

<violation number="1" location="lib/tokenIssuance.ts:78">
P2: initialSupply validation uses parseFloat, which accepts malformed numeric strings. Combined with normalizeAmount returning the raw string for decimals===7, invalid Stellar amount strings can pass validation and fail later at submission or be silently altered. Use the SDK’s amount validation to ensure a canonical decimal string.</violation>

<violation number="2" location="lib/tokenIssuance.ts:166">
P2: Minting is always executed without an idempotency check, so retries can mint multiple times; the status is derived only from trustline creation and can report `idempotent_skip` even when a payment was submitted.</violation>
</file>

<file name="docs/api-reference/modules/index.html">

<violation number="1" location="docs/api-reference/modules/index.html:1">
P2: Unguarded `app` reference in the timeout can throw `ReferenceError` before the fallback runs, leaving `display:none` in place if `main.js` hasn't loaded yet.</violation>
</file>

<file name="tools/stellar.ts">

<violation number="1" location="tools/stellar.ts:8">
P2: Tool description now implies generic Stellar network support, but implementation is still testnet-only, which misleads callers about where funds are sent.</violation>
</file>

<file name=".github/workflows/ci.yml">

<violation number="1" location=".github/workflows/ci.yml:13">
P2: GitHub Actions are referenced by mutable tags (@v4). Tags can be retargeted, so this workflow is exposed to supply‑chain changes. Pin actions to full commit SHAs for immutability and CI integrity.</violation>
</file>

<file name="package.json">

<violation number="1" location="package.json:21">
P2: Test script executes dist/tests/*.js but does not build first, so npm test will fail on clean checkouts where dist isn’t present.</violation>
</file>

<file name="errors.ts">

<violation number="1" location="errors.ts:72">
P2: Hardcoding the prototype to AgentKitError.prototype breaks subclass identity; subclasses will fail `instanceof` and lose their prototype chain.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P2: Duplicate SRB_PROVIDER_URL in .env.example creates ambiguous network selection and can override a user’s intended mainnet setting.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At .env.example, line 23:

<comment>Duplicate SRB_PROVIDER_URL in .env.example creates ambiguous network selection and can override a user’s intended mainnet setting.</comment>

<file context>
@@ -2,30 +2,31 @@
-# Set to 'true' to enable bridge operations on mainnet
-# WARNING: Bridge transactions are irreversible
+# RPC Provider URL for Soroban/Stellar
+SRB_PROVIDER_URL=https://soroban-testnet.stellar.org
+# ============================================
+# Required for mainnet bridging. Bridge transactions are irreversible.
</file context>

[cubic-dev-ai]

P2: Documentation marks CI as completed and references .github/workflows/ci.yml, but that workflow file is not present in the repository. This makes the release-readiness checklist inaccurate.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At docs/NEXT_STEPS.md, line 14:

<comment>Documentation marks CI as completed and references `.github/workflows/ci.yml`, but that workflow file is not present in the repository. This makes the release-readiness checklist inaccurate.</comment>

<file context>
@@ -0,0 +1,24 @@
+
+## 2. CI / Automation ✅
+
+- **GitHub Actions:** Already added (`.github/workflows/ci.yml`). Runs build, test, and `pnpm run docs:generate`.
+
+## 3. Documentation ✅
</file context>

[cubic-dev-ai]

P2: Broken documentation link: href points to media/api.md, but no such file exists in the repo/output, so users will hit a 404 from the API reference page.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At docs/api-reference/index.html, line 119:

<comment>Broken documentation link: href points to media/api.md, but no such file exists in the repo/output, so users will hit a 404 from the API reference page.</comment>

<file context>
@@ -0,0 +1,157 @@
+<a id="🪙-token-ıssuance-launchtoken" class="tsd-anchor"></a><h2 class="tsd-anchor-link">🪙 Token Issuance (launchToken)<a href="#🪙-token-ıssuance-launchtoken" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p>Create a classic Stellar asset: issuer account, trustline, and initial mint. Use <code>agent.launchToken()</code> with <code>assetCode</code>, <code>decimals</code>, <code>initialSupply</code>, and issuer/distributor keys. Mainnet issuance requires <code>allowMainnetTokenIssuance: true</code> and <code>ALLOW_MAINNET_TOKEN_ISSUANCE=true</code> in <code>.env</code>. See <code>docs/api.md</code> for parameters and error codes (e.g. <code>missing_trustline</code>, <code>invalid_params</code>).</p>
+<hr>
+<a id="📚-apı-reference" class="tsd-anchor"></a><h2 class="tsd-anchor-link">📚 API Reference<a href="#📚-apı-reference" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><ul>
+<li><strong>Summary:</strong> <a href="media/api.md">docs/api.md</a> — AgentClient methods, parameters, returns.</li>
+<li><strong>Generated docs:</strong> Run <code>pnpm run docs:generate</code> to build TypeDoc output.</li>
+</ul>
</file context>

[cubic-dev-ai]

P2: Non-native balance mapping assumes asset_code/asset_issuer are always present; Horizon balances can include liquidity_pool_shares with no asset_code/issuer, leading to undefined:undefined outputs and incorrect balance data.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At tools/account.ts, line 30:

<comment>Non-native balance mapping assumes asset_code/asset_issuer are always present; Horizon balances can include liquidity_pool_shares with no asset_code/issuer, leading to `undefined:undefined` outputs and incorrect balance data.</comment>

<file context>
@@ -0,0 +1,48 @@
+          return { asset: "XLM", balance: b.balance };
+        } else {
+          return {
+            asset: `${b.asset_code}:${b.asset_issuer}`,
+            balance: b.balance,
+            code: b.asset_code,
</file context>

[cubic-dev-ai]

P2: Security docs overstate protections by claiming env-level safeguards for all mainnet fund operations, but swap/LP only require allowMainnet in code.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At README.md, line 147:

<comment>Security docs overstate protections by claiming env-level safeguards for all mainnet fund operations, but swap/LP only require `allowMainnet` in code.</comment>

<file context>
@@ -1,352 +1,153 @@
-- Developers must consciously enable mainnet at both configuration and environment levels
-- Reduces risk of accidental mainnet bridging due to misconfiguration
-- Provides clear separation between general mainnet operations and high-risk bridge operations
+AgentKit implements a **Dual-Safeguard System** for all mainnet operations involving funds. Developers must consciously enable mainnet at both configuration (`AgentClient`) and environment (`.env`) levels.
 
 ---
</file context>

Suggested change

	AgentKit implements a **Dual-Safeguard System** for all mainnet operations involving funds. Developers must consciously enable mainnet at both configuration (`AgentClient`) and environment (`.env`) levels.
	AgentKit requires explicit `allowMainnet: true` configuration for mainnet operations; additional environment safeguards apply only to higher‑risk actions like bridging/token issuance (e.g., `ALLOW_MAINNET_BRIDGE`, `ALLOW_MAINNET_TOKEN_ISSUANCE`).

[cubic-dev-ai]

P2: Tool description now implies generic Stellar network support, but implementation is still testnet-only, which misleads callers about where funds are sent.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At tools/stellar.ts, line 8:

<comment>Tool description now implies generic Stellar network support, but implementation is still testnet-only, which misleads callers about where funds are sent.</comment>

<file context>
@@ -5,7 +5,7 @@ import * as StellarSdk from "stellar-sdk";
 export const stellarSendPaymentTool = new DynamicStructuredTool({
   name: "stellar_send_payment",
-  description: "Send a payment on the Stellar testnet. Requires recipient address and amount.",
+  description: "Send a direct payment (XLM) to another address on the Stellar network. Use this for simple peer-to-peer transfers or funding accounts. Requires a valid recipient 'G...' address and amount.",
   schema: z.object({
     recipient: z.string().describe("The Stellar address to send to"),
</file context>

Suggested change

	description: "Send a direct payment (XLM) to another address on the Stellar network. Use this for simple peer-to-peer transfers or funding accounts. Requires a valid recipient 'G...' address and amount.",
	description: "Send a payment on the Stellar testnet. Requires recipient address and amount.",

[cubic-dev-ai]

P2: GitHub Actions are referenced by mutable tags (@v4). Tags can be retargeted, so this workflow is exposed to supply‑chain changes. Pin actions to full commit SHAs for immutability and CI integrity.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At .github/workflows/ci.yml, line 13:

<comment>GitHub Actions are referenced by mutable tags (@v4). Tags can be retargeted, so this workflow is exposed to supply‑chain changes. Pin actions to full commit SHAs for immutability and CI integrity.</comment>

<file context>
@@ -0,0 +1,36 @@
+  build-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
</file context>

[cubic-dev-ai]

P2: Test script executes dist/tests/*.js but does not build first, so npm test will fail on clean checkouts where dist isn’t present.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At package.json, line 21:

<comment>Test script executes dist/tests/*.js but does not build first, so npm test will fail on clean checkouts where dist isn’t present.</comment>

<file context>
@@ -17,7 +17,9 @@
     "prepare": "npm run build",
-    "postbuild": "copyfiles index.d.ts dist/"
+    "postbuild": "copyfiles index.d.ts dist/",
+    "test": "node dist/tests/errors.test.js && node dist/tests/agentKitError.test.js && node dist/tests/buildTransaction.test.js && node dist/tests/contract-errors.test.js && node dist/tests/integration.test.js && node dist/tests/error-scenarios.test.js",
+    "docs:generate": "typedoc"
   },
</file context>

Suggested change

	"test": "node dist/tests/errors.test.js && node dist/tests/agentKitError.test.js && node dist/tests/buildTransaction.test.js && node dist/tests/contract-errors.test.js && node dist/tests/integration.test.js && node dist/tests/error-scenarios.test.js",
	"test": "npm run build && node dist/tests/errors.test.js && node dist/tests/agentKitError.test.js && node dist/tests/buildTransaction.test.js && node dist/tests/contract-errors.test.js && node dist/tests/integration.test.js && node dist/tests/error-scenarios.test.js",

[cubic-dev-ai]

P2: Hardcoding the prototype to AgentKitError.prototype breaks subclass identity; subclasses will fail instanceof and lose their prototype chain.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At errors.ts, line 72:

<comment>Hardcoding the prototype to AgentKitError.prototype breaks subclass identity; subclasses will fail `instanceof` and lose their prototype chain.</comment>

<file context>
@@ -0,0 +1,96 @@
+    this.code = code;
+    this.context = options?.context;
+    this.cause = options?.cause;
+    Object.setPrototypeOf(this, AgentKitError.prototype);
+  }
+}
</file context>

[cubic-dev-ai]

P3: Angle-bracket placeholder is parsed as HTML in Markdown and can be hidden in rendered views, making the required prompt insertion unclear.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At .agent/skills/hackathon-autopilot/templates/output_figma_flow.md, line 33:

<comment>Angle-bracket placeholder is parsed as HTML in Markdown and can be hidden in rendered views, making the required prompt insertion unclear.</comment>

<file context>
@@ -0,0 +1,33 @@
+
+### Figma/FigJam Prompt (copy-paste)
+
+<PUT PROMPT HERE>
</file context>